Skip to main content

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.

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.

​
Endpoint

POST https://virtualsms.io/api/v1/x402/topup
FieldValue
Top-up range2.00 – 10000.00 USDC
Per-verification cost0.05–0.05 – 5.00 — drawn from balance at retail price (same as REST API path)
Settlement timeout300 seconds
Asset transfer schemeexact (EIP-3009 / Solana)
FacilitatorSelf-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

NetworkTokenStatus
BaseUSDCLive
SolanaUSDCLive
SolanaUSDTLive
BNB ChainUSDC, USDTComing 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 fieldTypeRequiredNotes
amount_usdnumberyesTop-up amount in USDC, between 2 and 10000
metadataobjectnoOptional 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

{
  "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.10quoteperverification.Deprecated2026−04−30—flatper−callpricingdidnotfitour0.10 quote per verification. Deprecated 2026-04-30 — flat per-call pricing did not fit our 0.05–$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.