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: one signature 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
Top-up range	`2.00` to `10000.00` USDC
Per-verification cost	$0.05 to$ 5.00: drawn from balance at retail price (same as REST API path)
Settlement timeout	300 seconds
Asset transfer scheme	`exact` (EIP-3009 / 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	Token	Status
Base	USDC	Live
Solana	USDC	Live
Solana	USDT	Live
BNB Chain	USDC, USDT	Coming soon: pending Permit2 settlement support

Polygon, Arbitrum, and Optimism are intentionally not in the manifest. VirtualSMS routes settlement through Base + Solana to keep gas + bridging overhead low for agent flows.

Request body

Body field	Type	Required	Notes
`amount_usd`	number	yes	Top-up amount in USDC, between `2` 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
Your agent picks one network/token, signs an authorization for the amount, and submits it via the standard x402 X-PAYMENT header
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": 1,
  "error": "Payment required to top up VirtualSMS balance",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "10000000",
      "payTo": "0xfEc54264350d97d9b63f9Cc415BAF708C4695F32",
      "resource": "https://virtualsms.io/api/v1/x402/topup",
      "description": "Top up VirtualSMS balance ($10.00 USDC)",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 300
    },
    {
      "scheme": "exact",
      "network": "solana",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "maxAmountRequired": "10000000",
      "payTo": "7AJwx3J2qXnURXZmU5AotDeMUY5dDBqBFbweHLZ2UeUs",
      "resource": "https://virtualsms.io/api/v1/x402/topup",
      "description": "Top up VirtualSMS balance ($10.00 USDC)",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 300
    }
  ]
}

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": "base",
    "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.

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 single signature per SMS added meaningful latency for high-volume agents. The endpoint now returns HTTP 410 Gone with a pointer to /topup. One up-front signature funds N verifications at the same retail rates, and the resulting API key works with the full REST surface.

Discovering this endpoint

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 signature? Use x402 top-up.

Getting Started

Integration

Earn

x402 - Stablecoin top-up for AI agents

Endpoint

Supported networks

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

​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

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