x402 - Stablecoin top-up for AI agents

VirtualSMS exposes an x402-compatible top-up endpoint so AI agents can fund a balance with a single stablecoin transfer and immediately receive a working API key. Each subsequent SMS verification draws from that balance at the same retail prices as the standard API path. This is the lowest-friction integration we offer for autonomous agents: a single payment flow funds the account, and the agent then has a normal API key it can reuse for thousands of verifications. See pricing for the full cost breakdown across verification, rentals, and proxies.

Endpoint

POST https://virtualsms.io/api/v1/x402/topup

Field	Value
Protocol version	x402 v2 (v1 payloads still accepted)
Top-up range	`2.50` to `10000.00` USD
Per-verification cost	$0.05 to$ 5.00: drawn from balance at retail price (same as REST API path)
Settlement timeout	45 seconds
Asset transfer scheme	`exact` (EIP-3009 on Base, Permit2 on BNB Chain, SPL transfer on Solana)
Facilitator	Self-hosted (VirtualSMS-operated)

Pricing per verification depends on service + country and matches the rates published at /api/v1/services. There is no per-call premium for the x402 path. Agents pay the same as customers using the REST API key path.

Supported networks

Network	CAIP-2 id	Token	Status
Base	`eip155:8453`	USDC	Live
BNB Chain	`eip155:56`	USDC, USDT	Live
Solana	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	USDC, USDT	Live

All three rails have settled real payments on mainnet: Base via EIP-3009 transferWithAuthorization, BNB Chain via Permit2 permitWitnessTransferFrom, and Solana via SPL transfer.

Prerequisites per chain

Base — no prerequisite. One off-chain EIP-3009 signature; the payer needs no native gas.
BNB Chain — the payer must first approve the canonical Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3) to spend the token being paid. One-time per token per wallet. Standard ERC-20 approve. After that, payment is a single off-chain signature.
Solana — the payer signs the transfer transaction and pays SOL for network fees.

The BNB Chain approval is a one-time cost per token per wallet, not a recurring requirement — but skip it on a first payment and the transfer is rejected with no indication of why. Polygon, Arbitrum, and Optimism are intentionally not in the manifest. VirtualSMS routes settlement through Base, BNB Chain, and Solana to keep gas + bridging overhead low for agent flows.

Token decimals differ by chain. USDC and USDT on BNB Chain use 18 decimals; USDC on Base and USDC/USDT on Solana use 6. The amount field in the 402 manifest is always in the asset’s own base units, so read it from the manifest rather than deriving it from a hardcoded decimal count. A client assuming 6 decimals on BNB Chain would sign for one-trillionth of the intended amount.

Request body

Body field	Type	Required	Notes
`amount_usd`	number	yes	Top-up amount in USD, between `2.5` and `10000`
`metadata`	object	no	Optional agent identifier / memo, returned in the response for client-side bookkeeping

How the flow works

Your agent sends POST /api/v1/x402/topup with the desired top-up amount
The endpoint returns HTTP 402 Payment Required with a payment manifest listing every supported network/token + recipient wallet + price. The manifest is also present, base64-encoded, in the payment-required response header
Your agent picks one network/token, signs an authorization for the amount, and submits it in the PAYMENT-SIGNATURE header (x402 v2). The v1 X-PAYMENT header is still accepted, so existing clients keep working
VirtualSMS verifies the signature, settles on-chain, then returns {api_key, balance_usd, user_id, endpoints}: the API key is immediately usable
The agent then calls /api/v1/customer/purchase, /api/v1/customer/order/{id}, and the rest of the REST API with the issued key, drawing from the funded balance

Sample 402 response

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": "https://virtualsms.io/api/v1/x402/topup",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xfEc54264350d97d9b63f9Cc415BAF708C4695F32",
      "maxTimeoutSeconds": 45
    },
    {
      "scheme": "exact",
      "network": "eip155:56",
      "amount": "10000000000000000000",
      "asset": "0x55d398326f99059fF775485246999027B3197955",
      "payTo": "0xfEc54264350d97d9b63f9Cc415BAF708C4695F32",
      "maxTimeoutSeconds": 45
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "10000000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "7AJwx3J2qXnURXZmU5AotDeMUY5dDBqBFbweHLZ2UeUs",
      "maxTimeoutSeconds": 45
    }
  ]
}

Trimmed to three of the five entries for readability. amount is in the asset’s base units, so the Base and Solana rows above are

10.00 at 6 decimals and the BNB Chain row is

10.00 at 18.

Output schema (after successful settlement)

{
  "success": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "vsms_live_4f3a9b1c8e2d7f6a5b4c3d2e1f0a9b8c",
  "balance_usd": "10.00",
  "settlement": {
    "network": "eip155:8453",
    "tx_hash": "0xabc...",
    "amount_paid": "10.00",
    "asset": "USDC"
  },
  "endpoints": {
    "purchase": "https://virtualsms.io/api/v1/customer/purchase",
    "order": "https://virtualsms.io/api/v1/customer/order/{id}",
    "balance": "https://virtualsms.io/api/v1/customer/balance",
    "services": "https://virtualsms.io/api/v1/services"
  }
}

The returned api_key is a standard VirtualSMS key: it works with every REST endpoint, supports all services and countries we list, and can be re-used until the balance is exhausted or the agent tops up again against the same key. Settlement is idempotent per on-chain transaction: re-submitting the same signed payment credits the balance once, never twice.

Topping up an existing key

To add to a balance without provisioning a new account, include the existing API key:

POST https://virtualsms.io/api/v1/x402/topup
x-api-key: vsms_live_4f3a9b1c8e2d7f6a5b4c3d2e1f0a9b8c

The 402 manifest, signing flow, and settlement are identical. The response returns the same api_key plus the new balance_usd.

Why top-up instead of per-call settlement

An earlier per-call /sms-verify endpoint returned a flat

0.10 quote per verification. Deprecated 2026-04-30: flat per-call pricing did not fit our

0.05 to $7 service price range, and a payment per SMS added meaningful latency for high-volume agents. One up-front payment funds N verifications at the same retail rates, and the resulting API key works with the full REST surface.

Discovering this endpoint

The x402 discovery API lists every payable resource we expose:

GET https://virtualsms.io/api/v1/x402/discovery/resources

VirtualSMS is listed (or will be listed on first settlement) on:

Info endpoint

GET https://virtualsms.io/api/v1/x402/info

Returns the live wallet addresses, supported networks, and top-up range, useful for client introspection without triggering a 402.

Already have an account and want balance/history dashboards? Use the REST API with an x-api-key issued from the web app. Want an agent to provision its own key in one payment? Use x402 top-up.

Getting Started

Integration

Earn

x402 - Stablecoin top-up for AI agents

Endpoint

Supported networks

Prerequisites per chain

Request body

How the flow works

Sample 402 response

Output schema (after successful settlement)

Topping up an existing key

Why top-up instead of per-call settlement

Discovering this endpoint

Info endpoint

​Endpoint

​Supported networks

​Prerequisites per chain

​Request body

​How the flow works

​Sample 402 response

​Output schema (after successful settlement)

​Topping up an existing key

​Why top-up instead of per-call settlement

​Discovering this endpoint

​Info endpoint

Endpoint

Supported networks

Prerequisites per chain

Request body

How the flow works

Sample 402 response

Output schema (after successful settlement)

Topping up an existing key

Why top-up instead of per-call settlement

Discovering this endpoint

Info endpoint