> ## 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 Divisas Fiat con Liquidación en Stablecoins
> Opera entre pares de divisas fiat usando stablecoins como puente de liquidación: BRL ↔ USD, USD ↔ EUR y nuevos corredores en SpherePay.
Usa SpherePay para facilitar el trading de divisas entre pares fiat usando stablecoins como capa de liquidación. El patrón es el mismo en todos los corredores — un "sándwich" de stablecoin enruta el trade a través de USDC (u otra stablecoin), con SpherePay manejando ambas piernas fiat.
Este es el patrón correcto para brókers de FX, plataformas de cambio de divisas, liquidación cross-currency B2B, y cualquier producto que necesite convertir un fiat en otro de forma rápida y predecible.
## El patrón, en una forma
Todos los corredores siguen el mismo modelo de tres pasos:
1. **On-ramp** (conversión de fiat a stablecoin) del fiat de origen a USDC.
2. **Bridge** del USDC entre redes si es necesario (de una billetera (`wallet`) a otra).
3. **Off-ramp** (conversión de stablecoin a fiat) de USDC al fiat de destino.
La implementación más limpia usa un [Offloader Wallet](/es/concepts/automation/offloader-wallets) para el paso 3 — Sphere convierte automáticamente USDC al fiat de destino y lo envía por wire a una cuenta bancaria, eliminando la necesidad de una segunda llamada a la API de transferencia.
Ambas piernas fiat requieren perfiles de verificación separados en el cliente (uno por divisa). Consulta cada corredor a continuación para los perfiles específicos requeridos.
## Corredores soportados
Expande un corredor a continuación para el tutorial de integración paso a paso completo.
El corredor más común de Sphere hoy. Mueve fondos entre Reales Brasileños (vía PIX) y Dólares Estadounidenses (vía wire o ACH) con USDC como divisa puente.
**Casos de uso comunes:**
* Pagos de importación/exportación — importadores brasileños pagando facturas en USD a proveedores internacionales, o exportadores recibiendo ingresos en USD.
* Repagos de préstamos — prestatarios con BRL sirviendo deuda denominada en USD.
* Transacciones inmobiliarias — compradores o vendedores en negocios de propiedad brasileña liquidando en USD.
* Remesas — remitentes brasileños, destinatarios en EE. UU.
### Requisitos previos
El cliente debe estar aprobado para **ambos** perfiles de verificación:
* `kyc_profile_a` / `kyb_profile_a` — requerido para transferencias USD
* `kyc_profile_b` / `kyb_profile_b` — requerido para transferencias BRL/PIX
Consulta [KYC Individual](/es/concepts/onboarding/individual-kyc) y [KYB Empresarial](/es/concepts/onboarding/business-kyb) para la configuración.
Pasar `"network": "sol"` en una transferencia BRL resultará en una solicitud rechazada. Usa `ethereum`, `polygon`, `arbitrum`, `base` o `avalanche` para USDC. USDT soporta `ethereum` o `tron`.
### Flujo
```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
```
### Paso 1 — Crear una cuenta bancaria 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"]
}
```
### Paso 2 — Crear un 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"
}
}
```
Guarda el `address` devuelto como `{{offloader_address}}`.
### Paso 3 — Registrar la dirección del Offloader como billetera
**POST** `https://api.spherepay.co/v2/wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"network": "polygon",
"address": "{{offloader_address}}"
}
```
Guarda el `id` devuelto como `{{wallet_id}}`. Los pasos 1–3 solo necesitan hacerse una vez por cliente — reutiliza `{{wallet_id}}` para todas las futuras transferencias BRL → USD.
### Paso 4 — Crear una cuenta bancaria 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` acepta `email`, `phone`, `cnpj` o `random`.
### Paso 5 — Crear la transferencia 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"
}
```
**Restricciones BRL:** `integratorBpsFeeRate` es obligatorio (comisiones fijas no soportadas), límites por transferencia R$1.00–R$7,500.00, Solana no soportado. Consulta [Rieles soportados](/es/concepts/transfers/supported-rails).
### Paso 6 — Financiar la transacción
La respuesta incluye un `instructions.pixKey` — preséntalo a tu usuario final. Una vez que envíe el BRL vía PIX:
1. Sphere recibe el BRL y lo convierte a USDC.
2. El USDC se entrega al Offloader Wallet.
3. El Offloader Wallet convierte automáticamente USDC a USD y lo envía por wire a la cuenta bancaria USD registrada.
### Dirección inversa — USD → BRL
Para la dirección opuesta, invierte el patrón: registra un Offloader Wallet BRL (USDC → BRL vía PIX), luego realiza el on-ramp de USD → USDC hacia él. Los mismos primitivos, el mismo número de llamadas API.
### Manejo de errores
| Escenario | Qué ocurre | Qué hacer |
| --------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------ |
| El on-ramp falla | BRL devuelto vía PIX. No se acuña USDC. | Reintentar o informar al usuario. |
| El on-ramp tiene éxito, falla la conversión del Offloader | USDC queda en el Offloader Wallet. No se envía USD. | Contactar soporte de SpherePay. |
| El cliente envía el monto PIX incorrecto | USDC parcial o excedente llega al Offloader Wallet. | La billetera convierte lo que llegue — concilia por tu lado. |
Convierte entre Dólares Estadounidenses (vía ACH o wire) y Euros (vía SEPA) con USDC o EURC como puente. SEPA liquida el mismo/siguiente día hábil; SEPA Instant es casi instantáneo donde está soportado.
**Casos de uso comunes:**
* Importadores estadounidenses pagando proveedores europeos.
* Plataformas europeas aceptando ingresos en USD y liquidando en EUR.
* Tesorería cross-border — empresas que operan en ambas regiones gestionando exposición a FX.
* Brókers de FX ofreciendo conversión retail USD/EUR.
### Requisitos previos
El cliente debe estar aprobado para perfiles de verificación de USD y EUR. Ambos rieles fiat caen bajo `kyc_profile_a` / `kyb_profile_a` (no se necesita un perfil separado para EUR, a diferencia del BRL).
Todas las redes USDC estándar están soportadas, incluida Solana. Para EURC, las redes soportadas son Base, Ethereum y Solana.
### Flujo
```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
```
### Paso 1 — Crear una cuenta bancaria 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"]
}
```
Usa `sepaInstant` en `networks` si necesitas liquidación casi instantánea y el banco receptor lo soporta.
### Paso 2 — Crear un 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"
}
}
```
Elige la red de origen según dónde recibirás USDC. Solana es la más barata y rápida; Ethereum y Base son comunes para flujos institucionales.
Guarda el `address` devuelto como `{{offloader_address}}`.
### Paso 3 — Registrar la dirección del Offloader como billetera
**POST** `https://api.spherepay.co/v2/wallet`
```json theme={"dark"}
{
"customerId": "{{customer_id}}",
"network": "ethereum",
"address": "{{offloader_address}}"
}
```
Guarda el `id` devuelto como `{{wallet_id}}`.
### Paso 4 — Crear una cuenta bancaria 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"]
}
```
### Paso 5 — Crear la transferencia 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"
}
}
```
Elige `wire` para transferencias grandes o internacionales; `ach` es la opción más económica para transferencias domésticas en EE. UU. y se envía el mismo día de forma predeterminada.
### Paso 6 — Liquidación
Una vez que el USD llega a SpherePay:
1. Sphere convierte USD → USDC.
2. El USDC se entrega al Offloader Wallet.
3. El Offloader Wallet convierte automáticamente USDC → EUR y lo envía vía SEPA.
Tiempo total: minutos (wire) a \~1 día hábil (ACH + SEPA), dependiendo de las opciones de riel.
### Dirección inversa — EUR → USD
Mismos primitivos, invertidos. Registra un Offloader Wallet USD (USDC → USD), realiza el on-ramp de EUR → USDC hacia él.
### Usar EURC en lugar de USDC
Para flujos con mucho EUR, EURC puede reducir el deslizamiento. Establece `currency: "eurc"` y `network` como uno de `base`, `ethereum` o `solana` en el Offloader Wallet. La divisa puente se convierte en EURC en lugar de USDC; el resto de la integración es idéntico.
## Qué manejas tú vs. qué maneja SpherePay
| Responsabilidad | Propietario |
| ---------------------------------------------------------- | -------------------------------- |
| Crear el cliente, cuentas bancarias y objetos de billetera | Tú (integrador) |
| Crear y gestionar el Offloader Wallet | Tú (integrador) |
| Iniciar la transferencia on-ramp | Tú (integrador) |
| Cobro de fiat y conversión fiat de origen → USDC | SpherePay |
| Conversión USDC → fiat de destino y liquidación | SpherePay (vía Offloader Wallet) |
| Manejo de fallos en cualquiera de las piernas | Tú (integrador) |
## Restricciones comunes a todos los corredores
* Cada pierna se factura como una transferencia (`transfer`) separada.
* Los Offloader Wallets no soportan webhooks hoy — consulta `GET /v2/transfer/{id}` para rastrear el estado del on-ramp.
* Tanto los perfiles de verificación de fiat de origen como de destino deben estar aprobados antes de que se pueda iniciar cualquier transferencia.
## De cara al futuro — transferencias cross-currency de una sola llamada
Hoy cada corredor requiere configurar un Offloader Wallet más una llamada separada de transferencia on-ramp. SpherePay está trabajando hacia una API de **transferencia cross-currency de una sola llamada** que abstrae completamente el salto de stablecoin — enviarías una solicitud con las divisas de origen y destino, y SpherePay manejaría el enrutamiento internamente. Cuando eso se lance, los patrones de esta guía seguirán funcionando, pero tendrás la opción de consolidar a una sola llamada.
## Relacionado
Cómo funciona la conversión automatizada de stablecoin a fiat.
Referencia completa de creación y seguimiento de transferencias.
Compatibilidad de divisas, redes y rieles por moneda.
Patrones de pago comercial con múltiples partes.