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.

Accept fiat payments from your end users and have them delivered to your wallet as USDC, USDT, or EURC — automatically, without writing a POST /v2/transfer call per payment. The primitive is an Onramper Account: a dedicated virtual bank account that auto-converts any incoming fiat deposit into stablecoins and settles to a registered wallet. This pattern is the inverse of Trading — instead of orchestrating each conversion, you provision the account once and let it run.

​
When to use this pattern

  • E-commerce and B2B billing. Invoice customers in USD, EUR, or BRL — they pay via wire or ACH against a virtual account, and you receive USDC.
  • Marketplaces. Provision one Onramper Account per seller. Each seller’s fiat receipts auto-settle to a seller-controlled wallet.
  • DeFi funding. Let users fund an on-chain position via wire or card. The user wires fiat to their Onramper Account, USDC settles directly to the protocol’s contract or a wallet you sweep into the protocol.
  • Subscription billing. Recurring ACH pulls from customers land in their Onramper Account and convert without per-billing-cycle API work.
  • Treasury inbound. Receive customer payments in fiat without holding fiat — convert at the point of receipt.
The common thread: anytime you’d otherwise write a transfer-per-payment loop, an Onramper Account replaces it with a single setup call and zero ongoing transfer API calls.

​
How it works

  1. Provision an Onramper Account for each payer (or per receiving wallet — depends on your model).
  2. Share the deposit instructions with your end user — they wire USD, ACH, or SEPA against the virtual account just like any other bank account.
  3. SpherePay auto-converts and settles. Each incoming deposit is converted to the configured stablecoin and delivered to the registered wallet address — no transfer API call required.
You can fan this out: one Onramper Account per customer for clean reconciliation, one per product line, or one per wallet destination.

​
Setup

​
Step 1 — Verify the customer

The customer who owns the Onramper Account must complete KYC or KYB and be approved. The customer can be a single user, a business entity (for a marketplace seller), or your own company (for a single-account inbound funnel).

​
Step 2 — Register the destination wallet

The wallet that will receive the stablecoin output of every deposit. POST https://api.spherepay.co/v2/wallet 
{
  "customerId": "{{customer_id}}",
  "network": "ethereum",
  "address": "0xabcd1234...your wallet or contract..."
}
Store the returned id as {{wallet_id}}. For a DeFi flow, this can be the address of the protocol’s vault or pool contract directly — Sphere will deliver USDC to it on every conversion.

​
Step 3 — Create the Onramper Account

POST https://api.spherepay.co/v2/virtual-account 
{
  "customerId": "{{customer_id}}",
  "destination": {
    "walletId": "{{wallet_id}}",
    "currency": "usdc",
    "network": "ethereum"
  },
  "source": {
    "currency": "usd",
    "networks": ["ach", "wire"]
  }
}
The response includes accountDetails — the virtual bank account’s routing and account numbers. Share these with your payer. For EUR-denominated inbound, swap to: 
"source": {
  "currency": "eur",
  "networks": ["sepa"]
}
For BRL inbound, use currency: "brl" and networks: ["pix"] (subject to BRL verification-profile requirements — see Trading).

​
Step 4 — Share deposit instructions

From the response, surface the account number, routing number (or IBAN/BIC for SEPA, PIX key for BRL), and account-holder name in your UI or invoice. The payer initiates an ACH or wire to that account.

​
Step 5 — Receive

Each deposit triggers:
  1. Sphere receives the fiat into the virtual account.
  2. Sphere converts to the configured stablecoin at the prevailing rate.
  3. The stablecoin is delivered to the registered wallet — {{wallet_id}}.
Track activity on the Onramper Account via: 
curl "https://api.spherepay.co/v2/virtual-account/{{virtual_account_id}}/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
DeFi application

For DeFi platforms specifically, the Onramper Account pattern unlocks on-ramp into a protocol position in one user action:
  1. User decides to deposit into your protocol.
  2. Your app shows them the deposit instructions for an Onramper Account configured to settle USDC directly to the protocol’s vault contract (or an intermediary wallet you sweep into the protocol).
  3. User wires USD from their bank.
  4. USDC lands at the protocol contract; the deposit reflects in their on-chain position automatically.
The user never touches a wallet, never bridges, never pays gas to onboard. The fiat-to-position flow becomes a single wire. For protocols requiring more orchestration (e.g. permit signatures, deposit functions with specific calldata), use an intermediary wallet that you control and trigger the protocol interaction on stablecoin arrival.

​
Marketplace application

Provision one Onramper Account per seller at onboarding: 
async function onboardSeller(sellerCustomerId, sellerWalletId) {
  // Each seller gets their own dedicated virtual account
  const va = await createVirtualAccount({
    customerId: sellerCustomerId,
    destination: {
      walletId: sellerWalletId,
      currency: "usdc",
      network: "polygon",
    },
    source: {
      currency: "usd",
      networks: ["ach"],
    },
  });

  // Hand the seller their unique deposit details
  return {
    routing: va.accountDetails.routingNumber,
    account: va.accountDetails.accountNumber,
    name: va.accountDetails.accountHolderName,
  };
}
Buyers pay each seller directly via ACH against the seller’s virtual account. The marketplace platform never touches the funds — Sphere handles the entire fiat-to-USDC settlement.

​
Compliance considerations

  • KYC the account owner. The customer who owns the Onramper Account must be verified. For marketplaces, this means each seller goes through KYC/KYB.
  • Source of funds. Large or unusual deposits may require additional documentation per Sphere’s compliance policies.
  • Sanctions screening. Sphere screens deposits at the rail level, but you remain responsible for the legality of your underlying business activity.
  • Tax reporting. Convert-to-stablecoin events may be taxable in some jurisdictions — coordinate with your tax advisor.

​
Best practices

  • One account per receiver. Don’t share an Onramper Account across multiple sellers or use cases — reconciliation gets messy. Dedicated accounts make every deposit unambiguous.
  • Set conservative limits. Use Sphere’s per-account deposit caps to bound exposure on any single account.
  • Poll deposit status. The Onramper Account doesn’t fire webhooks today; poll the virtual-account transfers endpoint to detect new deposits.
  • Use SEPA Instant where possible for EUR flows requiring fast settlement.
  • Plan for refunds. If the underlying business model requires returning funds, you’ll need a separate off-ramp flow (see Offloader Wallets).

Onramper Accounts

The primitive this solution is built on — virtual bank accounts with automatic stablecoin conversion.

Trading

The inverse pattern — orchestrated, per-transfer conversion.

Onboarding

KYC/KYB for the account owner.

Supported rails

Which currencies and networks are supported.
Last modified on May 21, 2026