API reference

Machine-readable spec: openapi.json · llms.txt

Free endpoints

`GET /v1/services`

All orderable services: { services: [{ alias, name }] } — 2,205 entries. Alias ot ("Any other") works for services without a dedicated alias.

`GET /v1/countries`

All countries: { countries: [{ apiId, name }] } — 182 entries. Use apiId as country when ordering.

`GET /v1/operators`

All operators: { operators: [{ name, displayName, countryIds }] } — ~150 entries. Omit operator when ordering for a random operator.

`GET /v1/price?service={alias}&country={apiId}`

Current quote: { service, country, priceUsd, priceAtomic }. priceAtomic is the exact USDC atomic amount that will appear in the 402.

Paid endpoint

`POST /v1/numbers` — x402-gated

Body: { "service": "tg", "country": 16, "operator": "vodafone"? }

Without payment → 402 + PAYMENT-REQUIRED header (x402 v2, upto scheme, Base USDC) with Bazaar discovery metadata
With PAYMENT-SIGNATURE → 200:

{
  "id": "uuid",
  "accessToken": "hex token",
  "number": "447412345678",
  "service": "tg",
  "country": 16,
  "priceAtomic": "1941139",
  "expiresAt": "ISO-8601",
  "status": "waiting_code"
}

Errors: 400 invalid input/payment mismatch · 402 verification failed · 409 no numbers · 503 temporarily unavailable.

Activation endpoints (token-gated, not paid)

Auth: Authorization: Bearer {accessToken} or ?token={accessToken}.

`GET /v1/numbers/{id}`

Poll status. 200:

`status`	Meaning	Extra fields
`waiting_code`	Still waiting	—
`completed`	SMS delivered, payment settled	`code`, `codes` (all codes), `settleTx`, `PAYMENT-RESPONSE` header on the settling poll
`cancelled`	Cancelled	—
`expired`	Timed out	—

`POST /v1/numbers/{id}/cancel`

Cancel before delivery. Always settles $0. 409 if already finished.

Request another SMS for the same number after a code was already delivered (additional codes are free within the number's lifetime). 409 while the first SMS is still pending or the activation is finished.