Quickstart

Create, pay, and poll your first sms4sats API v2 order.

This example uses the bearer-token receive-SMS API. It is the simplest integration for web apps, mobile apps, backend services, and bots.

1. Discover a service

curl -sS 'https://api.sms4sats.com/v2/receive-sms/catalog?country=auto'

Use a services[].code value in the next requests. country=auto lets sms4sats select a route using live availability and recent delivery performance.

2. Request a live quote

curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/quote \
  -H 'Content-Type: application/json' \
  -d '{"country":"auto","service":"tg"}'

{
  "type": "receive-sms",
  "country": "151",
  "service": "tg",
  "durationMinutes": null,
  "availability": 120,
  "priceSats": 350
}

A quote is side-effect free: it does not create an invoice or reserve inventory. Price and availability may change before creation.

3. Create the order

Generate a new UUID v4 once and reuse it only when retrying this exact request.

curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 17165eb7-d770-4a21-abd4-90295ac15252' \
  -d '{"country":"auto","service":"tg"}'

{
  "orderId": "<payment-hash>",
  "accessToken": "<opaque-token>",
  "orderReference": "<payment-hash>.<opaque-token>",
  "invoice": "lnbc...",
  "priceSats": 350,
  "status": "pending_payment"
}

Store accessToken securely when it is returned. Treat it like a password: anyone who has it can read or cancel that order. Do not log it, place it in a URL, or expose it in analytics.

4. Pay and poll

Pay invoice with a Lightning wallet, then poll every 5–10 seconds:

curl -sS https://api.sms4sats.com/v2/receive-sms/orders/ORDER_ID \
  -H 'Authorization: Bearer ACCESS_TOKEN'

A successful order normally progresses through:

pending_payment → paid → allocating → waiting_for_sms → code_received → completed

The assigned phoneNumber appears after allocation. Delivered SMS content appears in messages.

5. Handle completion or cancellation

Stop polling on completed, cancelled, expired, or failed. If no message arrives, use the response's cancellation.eligible and cancellation.availableAt fields rather than a client-side guess.

curl -sS -X POST \
  https://api.sms4sats.com/v2/receive-sms/orders/ORDER_ID/cancel \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Continue with Catalog & Quotes or review Errors, Limits & Retries before shipping.