Skip to main content

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.

Use this endpoint to initiate a money movement for a verified customer. SpherePay supports two transfer directions: on-ramp (fiat → crypto) and off-ramp (crypto → fiat). You define the direction by the types you supply for source and destination — a bank_account source with a wallet destination creates an on-ramp, and the reverse creates an off-ramp. The response includes deposit instructions your customer needs to fund the transfer.
The customer must have an approved verification profile before you can create a transfer on their behalf.

​
Endpoint

POST https://api.spherepay.co/v2/transfer

​
Authentication

All requests require a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request body

​
Standard transfer (floating rate)

​
amount
string
required
Transfer amount in the source currency. Must have exactly 2 decimal places (e.g. "250.00"). For BRL transfer limits, see BRL/PIX transfer constraints.
​
customer
string
required
The customer’s ID. Must match ^customer_[a-z0-9]+$.
​
source
object
required
Describes where funds originate. Use bank_account for on-ramp transfers, wallet for off-ramp transfers.
​
destination
object
required
Describes where funds are delivered. Use wallet for on-ramp transfers, bank_account for off-ramp transfers.
​
integratorFixedFee
string
Fixed fee amount in the source currency, with exactly 2 decimal places. Not supported for BRL transfers — use integratorBpsFeeRate instead.
​
integratorBpsFeeRate
string
Integrator fee rate in basis points, expressed as an integer string (e.g. "10" = 10 bps = 0.10%). This is the only fee mechanism supported for BRL transfers.
​
externalId
string
Your own reference identifier for this transfer. Not enforced as unique by SpherePay.

​
Transfer with quote

If you created a quote beforehand to lock an exchange rate, provide quoteId and customer instead of amount. The locked rate, currency, and network from the quote are used automatically.
​
customer
string
required
The customer’s ID. Must match ^customer_[a-z0-9]+$.
​
quoteId
string
required
ID of a previously created quote.
​
source
object
required
Source object (same structure as standard transfer, but currency and network are derived from the quote).
​
destination
object
required
Destination object (same structure as standard transfer, but currency and network are derived from the quote).
​
externalId
string
Your own reference identifier.
  -H "Authorization: Bearer $SPHEREPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
    "source": {
      "type": "bank_account",
      "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "currency": "usd",
      "network": "ach"
    },
    "destination": {
      "type": "wallet",
      "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
      "currency": "usdc",
      "network": "sol"
    },
    "integratorBpsFeeRate": "10"
  }'

​
Response fields

​
id
string
Unique transfer identifier, prefixed with payout_.
​
type
string
Transfer direction: on_ramp or off_ramp.
​
status
string
Initial transfer status. Newly created transfers start at pendingFunding. See Transfer Lifecycle for all values.
​
customer
string
The customer ID associated with this transfer.
​
externalId
string
Your integrator-defined reference ID, if provided.
​
source
object
Source details.
​
destination
object
Destination details.
​
depositAccount
object
Instructions the customer must use to fund the transfer (on-ramp only).
​
fees
object
Fee breakdown for the transfer.
​
quote
object
Quote used for the transfer, if applicable.
​
created
string
ISO 8601 timestamp of transfer creation.
​
updated
string
ISO 8601 timestamp of the last status update.
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "externalId": "merchant_ref_123",
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "498.50",
    "exchangeRate": "1.00"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "SpherePay LLC",
      "accountNumber": "1234567890",
      "routingNumber": "026009593",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "fees": {
    "integratorFee": {
      "fixedAmount": "0.00",
      "bpsRate": "10",
      "bpsAmount": "0.50",
      "totalAmount": "0.50",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "1.00",
      "bpsRate": "0",
      "bpsAmount": "0.00",
      "totalAmount": "1.00",
      "currency": "usd"
    }
  },
  "created": "2026-04-01T10:00:00.000Z",
  "updated": "2026-04-01T10:00:00.000Z"
}

​
Error codes

StatusCodeDescription
400address/invalidThe request body contains invalid fields or an unsupported combination.
404resource/not-foundThe customer, wallet, or bank account ID was not found.
422validation/failedField validation failed. Check the errors array for details.
For BRL (PIX) transfers, integratorFixedFee is not supported. Use integratorBpsFeeRate instead. Only polygon, ethereum, base, and tron wallet networks are supported for BRL destinations.
Last modified on May 12, 2026