{"openapi":"3.1.0","info":{"title":"x402sms","version":"0.1.0","description":"Virtual phone numbers and SMS verification for AI agents and humans. Pay per activation in USDC via x402 on Base. You are only charged when the SMS code arrives — cancellations and expirations cost nothing.","contact":{"email":"support@sms-x402.xyz"},"x-guidance":"Typical flow: 1) GET /v1/services and GET /v1/countries to pick a service alias and country api_id (use service alias 'ot' — 'Any other' — when your target service is not listed). 2) Optionally GET /v1/price?service=ALIAS&country=ID for a quote. 3) POST /v1/numbers with {service, country} — the first attempt returns HTTP 402 with x402 v2 payment requirements (upto scheme, Base USDC); pay and retry with the PAYMENT-SIGNATURE header to receive {id, number, accessToken}. 4) Poll GET /v1/numbers/{id} with the accessToken (Bearer or ?token=) every 5-10s until status=completed; the 'code' field contains the SMS verification code and payment is settled only at this point (receipt in the PAYMENT-RESPONSE header). Terminal states: 'completed' (charged, success), 'cancelled' and 'expired' (both free) — stop polling when you see any of them. Numbers expire after ~18 minutes; expired activations are never charged. After a code was delivered, POST /v1/numbers/{id}/retry requests another SMS for the same number (additional codes are free within the number's lifetime). Errors: 409 NO_NUMBERS = try another country/operator; 503 = back off and retry later; 429 = rate limited, slow down. Support: support@sms-x402.xyz"},"servers":[{"url":"https://api.sms-x402.xyz"}],"x-agentcash-provenance":{"ownershipProofs":["0x2d5d95c1a9c4e558b2000d76488cc7102812ede53b5c8e95c4c108c35ee6e208537cf4c5c47f223463013f32bd62d80d53399d5ba5e129550abf32cefec4402c1c"]},"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer accessToken returned by POST /v1/numbers. Also accepted as ?token= query param."}}},"paths":{"/v1/health":{"get":{"operationId":"health","summary":"Service health check","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/v1/countries":{"get":{"operationId":"listCountries","summary":"List countries with api_id values for ordering","security":[],"responses":{"200":{"description":"Country list","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"apiId":{"type":"integer"},"name":{"type":"string"}}}}}}}}}}}},"/v1/services":{"get":{"operationId":"listServices","summary":"List services with alias codes for ordering","security":[],"responses":{"200":{"description":"Service list","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"alias":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/v1/operators":{"get":{"operationId":"listOperators","summary":"List operators and the countries they serve","security":[],"responses":{"200":{"description":"Operator list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/price":{"get":{"operationId":"getPrice","summary":"Quote the USDC price for an activation","security":[],"parameters":[{"name":"service","in":"query","required":true,"schema":{"type":"string"},"description":"Service alias, e.g. 'tg'"},{"name":"country","in":"query","required":true,"schema":{"type":"integer"},"description":"Country api_id, e.g. 16"}],"responses":{"200":{"description":"Price quote","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string"},"country":{"type":"integer"},"priceUsd":{"type":"number"},"priceAtomic":{"type":"string"}}}}}},"400":{"description":"Unknown service or country","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/numbers":{"post":{"operationId":"orderNumber","summary":"Order a virtual phone number. Paid via x402 (upto scheme): you authorize the quoted max price and are charged only when an SMS code is delivered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","description":"Service alias to activate, e.g. 'tg' (Telegram), 'wa' (WhatsApp), 'ig' (Instagram). Full list: GET /v1/services. Use 'ot' (Any other) if your target service is not listed."},"country":{"type":"integer","description":"Country api_id, e.g. 16 = United Kingdom. Full list: GET /v1/countries"},"operator":{"type":"string","description":"Optional operator name, e.g. 'vodafone'. Full list: GET /v1/operators. Omit for random operator."}},"required":["service","country"]}}}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.500000","max":"100.000000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Number ordered","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"accessToken":{"type":"string","description":"Bearer token required for status/cancel/retry calls"},"number":{"type":"string","description":"Phone number with country code"},"service":{"type":"string"},"country":{"type":"integer"},"priceAtomic":{"type":"string","description":"Max authorized price in USDC atomic units (6 decimals)"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["waiting_code"]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required (x402 v2)"},"409":{"description":"No numbers available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"503":{"description":"Temporarily at capacity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/numbers/{id}":{"get":{"operationId":"getActivation","summary":"Poll activation status. When the SMS arrives, status becomes 'completed' with the verification 'code', and payment is settled.","security":[{"accessToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"Alternative to the Authorization header"}],"responses":{"200":{"description":"Activation status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["waiting_code","completed","cancelled","expired"]},"number":{"type":"string"},"code":{"type":"string","description":"Latest SMS verification code (present when status=completed)"},"codes":{"type":"array","items":{"type":"string"},"description":"All SMS codes received for this activation"},"settleTx":{"type":"string","description":"Payment settlement tx hash"}}}}}},"401":{"description":"Invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/numbers/{id}/cancel":{"post":{"operationId":"cancelActivation","summary":"Cancel an activation before the SMS arrives. Never charged.","security":[{"accessToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Not cancellable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/numbers/{id}/retry":{"post":{"operationId":"retryActivation","summary":"Request another SMS for the same activation","security":[{"accessToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Waiting for new SMS","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Not retryable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}