> ## 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.
# Transfers API: On-Ramp and Off-Ramp Guide
> Create on-ramp and off-ramp transfers with the SpherePay Transfers API. Covers integration workflow, request examples for USD and BRL/PIX, and status tracking.
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`.
Transfers can support multiple business models. Before implementation, confirm whether the movement is [first-party](/implementation-guides/first-party-flows) or [third-party](/implementation-guides/third-party-flows) so you can identify the correct customer of record, source, destination, and required payment data.
## 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](/widget/overview) 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
Complete KYC (individuals) or KYB (businesses) before any transfer can be created. The customer's verification profile must be `approved`. See [Customers & Onboarding](/concepts/onboarding/overview).
Register the bank account and wallet that will be used as the source and destination for the transfer.
* Bank accounts: [POST /v2/bank-account](/concepts/transfers/bank-accounts)
* Wallets: [POST /v2/wallet](/concepts/transfers/wallets)
Call `POST /v2/transfer` with the customer, amount, source, and destination. See full examples below.
Poll `GET /v2/transfer/{id}` until the transfer reaches a terminal state (`succeeded`, `failed`, `refunded`, etc.). See [Transfer Lifecycle](/concepts/transfers/lifecycle).
## Transfer creation
`POST https://api.spherepay.co/v2/transfer`
Use the tabs below to see request bodies for each supported transfer direction.
Sends USD from a bank account via ACH and delivers USDC to an Ethereum wallet.
```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"
}
}'
```
Sends USDC from an Ethereum wallet and delivers USD to a bank account 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"
}
}'
```
Sends BRL from a PIX bank account and delivers USDC to a Polygon wallet.
```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"
}'
```
Sends USDC from a Polygon wallet and delivers BRL to a PIX bank account.
```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"
}'
```
### Response
A successful request returns a transfer object with an `id`, `type`, and initial `status`:
```json theme={"dark"}
{
"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](/api-reference/transfer/get) 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](/api-reference/transfer/get-id) 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](/concepts/transfers/lifecycle) for the full status reference.