API de Transferências: Guia de On-Ramp e Off-Ramp

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) ou de terceiros (third-party) 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.

	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

Cadastrar o cliente

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.

Criar instrumentos de financiamento

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
Carteiras: POST /v2/wallet

Criar uma transferência

Chame POST /v2/transfer com o cliente, valor, origem e destino. Veja exemplos completos abaixo.

Rastrear status e tratar resultados

Consulte GET /v2/transfer/{id} até a transferência atingir um estado terminal (succeeded, failed, refunded, etc.). Consulte Ciclo de Vida da Transferência.

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.

On-ramp (USD)
Off-ramp (USD)
On-ramp (BRL/PIX)
Off-ramp (BRL/PIX)

Envia USD de uma conta bancária via ACH e entrega USDC em uma carteira Ethereum.

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.

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.

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.

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:

{
  "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 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 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 para a referência completa de status.

​Quando usar a API de Transferências

​Visão geral da integração

​Criação de transferência

​Resposta

​Restrições de transferências BRL/PIX

​Rastrear transferências

​Listar todas as transferências

​Recuperar uma transferência por ID

Quando usar a API de Transferências

Visão geral da integração

Criação de transferência

Resposta

Restrições de transferências BRL/PIX

Rastrear transferências

Listar todas as transferências

Recuperar uma transferência por ID