> ## 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. # API de Transferências: Guia de On-Ramp e Off-Ramp > Crie transferências de on-ramp e off-ramp com a API do SpherePay: fluxo de integração, exemplos em USD e BRL/PIX e acompanhamento de status. A API de Transferências permite criar transferências de on-ramp (conversão de fiat para stablecoin) e off-ramp (conversão de stablecoin para fiat) para seus clientes e acompanhar seu ciclo de vida desde a criação até a conclusão ou falha. Um on-ramp converte moeda fiat (USD, EUR, BRL) em uma stablecoin (USDC, USDT, EURC) depositada em uma carteira blockchain. Um off-ramp faz o inverso — converte stablecoin em fiat e entrega em uma conta bancária. Ambas as direções usam o mesmo endpoint `POST /v2/transfer`; a direção é determinada pelo que você define como `source` e `destination`. As transferências podem suportar múltiplos modelos de negócio. Antes da implementação, confirme se o movimento é [próprio (first-party)](/pt-BR/implementation-guides/first-party-flows) ou [de terceiros (third-party)](/pt-BR/implementation-guides/third-party-flows) para identificar o cliente de registro correto, origem, destino e dados de pagamento necessários. ## Quando usar a API de Transferências Use a API de Transferências quando quiser incorporar transferências diretamente no seu produto e controlar sua própria UX. Você inicia cada transferência explicitamente, e o SpherePay retorna instruções de depósito exclusivas por requisição — o cliente envia fundos para essas instruções, e o SpherePay faz a correspondência do memo para processá-la. Se você quiser uma experiência pré-construída e hospedada sem trabalho de frontend, use o [Ramp Widget](/widget/overview). | | API de Transferências | Ramp Widget | | --------------------- | ------------------------------------------------- | --------------------------------- | | **Controle** | Total — você inicia e rastreia cada transferência | Mínimo — o SpherePay hospeda a UX | | **Propriedade da UX** | Seu produto | Widget hospedado pelo SpherePay | | **Melhor para** | Integrações personalizadas, fluxos programáticos | Incorporações rápidas, protótipos | ## Visão geral da integração Complete o KYC (pessoas físicas) ou KYB (empresas) antes de qualquer transferência ser criada. O perfil de verificação do cliente deve estar `approved`. Consulte [Clientes e Onboarding](/pt-BR/concepts/onboarding/overview). Registre a conta bancária e a carteira que serão usadas como origem e destino para a transferência. * Contas bancárias: [POST /v2/bank-account](/pt-BR/concepts/transfers/bank-accounts) * Carteiras: [POST /v2/wallet](/pt-BR/concepts/transfers/wallets) Chame `POST /v2/transfer` com o cliente, valor, origem e destino. Veja exemplos completos abaixo. Consulte `GET /v2/transfer/{id}` até a transferência atingir um estado terminal (`succeeded`, `failed`, `refunded`, etc.). Consulte [Ciclo de Vida da Transferência](/pt-BR/concepts/transfers/lifecycle). ## Criação de transferência `POST https://api.spherepay.co/v2/transfer` Use as abas abaixo para ver corpos de requisição para cada direção de transferência suportada. Envia USD de uma conta bancária via ACH e entrega USDC em uma carteira Ethereum. ```bash theme={"dark"} curl -X POST https://api.spherepay.co/v2/transfer \ -H "Authorization: Bearer {{api_key}}" \ -H "Content-Type: application/json" \ -d '{ "amount": "100.00", "customer": "{{customer_id}}", "source": { "type": "bank_account", "id": "{{bank_account_id}}", "currency": "usd", "network": "ach" }, "destination": { "type": "wallet", "id": "{{wallet_id}}", "currency": "usdc", "network": "ethereum" } }' ``` Envia USDC de uma carteira Ethereum e entrega USD em uma conta bancária via ACH. ```bash theme={"dark"} curl -X POST https://api.spherepay.co/v2/transfer \ -H "Authorization: Bearer {{api_key}}" \ -H "Content-Type: application/json" \ -d '{ "amount": "100.00", "customer": "{{customer_id}}", "source": { "type": "wallet", "id": "{{wallet_id}}", "currency": "usdc", "network": "ethereum" }, "destination": { "type": "bank_account", "id": "{{bank_account_id}}", "currency": "usd", "network": "ach" } }' ``` Envia BRL de uma conta bancária PIX e entrega USDC em uma carteira Polygon. ```bash theme={"dark"} curl -X POST https://api.spherepay.co/v2/transfer \ -H "Authorization: Bearer {{api_key}}" \ -H "Content-Type: application/json" \ -d '{ "amount": "500.00", "customer": "{{customer_id}}", "source": { "type": "bank_account", "id": "{{bank_account_id}}", "currency": "brl", "network": "pix" }, "destination": { "type": "wallet", "id": "{{wallet_id}}", "currency": "usdc", "network": "polygon" }, "integratorBpsFeeRate": "50" }' ``` Envia USDC de uma carteira Polygon e entrega BRL em uma conta bancária PIX. ```bash theme={"dark"} curl -X POST https://api.spherepay.co/v2/transfer \ -H "Authorization: Bearer {{api_key}}" \ -H "Content-Type: application/json" \ -d '{ "amount": "500.00", "customer": "{{customer_id}}", "source": { "type": "wallet", "id": "{{wallet_id}}", "currency": "usdc", "network": "polygon" }, "destination": { "type": "bank_account", "id": "{{bank_account_id}}", "currency": "brl", "network": "pix" }, "integratorBpsFeeRate": "50" }' ``` ### Resposta Uma requisição bem-sucedida retorna um objeto de transferência com um `id`, `type` e `status` inicial: ```json theme={"dark"} { "id": "payout_1234567890abcdef12345678", "type": "on_ramp", "status": "pendingFunding", "customer": "customer_123abc..." } ``` Armazene o `id` — você o usará para consultar atualizações de status. ## Restrições de transferências BRL/PIX Transferências em BRL usam a rede de pagamentos instantâneos PIX do Brasil e estão sujeitas a regras adicionais além das transferências padrão em USD/EUR. **Limites de transferência** * On-ramp (PIX BRL → USDC/USDT): R$ 1,00 – R$ 7.500,00 por transferência * Off-ramp (USDC/USDT → PIX BRL): US$ 1,00 – US$ 7.500,00 (unidades de stablecoin, aproximadamente 1:1 com USD) Os limites podem ser aumentados com base em due diligence. Entre em contato com seu representante SpherePay para detalhes. **Redes de carteira suportadas** Transferências em BRL suportam `polygon`, `ethereum`, `base` e `tron`. Solana **não é suportada** para transferências em BRL — requisições que passarem `"network": "sol"` serão rejeitadas. **Stablecoins suportadas** | Stablecoin | Polygon | Ethereum | Base | Tron | | ---------- | ------- | -------- | ---- | ---- | | USDC | ✅ | ✅ | ✅ | — | | USDT | ✅ | ✅ | — | ✅ | USDT na Base e USDC na Tron não são suportados para transferências em BRL. **Parâmetro de taxa** Apenas `integratorBpsFeeRate` (pontos base) é aceito para transferências em BRL. `integratorFixedFee` não é permitido porque as taxas são coletadas no lado da stablecoin, e uma taxa fixa denominada em fiat exigiria conversão entre moedas. **Perfil de verificação** Transferências em BRL requerem um perfil de verificação separado (`kyc_profile_b` para pessoas físicas, `kyb_profile_b` para empresas) além do perfil padrão. Entre em contato com seu representante SpherePay para habilitar o acesso. ## Rastrear transferências ### Listar todas as transferências `GET https://api.spherepay.co/v2/transfer` Retorna uma lista paginada de transferências para sua conta. Consulte a [referência da API de Listagem de Transferências](/pt-BR/api-reference/transfer/get) para parâmetros de consulta e formato de resposta. ### Recuperar uma transferência por ID `GET https://api.spherepay.co/v2/transfer/{id}` Retorna o estado atual de uma única transferência. Consulte este endpoint para rastrear o progresso. Consulte a [referência da API de Obter uma Transferência](/pt-BR/api-reference/transfer/get-id) para o esquema completo de resposta. Consulte `GET /v2/transfer/{id}` após a criação e após cada atualização de status até a transferência atingir um estado terminal: `succeeded`, `refunded`, `failed` ou `canceled`. Consulte [Ciclo de Vida da Transferência](/pt-BR/concepts/transfers/lifecycle) para a referência completa de status.