Create a Virtual Bank Account for Fiat On-Ramp

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 '
{
  "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "destinationCurrency": "usdc",
  "network": "ethereum",
  "sourceCurrency": "usd",
  "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "integratorFeeBps": "100"
}
'

import requests

url = "https://api.spherepay.co/v2/virtual-account"

payload = {
    "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "destinationCurrency": "usdc",
    "network": "ethereum",
    "sourceCurrency": "usd",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
    "integratorFeeBps": "100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7',
    destinationCurrency: 'usdc',
    network: 'ethereum',
    sourceCurrency: 'usd',
    walletAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97',
    integratorFeeBps: '100'
  })
};

fetch('https://api.spherepay.co/v2/virtual-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/virtual-account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => 'customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7',
    'destinationCurrency' => 'usdc',
    'network' => 'ethereum',
    'sourceCurrency' => 'usd',
    'walletAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97',
    'integratorFeeBps' => '100'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/virtual-account"

	payload := strings.NewReader("{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/virtual-account")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/virtual-account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}"

response = http.request(request)
puts response.read_body

{
  "active": true,
  "created": "2025-01-15T10:30:00.000Z",
  "depositInstructions": {
    "bankAccountNumber": "9876543210",
    "bankAddress": "1801 Main St, Kansas City, MO 64108",
    "bankBeneficiaryAddress": "123 Finance St, San Francisco, CA 94105",
    "bankBeneficiaryName": "Bridge Financial Inc.",
    "bankName": "Lead Bank",
    "bankRoutingNumber": "021000089",
    "bic": "COBADEFFXXX",
    "currency": "usd",
    "iban": "DE89370400440532013000"
  },
  "destination": {
    "currency": "usdc",
    "network": "ethereum",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  },
  "id": "virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "updated": "2025-01-15T12:00:00.000Z",
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "fee": {
    "integratorFee": {
      "bpsRate": "100"
    },
    "platformFee": {
      "bpsRate": "30"
    },
    "totalBpsRate": "130"
  }
}

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

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

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

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 '
{
  "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "destinationCurrency": "usdc",
  "network": "ethereum",
  "sourceCurrency": "usd",
  "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
  "integratorFeeBps": "100"
}
'

import requests

url = "https://api.spherepay.co/v2/virtual-account"

payload = {
    "customerId": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "destinationCurrency": "usdc",
    "network": "ethereum",
    "sourceCurrency": "usd",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
    "integratorFeeBps": "100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7',
    destinationCurrency: 'usdc',
    network: 'ethereum',
    sourceCurrency: 'usd',
    walletAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97',
    integratorFeeBps: '100'
  })
};

fetch('https://api.spherepay.co/v2/virtual-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/virtual-account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => 'customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7',
    'destinationCurrency' => 'usdc',
    'network' => 'ethereum',
    'sourceCurrency' => 'usd',
    'walletAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97',
    'integratorFeeBps' => '100'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/virtual-account"

	payload := strings.NewReader("{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/virtual-account")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/virtual-account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7\",\n  \"destinationCurrency\": \"usdc\",\n  \"network\": \"ethereum\",\n  \"sourceCurrency\": \"usd\",\n  \"walletAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\",\n  \"integratorFeeBps\": \"100\"\n}"

response = http.request(request)
puts response.read_body

{
  "active": true,
  "created": "2025-01-15T10:30:00.000Z",
  "depositInstructions": {
    "bankAccountNumber": "9876543210",
    "bankAddress": "1801 Main St, Kansas City, MO 64108",
    "bankBeneficiaryAddress": "123 Finance St, San Francisco, CA 94105",
    "bankBeneficiaryName": "Bridge Financial Inc.",
    "bankName": "Lead Bank",
    "bankRoutingNumber": "021000089",
    "bic": "COBADEFFXXX",
    "currency": "usd",
    "iban": "DE89370400440532013000"
  },
  "destination": {
    "currency": "usdc",
    "network": "ethereum",
    "walletAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  },
  "id": "virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "updated": "2025-01-15T12:00:00.000Z",
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "fee": {
    "integratorFee": {
      "bpsRate": "100"
    },
    "platformFee": {
      "bpsRate": "30"
    },
    "totalBpsRate": "130"
  }
}

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

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

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

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

customerId

string

required

The customer who will own the virtual account.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

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"

sourceCurrency

enum<string>

required

The fiat currency the virtual account accepts for deposits.

Available options:

usd,

eur

Example:

"usd"

walletAddress

string

required

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

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

integratorFeeBps

string

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

Example:

"100"

Response

active

boolean

required

Whether the virtual account is currently active and accepting deposits.

Example:

true

created

string

required

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

Example:

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

depositInstructions

object

required

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

Show child attributes

destination

object

required

The crypto destination where converted funds are sent after deposit.

Show child attributes

string

required

Unique identifier for the virtual account.

Example:

"virtualAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

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.

Show child attributes

Last modified on June 18, 2026

Onboarding

Accounts

Money movement

Webhooks

Create a Virtual Bank Account for Fiat On-Ramp

Authorizations

Body

Response