Quickstart for agents

This guide takes an agent from zero to a delivered SMS code.

Prerequisites

A wallet with USDC on Base mainnet (eip155:8453)
An x402 client library (TypeScript, Python, or raw HTTP)

Step 1 — Discover what's available

curl https://api.sms-x402.xyz/v1/services    # 2,205 service aliases: tg, wa, ig, go, fb...
curl https://api.sms-x402.xyz/v1/countries   # 182 country api_ids: 16 = UK, 1 = Ukraine...

Service not listed? Use alias ot ("Any other") — it works for any service without a dedicated alias.

Step 2 — (Optional) quote the price

curl "https://api.sms-x402.xyz/v1/price?service=tg&country=16"
# {"priceUsd":1.941139,"priceAtomic":"1941139",...}

Prices start at $0.50 in USDC and vary by service and country. This step is optional — the 402 response always carries the exact price.

Step 3 — Order a number

curl -X POST https://api.sms-x402.xyz/v1/numbers \
  -H 'Content-Type: application/json' \
  -d '{"service":"tg","country":16}'

The response is HTTP 402 with a PAYMENT-REQUIRED header containing x402 v2 payment requirements (upto scheme — you authorize a maximum, we settle only the actual price on delivery). Your x402 client signs the payment and retries with the PAYMENT-SIGNATURE header. The paid response:

{
  "id": "3f8b2c1e-...",
  "accessToken": "ab12cd34...",
  "number": "447412345678",
  "priceAtomic": "1941139",
  "expiresAt": "2026-01-01T00:18:00.000Z",
  "status": "waiting_code"
}

Store the accessToken — it authorizes all follow-up calls for this activation.

Step 4 — Trigger the SMS and poll

Enter the number in the target service and request the verification code there. Then poll us:

curl "https://api.sms-x402.xyz/v1/numbers/3f8b2c1e-...?token=ab12cd34..."

Every 5–10 seconds until:

{ "status": "completed", "code": "58123" }

The PAYMENT-RESPONSE header confirms settlement — this is the moment you are charged, never before.

Step 5 — Failure paths (free) and extra codes

No SMS after a few minutes → POST /v1/numbers/{id}/cancel — costs $0
Do nothing → the number expires after ~18 minutes — costs $0
Got one code but the service wants another? → POST /v1/numbers/{id}/retry requests another SMS for the same number, delivered free within the number's lifetime

One-line prompt for your agent

Read https://api.sms-x402.xyz/llms.txt and use the API to get a phone number that can receive an SMS verification code for [SERVICE] in [COUNTRY]. You have an x402 wallet on Base.