New: BRL/PIX transfers now supported  View changelog →
Onramper Account

Create an Onramper Account

An Onramper Account provides a streamlined, automatic solution to convert fiat currency into stablecoins directly into your customers' bank accounts.

POST
/v2/virtual-account

Authorization

AuthorizationBearer <token>

In: header

Request Body

customerIdstring

The customer who will own the virtual account.

sourceCurrencystring

The fiat currency the virtual account accepts for deposits.

Value in"usd" | "eur"
destinationCurrencystring

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

Value in"usdc" | "usdt" | "eurc"
networkstring

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

Value in"arbitrum" | "avalanche" | "base" | "ethereum" | "polygon" | "sol" | "tron"
walletAddressstring

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

integratorFeeBps?string

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

Response Body

curl -X POST "https://api.spherepay.co/v2/virtual-account" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "sourceCurrency": "usd",
    "destinationCurrency": "usdc",
    "network": "ethereum",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  }'
{
  "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"
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}