Transfers API: On-Ramp and Off-Ramp Guide

The Transfers API lets you create on-ramp and off-ramp transfers for your customers and track their lifecycle from creation to completion or failure. An on-ramp converts fiat currency (USD, EUR, BRL) into a stablecoin (USDC, USDT, EURC) deposited to a blockchain wallet. An off-ramp does the reverse — it converts stablecoin into fiat and delivers it to a bank account. Both directions use the same POST /v2/transfer endpoint; the direction is determined by what you set as source and destination.

When to use the Transfers API

Use the Transfers API when you want to embed transfers directly into your product and control your own UX. You initiate each transfer explicitly, and SpherePay returns unique deposit instructions per request — the customer sends funds to those instructions, and SpherePay matches the memo to process it. If you want a pre-built, hosted experience with no frontend work, use the Ramp Widget instead.

	Transfers API	Ramp Widget
Control	Full — you initiate and track every transfer	Minimal — SpherePay hosts the UX
UX ownership	Your product	SpherePay-hosted widget
Best for	Custom integrations, programmatic flows	Quick embeds, prototypes

Integration overview

Onboard the customer

Complete KYC (individuals) or KYB (businesses) before any transfer can be created. The customer’s verification profile must be approved. See Customers & Onboarding.

Create funding instruments

Bank accounts: POST /v2/bank-account
Wallets: POST /v2/wallet

Create a transfer

Call POST /v2/transfer with the customer, amount, source, and destination. See full examples below.

Track status and handle outcomes

Poll GET /v2/transfer/{id} until the transfer reaches a terminal state (succeeded, failed, refunded, etc.). See Transfer Lifecycle.

Transfer creation

POST https://api.spherepay.co/v2/transfer Use the tabs below to see request bodies for each supported transfer direction.

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

Sends USD from a bank account via ACH and delivers USDC to an Ethereum wallet.

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"
    }
  }'

Sends USDC from an Ethereum wallet and delivers USD to a bank account 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"
    }
  }'

Sends BRL from a PIX bank account and delivers USDC to a Polygon wallet.

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"
  }'

Sends USDC from a Polygon wallet and delivers BRL to a PIX bank account.

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"
  }'

Response

A successful request returns a transfer object with an id, type, and initial status:

{
  "id": "payout_1234567890abcdef12345678",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_123abc..."
}

Store the id — you will use it to poll for status updates.

BRL/PIX transfer constraints

BRL transfers use Brazil’s PIX instant payment network and are subject to additional rules beyond standard USD/EUR transfers. Transfer limits

On-ramp (PIX BRL → USDC/USDT): R $1.00 – R$ 7,500.00 per transfer
Off-ramp (USDC/USDT → PIX BRL): $1.00 –$ 7,500.00 (stablecoin units, approximately 1:1 with USD)

Limits may be increased based on due diligence. Contact your SpherePay representative for details. Supported wallet networks BRL transfers support polygon, ethereum, base, and tron. Solana is not supported for BRL transfers — requests that pass "network": "sol" will be rejected. Supported stablecoins

Stablecoin	Polygon	Ethereum	Base	Tron
USDC	✅	✅	✅	—
USDT	✅	✅	—	✅

USDT on Base and USDC on Tron are not supported for BRL transfers.

Fee parameter Only integratorBpsFeeRate (basis points) is accepted for BRL transfers. integratorFixedFee is not allowed because fees are collected on the stablecoin side, and a fiat-denominated fixed fee would require cross-currency conversion. Verification profile BRL transfers require a separate verification profile (kyc_profile_b for individuals, kyb_profile_b for businesses) in addition to the standard profile. Contact your SpherePay representative to enable access.

Track transfers

List all transfers

GET https://api.spherepay.co/v2/transfer Returns a paginated list of transfers for your account. See the List Transfers API reference for query parameters and response shape.

Retrieve a transfer by ID

GET https://api.spherepay.co/v2/transfer/{id} Returns the current state of a single transfer. Poll this endpoint to track progress. See the Get a Transfer API reference for the full response schema.

Poll GET /v2/transfer/{id} after creation and after each status update until the transfer reaches a terminal state: succeeded, refunded, failed, or canceled. See Transfer Lifecycle for the full status reference.

Overview

Onboarding

Transfers

Automation

Reference data

Operational

Transfers API: On-Ramp and Off-Ramp Guide

When to use the Transfers API

Integration overview

Transfer creation

Response

BRL/PIX transfer constraints

Track transfers

List all transfers

Retrieve a transfer by ID

Overview

Onboarding

Transfers

Automation

Reference data

Operational

Documentation Index

​When to use the Transfers API

​Integration overview

​Transfer creation

​Response

​BRL/PIX transfer constraints

​Track transfers

​List all transfers

​Retrieve a transfer by ID

When to use the Transfers API

Integration overview

Transfer creation

Response

BRL/PIX transfer constraints

Track transfers

List all transfers

Retrieve a transfer by ID