> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Trading de Moedas Fiat com Liquidação em Stablecoin
> Faça trading entre pares de moedas fiat usando stablecoins como ponte de liquidação: BRL ↔ USD, USD ↔ EUR e novos corredores no SpherePay.
Use o SpherePay para facilitar trading de moedas entre pares fiat usando stablecoins como camada de liquidação. O padrão é o mesmo em todos os corredores — um "sanduíche" de stablecoin roteia o trade através de USDC (ou outra stablecoin), com o SpherePay cuidando de ambas as pernas fiat.
Este é o padrão correto para corretoras de câmbio, plataformas de câmbio de moedas, liquidação de câmbio B2B e qualquer produto que precise converter um fiat em outro de forma rápida e previsível.
## O padrão em um só modelo
Cada corredor abaixo segue o mesmo modelo de três etapas:
1. **On-ramp** do fiat de origem para USDC.
2. **Bridge** do USDC entre redes se necessário (de uma carteira para outra).
3. **Off-ramp** do USDC para o fiat de destino.
A implementação mais limpa usa um [Offloader Wallet](/pt-BR/concepts/automation/offloader-wallets) para a etapa 3 — o Sphere converte automaticamente USDC para o fiat de destino e envia por wire para uma conta bancária, eliminando a necessidade de uma segunda chamada de API de transferência.
Ambas as pernas fiat requerem perfis de verificação separados no cliente (um por moeda). Consulte cada corredor abaixo para os perfis específicos necessários.
## Corredores suportados
Expanda um corredor abaixo para o tutorial completo de integração passo a passo.
O corredor mais comum do Sphere hoje. Move fundos entre Reais Brasileiros (via PIX) e Dólares Americanos (via wire ou ACH) com USDC como moeda de ponte.
**Casos de uso comuns:**
* Pagamentos de importação/exportação — importadores brasileiros pagando faturas USD a fornecedores internacionais, ou exportadores recebendo receitas em USD.
* Pagamentos de empréstimos — devedores com BRL pagando dívidas denominadas em USD.
* Transações imobiliárias — compradores ou vendedores em negócios imobiliários brasileiros liquidando em USD.
* Remessas — remetentes brasileiros, destinatários nos EUA.
### Pré-requisitos
O cliente deve ser aprovado em **ambos** os perfis de verificação:
* `kyc_profile_a` / `kyb_profile_a` — obrigatório para transferências USD
* `kyc_profile_b` / `kyb_profile_b` — obrigatório para transferências BRL/PIX
Consulte [KYC Individual](/pt-BR/concepts/onboarding/individual-kyc) e [KYB Empresarial](/pt-BR/concepts/onboarding/business-kyb) para configuração.
Passar `"network": "sol"` em uma transferência BRL resultará em uma requisição rejeitada. Use `ethereum`, `polygon`, `arbitrum`, `base` ou `avalanche` para USDC. USDT suporta `ethereum` ou `tron`.
### Fluxo
```mermaid theme={"dark"}
sequenceDiagram
participant U as End user
participant I as Your integration
participant S as SpherePay
participant P as PIX network
participant B as USD bank
I->>S: POST /v2/bank-account (USD)
S-->>I: usdBankAccountId
I->>S: POST /v2/offloader-wallet (USDC → USD)
S-->>I: offloaderWallet.address
I->>S: POST /v2/wallet (register offloader address)
S-->>I: walletId
I->>S: POST /v2/bank-account (BRL + PIX key)
S-->>I: brlBankAccountId
I->>S: POST /v2/transfer (BRL → USDC on-ramp)
S-->>I: transferId, instructions.pixKey
I->>U: Present PIX payment instructions
U->>P: Send BRL via PIX
P->>S: BRL received
Note over S: Convert BRL → USDC, deliver to Offloader Wallet
Note over S: Offloader Wallet auto-converts USDC → USD
S->>B: Settle USD via wire
```
### Etapa 1 — Criar uma conta bancária USD
**POST** `https://api.spherepay.co/v2/bank-account`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"bankName": "Chase",
"accountName": "My USD Account",
"accountOwner": "Alice Johnson",
"currency": "usd",
"accountDetails": {
"accountNumber": "1234567890",
"routingNumber": "021000021",
"accountType": "checking"
},
"networks": ["wire"]
}
```
### Etapa 2 — Criar um Offloader Wallet
**POST** `https://api.spherepay.co/v2/offloader-wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"currency": "usdc",
"network": "polygon",
"destination": {
"bankAccountId": "{{usd_bank_account_id}}",
"currency": "usd",
"network": "wire"
}
}
```
Armazene o `address` retornado como `{{offloader_address}}`.
### Etapa 3 — Registrar o endereço do Offloader como carteira
**POST** `https://api.spherepay.co/v2/wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"network": "polygon",
"address": "{{offloader_address}}"
}
```
Armazene o `id` retornado como `{{wallet_id}}`. As etapas 1–3 só precisam ser feitas uma vez por cliente — reutilize `{{wallet_id}}` para todas as transferências futuras de BRL → USD.
### Etapa 4 — Criar uma conta bancária BRL
**POST** `https://api.spherepay.co/v2/bank-account`
```json theme={"dark"}
{
"currency": "brl",
"bankName": "Banco do Brasil",
"accountName": "My BRL Account",
"accountDetails": {
"pixKey": "alice@example.com",
"pixKeyType": "email"
},
"accountOwner": {
"accountHolderName": "Alice Johnson",
"address": {
"line1": "Rua das Flores 123",
"city": "São Paulo",
"state": "SP",
"postalCode": "01310-100",
"country": "BRA"
}
},
"networks": ["pix"]
}
```
`pixKeyType` aceita `email`, `phone`, `cnpj` ou `random`.
### Etapa 5 — Criar a transferência BRL → USDC
**POST** `https://api.spherepay.co/v2/transfer`
```json theme={"dark"}
{
"customer": "{{customer_id}}",
"amount": "100.00",
"source": {
"type": "bank_account",
"id": "{{brl_bank_account_id}}",
"currency": "brl",
"network": "pix"
},
"destination": {
"type": "wallet",
"id": "{{wallet_id}}",
"currency": "usdc",
"network": "polygon"
},
"integratorBpsFeeRate": "50"
}
```
**Restrições BRL:** `integratorBpsFeeRate` é obrigatório (taxas fixas não suportadas), limites por transferência R$ 1,00–R$ 7.500,00, Solana não suportada. Consulte [Rails suportados](/pt-BR/concepts/transfers/supported-rails).
### Etapa 6 — Financiar a transação
A resposta inclui um `instructions.pixKey` — apresente-o ao seu usuário final. Assim que ele enviar o BRL via PIX:
1. O Sphere recebe o BRL e o converte para USDC.
2. USDC é entregue ao Offloader Wallet.
3. O Offloader Wallet converte automaticamente USDC para USD e envia por wire para a conta bancária USD registrada.
### Direção inversa — USD → BRL
Para a direção oposta, inverta o padrão: registre um Offloader Wallet BRL (USDC → BRL via PIX), depois faça on-ramp de USD → USDC nele. Mesmos primitivos, mesmo número de chamadas de API.
### Tratamento de erros
| Cenário | O que acontece | O que fazer |
| ------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| On-ramp falha | BRL devolvido via PIX. Nenhum USDC emitido. | Tente novamente ou exiba ao usuário. |
| On-ramp tem sucesso, conversão do Offloader falha | USDC fica no Offloader Wallet. Nenhum USD enviado. | Entre em contato com o suporte SpherePay. |
| Cliente envia valor PIX errado | USDC parcial ou em excesso chega ao Offloader Wallet. | A carteira converte o que chegar — reconcilie do seu lado. |
Converta entre Dólares Americanos (via ACH ou wire) e Euros (via SEPA) com USDC ou EURC como ponte. O SEPA liquida no mesmo/próximo dia útil; o SEPA Instant é quase instantâneo onde suportado.
**Casos de uso comuns:**
* Importadores americanos pagando fornecedores europeus.
* Plataformas europeias aceitando receita em USD e liquidando em EUR.
* Tesouraria internacional — empresas operando em ambas as regiões gerenciando exposição cambial.
* Corretoras de câmbio oferecendo conversão de USD/EUR para varejo.
### Pré-requisitos
O cliente deve ser aprovado em ambos os perfis de verificação USD e EUR. Ambos os rails fiat se enquadram em `kyc_profile_a` / `kyb_profile_a` (nenhum perfil separado é necessário para EUR, ao contrário do BRL).
Todas as redes USDC padrão são suportadas, incluindo Solana. Para EURC, as redes suportadas são Base, Ethereum e Solana.
### Fluxo
```mermaid theme={"dark"}
sequenceDiagram
participant U as End user
participant I as Your integration
participant S as SpherePay
participant USB as USD bank
participant EUB as EUR bank
I->>S: POST /v2/bank-account (EUR + SEPA)
S-->>I: eurBankAccountId
I->>S: POST /v2/offloader-wallet (USDC → EUR)
S-->>I: offloaderWallet.address
I->>S: POST /v2/wallet (register offloader)
S-->>I: walletId
I->>S: POST /v2/bank-account (USD)
S-->>I: usdBankAccountId
I->>S: POST /v2/transfer (USD → USDC on-ramp)
USB-->>S: USD received via ACH/wire
Note over S: Convert USD → USDC, deliver to Offloader Wallet
Note over S: Offloader auto-converts USDC → EUR
S->>EUB: Settle EUR via SEPA
```
### Etapa 1 — Criar uma conta bancária EUR
**POST** `https://api.spherepay.co/v2/bank-account`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"bankName": "Deutsche Bank",
"accountName": "EUR settlement",
"accountOwner": "Acme GmbH",
"currency": "eur",
"accountDetails": {
"iban": "DE89370400440532013000",
"bic": "DEUTDEFFXXX"
},
"networks": ["sepa"]
}
```
Use `sepaInstant` em `networks` se precisar de liquidação quase instantânea e o banco destinatário suportar.
### Etapa 2 — Criar um Offloader Wallet para USDC → EUR
**POST** `https://api.spherepay.co/v2/offloader-wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"currency": "usdc",
"network": "ethereum",
"destination": {
"bankAccountId": "{{eur_bank_account_id}}",
"currency": "eur",
"network": "sepa"
}
}
```
Escolha a rede de origem com base em onde você receberá USDC. Solana é a mais barata e rápida; Ethereum e Base são comuns para fluxos institucionais.
Armazene o `address` retornado como `{{offloader_address}}`.
### Etapa 3 — Registrar o endereço do Offloader como carteira
**POST** `https://api.spherepay.co/v2/wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"network": "ethereum",
"address": "{{offloader_address}}"
}
```
Armazene o `id` retornado como `{{wallet_id}}`.
### Etapa 4 — Criar uma conta bancária USD
**POST** `https://api.spherepay.co/v2/bank-account`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"bankName": "Chase",
"accountName": "USD source",
"accountOwner": "Acme Inc",
"currency": "usd",
"accountDetails": {
"accountNumber": "1234567890",
"routingNumber": "021000021",
"accountType": "checking"
},
"networks": ["ach", "wire"]
}
```
### Etapa 5 — Criar a transferência USD → USDC
**POST** `https://api.spherepay.co/v2/transfer`
```json theme={"dark"}
{
"customer": "{{customer_id}}",
"amount": "10000.00",
"source": {
"type": "bank_account",
"id": "{{usd_bank_account_id}}",
"currency": "usd",
"network": "wire"
},
"destination": {
"type": "wallet",
"id": "{{wallet_id}}",
"currency": "usdc",
"network": "ethereum"
}
}
```
Escolha `wire` para transferências grandes ou internacionais; `ach` é a opção mais barata para transferências domésticas nos EUA e é enviada no mesmo dia por padrão.
### Etapa 6 — Liquidação
Assim que USD chegar ao SpherePay:
1. O Sphere converte USD → USDC.
2. USDC é entregue ao Offloader Wallet.
3. O Offloader Wallet converte automaticamente USDC → EUR e envia via SEPA.
Tempo total: minutos (wire) a \~1 dia útil (ACH + SEPA), dependendo das escolhas de rail.
### Direção inversa — EUR → USD
Mesmos primitivos, invertidos. Registre um Offloader Wallet USD (USDC → USD), faça on-ramp de EUR → USDC nele.
### Usando EURC em vez de USDC
Para fluxos pesados em EUR, o EURC pode reduzir o slippage. Defina `currency: "eurc"` e `network` para um de `base`, `ethereum` ou `solana` no Offloader Wallet. A moeda de ponte passa a ser EURC em vez de USDC; o resto da integração é idêntico.
## O que você cuida vs. o que o SpherePay cuida
| Responsabilidade | Responsável |
| ------------------------------------------------------ | -------------------------------- |
| Criar os objetos de cliente, conta bancária e carteira | Você (integrador) |
| Criar e gerenciar o Offloader Wallet | Você (integrador) |
| Iniciar a transferência de on-ramp | Você (integrador) |
| Coleta de fiat e conversão de fiat de origem para USDC | SpherePay |
| Conversão de USDC para fiat de destino e liquidação | SpherePay (via Offloader Wallet) |
| Tratamento de falhas em qualquer perna | Você (integrador) |
## Restrições comuns a todos os corredores
* Cada perna é cobrada como uma transferência separada.
* Offloader Wallets não suportam webhooks atualmente — consulte `GET /v2/transfer/{id}` para rastrear o status do on-ramp.
* Os perfis de verificação do fiat de origem e destino devem estar aprovados antes de qualquer transferência ser iniciada.
## Perspectiva — transferências de câmbio com uma única chamada
Hoje cada corredor requer configurar um Offloader Wallet mais uma chamada separada de API de transferência on-ramp. O SpherePay está trabalhando para uma **API de transferência de câmbio com uma única chamada** que abstrai completamente o salto de stablecoin — você enviaria uma requisição com as moedas de origem e destino, e o SpherePay cuidaria do roteamento internamente. Quando isso for lançado, os padrões neste guia ainda funcionarão, mas você terá a opção de consolidar para uma única chamada.
## Relacionados
Como funciona a conversão automática de stablecoin para fiat.
Referência completa de criação e rastreamento de transferências.
Compatibilidade de rede e rail por moeda.
Padrões de pagamento multipartidário.