# x402sms

> Virtual phone numbers and SMS verification for AI agents. Pay per activation in USDC via x402 on Base. You are only charged when the SMS code arrives.

## Endpoints (base: https://api.sms-x402.xyz)

- GET /v1/services — list service aliases (tg, wa, ig, fb, ...; use 'ot' = Any other for unlisted services)
- GET /v1/countries — list country api_id values
- GET /v1/operators — list operators (countryIds are api_ids)
- GET /v1/price?service=ALIAS&country=ID — quote price in USDC
- POST /v1/numbers {service, country, operator?} — order a number (x402-paid, upto scheme; 402 on first call)
- GET /v1/numbers/{id} — poll for the SMS code (payment settles when the code arrives)
- POST /v1/numbers/{id}/cancel — cancel while waiting (free, never charged)
- POST /v1/numbers/{id}/retry — request another SMS after a code was delivered (free)

## Auth

Status/cancel/retry endpoints need the accessToken returned at order time:
Authorization: Bearer <accessToken>  (preferred) or ?token=<accessToken>

## Agent flow

1. Pick service alias + country api_id from the list endpoints (alias 'ot' works for any unlisted service).
2. POST /v1/numbers. First response is HTTP 402 with x402 v2 payment requirements (upto scheme, eip155:8453 USDC). Pay and retry with the PAYMENT-SIGNATURE header.
3. Response contains {id, number, accessToken}. Use the number in the target service.
4. Poll GET /v1/numbers/{id} every 5-10s. When status=completed, read 'code'. Payment settles at this moment only — the PAYMENT-RESPONSE header holds the on-chain receipt.
5. Terminal states — stop polling when you see them: 'completed' (charged, success), 'cancelled' (free), 'expired' (free, ~18 min lifetime).
6. Need a second code for the same number? POST /v1/numbers/{id}/retry, then keep polling — additional codes are free.

## Errors

- 409 no numbers — try another country or operator; you were not charged
- 503 — capacity exhausted; back off and retry later; you were not charged
- 429 — rate limited; slow down
- 402 on a paid retry — payment rejected; re-read the PAYMENT-REQUIRED header and sign again
- 502 on a poll — settlement hiccup; keep polling, it retries automatically (you can never be double-charged)

## Support

Contact: support@sms-x402.xyz

## Docs

- OpenAPI: https://api.sms-x402.xyz/openapi.json
- Discovery: https://api.sms-x402.xyz/.well-known/x402
- Website & guides: https://sms-x402.xyz