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 create an Onramper Account for a customer. An Onramper Account gives your customer a dedicated virtual bank account number. Any fiat deposited to that account is automatically converted to the specified stablecoin and forwarded to the destination wallet address — no per-transfer API call is required. Always create one Onramper Account per customer, even if multiple customers share the same destination wallet, to ensure deposits can be attributed correctly.
Onramper Accounts are a separate product from the Transfer API. They use different endpoints and do not support bank account creation via the Transfer API.

​
Endpoint

POST https://api.spherepay.co/v2/virtual-account

​
Authentication

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

​
Request parameters

​
customerId
string
required
The ID of the customer who will own this Onramper Account.
​
sourceCurrency
string
required
The fiat currency the virtual account accepts for deposits. Must be "usd" or "eur".
​
destinationCurrency
string
required
The stablecoin that deposited fiat is converted into. Must be one of "usdc", "usdt", or "eurc". Must be compatible with the chosen network.
​
network
string
required
The blockchain network the destination wallet is on. Must be one of "arbitrum", "avalanche", "base", "ethereum", "polygon", "sol", or "tron". Must support the chosen destinationCurrency.
​
walletAddress
string
required
The on-chain wallet address where converted stablecoins are delivered. Must be a valid address format for the specified network.
​
integratorFeeBps
string
Optional integrator fee in basis points (1 bps = 0.01%). Defaults to "0" if not provided. This fee is added on top of the SpherePay platform fee.
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "sourceCurrency": "usd",
    "destinationCurrency": "usdc",
    "network": "ethereum",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  }'

​
Response fields

​
id
string
Unique identifier for the Onramper Account.
​
customer
string
ID of the customer who owns this account.
​
active
boolean
Whether the account is currently accepting deposits.
​
depositInstructions
object
Bank account details your customer uses to deposit fiat funds.
​
destination
object
The crypto destination where converted funds are sent.
​
fee
object
Fee breakdown applied to each deposit conversion.
​
created
string
ISO 8601 timestamp of when the account was created.
​
updated
string
ISO 8601 timestamp of the most recent update.
  "id": "virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St, Kansas City, MO 64108",
    "bankAccountNumber": "9876543210",
    "bankRoutingNumber": 21000089,
    "bankBeneficiaryName": "Bridge Financial Inc.",
    "bankBeneficiaryAddress": "123 Finance St, San Francisco, CA 94105",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  },
  "destination": {
    "currency": "usdc",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
    "network": "ethereum"
  },
  "fee": {
    "totalBpsRate": "130",
    "integratorFee": {
      "bpsRate": "100"
    },
    "platformFee": {
      "bpsRate": "30"
    }
  },
  "created": "2025-01-15T10:30:00.000Z",
  "updated": "2025-01-15T12:00:00.000Z"
}

​
Error responses

StatusCodeDescription
400address/invalidOne or more request parameters are invalid.
404resource/not-foundThe specified customer ID does not exist.
422validation/failedValidation failed. The response includes a per-field errors array.
Last modified on May 12, 2026