Agent Payments (x402)

Deposit-first top-up via x402 — pay once, get a reusable balance + API key

LIVE. Call without payment to receive the HTTP 402 payment manifest; retry with a valid X-PAYMENT (or PAYMENT-SIGNATURE) header to settle inline. On success returns an API key (returned once) plus a USD balance, usable through the standard /api/v1/customer/* REST API at ordinary retail prices — no further per-call payment.

Canonical discovery manifest: https://virtualsms.io/.well-known/x402.json

Accepted payment rails: Base USDC, Solana USDC, Solana USDT, BNB Chain USDC, BNB Chain USDT. Deposit bounds: $2.50 minimum, $10000 maximum, $2.50 default, set via the optional amount_usd field.

Depositing again from the same wallet does NOT mint a second key by default — the first key stays valid. Set mint_new_key: true to mint a fresh one (e.g. the original was lost); the wallet's own signature is the proof of ownership.

post/api/v1/x402/topup

Request

  • Base URL: https://virtualsms.io
  • URL: https://virtualsms.io/api/v1/x402/topup
  • Auth: one of:
    • API key in header X-API-Key
    • API key in query parameter api_key

Request body

amount_usdnumber

Optional USD deposit amount, default 2.50, min 2.50, max 10000

mint_new_keyboolean

Mint a fresh API key even if this wallet already has one

Example request

{
  "amount_usd": 5
}

Response

Payment settled — balance credited, API key returned (once) on a first deposit

status'credited' | 'credit_pending' | 'already_processed'
api_keystring

Returned once, only on a wallet's first deposit or when mint_new_key was set

user_idstring
balance_usdnumber
credited_usdnumber
endpointsobject

The standard customer API routes to spend the balance with the api_key

Changes

No recorded changes to this operation across all 1 revision of this API.