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 The ID of the customer who will own this Onramper Account.
The fiat currency the virtual account accepts for deposits. Must be "usd" or "eur".
The stablecoin that deposited fiat is converted into. Must be one of "usdc", "usdt", or "eurc". Must be compatible with the chosen network.
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.
The on-chain wallet address where converted stablecoins are delivered. Must be a valid address format for the specified network.
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 Unique identifier for the Onramper Account.
ID of the customer who owns this account.
Whether the account is currently accepting deposits.
Bank account details your customer uses to deposit fiat funds. The fiat currency accepted (e.g., "usd").
Name of the receiving bank.
Physical address of the receiving bank.
Virtual bank account number to deposit to.
ABA routing number of the receiving bank (for USD/ACH and Wire).
Name of the beneficiary on the receiving account.
Address of the beneficiary.
IBAN for SEPA deposits (EUR accounts).
BIC/SWIFT code for SEPA deposits (EUR accounts).
The crypto destination where converted funds are sent. The stablecoin funds are converted to (e.g., "usdc").
On-chain wallet address receiving the converted funds.
Blockchain network of the destination wallet.
Fee breakdown applied to each deposit conversion. Total fee in basis points (platform + integrator).
Integrator fee in basis points.
SpherePay platform fee in basis points.
ISO 8601 timestamp of when the account was created.
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 Status Code Description 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.
