Skip to main content
Create a Virtual Account
curl --request POST \
  --url https://api.spherepay.co/v2/virtual-account \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destinationCurrency": "usdc",
  "network": "ethereum",
  "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "sourceCurrency": "usd",
  "integratorFeeBps": "100"
}
'
{
  "id": "virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St, Kansas City, MO 64108",
    "bankAccountNumber": "9876543210",
    "bankRoutingNumber": "021000089",
    "bankBeneficiaryName": "Bridge Financial Inc.",
    "bankBeneficiaryAddress": "123 Finance St, San Francisco, CA 94105",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  },
  "destination": {
    "currency": "usdc",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
    "network": "ethereum"
  },
  "created": "2025-01-15T10:30:00.000Z",
  "updated": "2025-01-15T12:00:00.000Z",
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "fee": {
    "totalBpsRate": "130",
    "integratorFee": {
      "bpsRate": "100"
    },
    "platformFee": {
      "bpsRate": "30"
    }
  }
}
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
destinationCurrency
enum<string>
required

The crypto currency deposited funds are converted into. See Supported Rails & Currencies.

Available options:
usdc,
usdt,
eurc
Example:

"usdc"

​
network
enum<string>
required

The blockchain network the destination wallet is on. See Supported Rails & Currencies.

Available options:
arbitrum,
avalanche,
base,
ethereum,
polygon,
sol,
tron
Example:

"ethereum"

​
walletAddress
string
required

The on-chain wallet address where converted crypto is sent. Must be valid for the selected network.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

​
customerId
string
required

The customer who will own the virtual account.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

​
sourceCurrency
enum<string>
required

The fiat currency the virtual account accepts for deposits.

Available options:
usd,
eur
Example:

"usd"

​
integratorFeeBps
string

Integrator fee in basis points (1 bps = 0.01%). Defaults to 0 if not provided.

Example:

"100"

Response

​
id
string
required

Unique identifier for the virtual account.

Example:

"virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

​
active
boolean
required

Whether the virtual account is currently active and accepting deposits.

Example:

true

​
depositInstructions
object
required

Bank account details that depositors should use to send fiat funds into the virtual account.

​
destination
object
required

The crypto destination where converted funds are sent after deposit.

​
created
string
required

Timestamp when the virtual account was created (ISO 8601).

Example:

"2025-01-15T10:30:00.000Z"

​
updated
string
required

Timestamp when the virtual account was last updated (ISO 8601).

Example:

"2025-01-15T12:00:00.000Z"

​
customer
string

The customer ID who owns the virtual account.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

​
fee
object

Fee breakdown for the virtual account, including integrator and platform fees.

Last modified on June 18, 2026