> ## Documentation Index
> Fetch the complete documentation index at: https://virtualsms.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 - Stablecoin top-up for AI agents

> Top up a VirtualSMS balance with USDC/USDT in a single x402 payment, then run unlimited SMS verifications at retail prices. No signup form, no card, no manual API-key issuance.

VirtualSMS exposes an [x402](https://x402.org)-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](https://virtualsms.io/agents): one signature funds the account, and the agent then has a normal API key it can reuse for thousands of verifications. See [pricing](https://virtualsms.io/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`](/docs/api-reference/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

1. Your agent sends `POST /api/v1/x402/topup` with the desired top-up amount
2. The endpoint returns **HTTP 402 Payment Required** with a payment manifest listing every supported network/token + recipient wallet + price
3. Your agent picks one network/token, signs an authorization for the amount, and submits it via the standard x402 `X-PAYMENT` header
4. VirtualSMS verifies the signature, settles on-chain, then returns `{api_key, balance_usd, user_id, endpoints}`: the API key is immediately usable
5. 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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:

* [402.ad](https://402.ad)
* [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)

## 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.

<Tip>
  Already have an account and want balance/history dashboards? Use the [REST API](/docs/api-reference/introduction) 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.
</Tip>