Developers

One key. REST and MCP.

Order disposable numbers and read SMS / OTP codes from your code, or let an AI agent do it over the Model Context Protocol. Same Bearer key, pay per code, automatic refund if a code never lands.

Get an API key MCP for agents

Authorize and order in 3 steps

Get your key

Generate a Bearer key in the dashboard. One key works for the REST API and the MCP server.

Order a number

POST a service + country to /otp/order. We allocate a number and debit your wallet.

Read the code

Poll /otp/sms until the code arrives. If a number stays quiet, order another and keep the first: it auto-refunds 10 to 15 minutes after ordering, so you only pay for codes that land.

Authentication

Generate a key in your dashboard and send it as a Bearer token on every request. The same key authenticates both the REST API and the MCP server.

Authorization: Bearer $ASMS_KEY

REST API

Base URL https://asms.ai. All responses are JSON. OpenAPI spec →

Integrated with the anonymsms.com API? It keeps working unchanged: anonymsms API docs →

The country field picks the number pool: us1 for Non-VoIP AT&T (real carrier line, for strict services), us for VoIP High Quality, uk for the United Kingdom (+44), or au for Australia (+61).

GET/api/v1/balance

Current wallet balance.

{ "balance": 12.50, "currency": "USD" }

GET/api/v1/otp/services?country=us

Available services for a country, with live stock and retail price.

{ "country": "us",
  "services": [ { "service": "telegram", "price": 0.50, "stock": 240 } ] }

POST/api/v1/otp/order

Allocate a number and debit the wallet. Body: { country, service }.

{ "activationId": "12345",
  "phoneNumber": "+1•••••••",
  "price": 0.50, "balance": 12.00 }

GET/api/v1/otp/sms?id=12345

Poll for the code. Returns null until the SMS arrives.

{ "sms": { "code": "504913",
    "text": "Your code is 504913" } }

POST/api/v1/rentals/renew

Keep a rented number for another period, at today's price, from the wallet. Body: { number, period }. Charged only if it goes through.

{ "number": "447700900123", "period": "oneMonth",
  "price": 14.99, "balance": 5.01,
  "expiresAt": "2026-12-08T14:30:00.000Z" }

POST/api/v1/rentals/auto-renew

Renew a rented number from the wallet a day before it ends. Body: { number, autoRenew }.

{ "number": "447700900123", "autoRenew": true }

full loop

# order a US number for telegram
curl -X POST https://asms.ai/api/v1/otp/order \
  -H "Authorization: Bearer $ASMS_KEY" \
  -d '{"service":"telegram","country":"us"}'

# poll until the code lands (id from the order above)
curl "https://asms.ai/api/v1/otp/sms?id=12345" \
  -H "Authorization: Bearer $ASMS_KEY"

AI-native

MCP server

ASMS ships a native Model Context Protocol server so Claude and other agents can verify accounts on their own: get pricing, order a number, and read the code, all from the wallet you fund. Streamable HTTP, stateless, authenticated with your Bearer key or with “Sign in with asms” (OAuth).

ChatGPT and Claude: no key needed

Add a custom connector (ChatGPT: turn on Developer mode in settings, then create a connector; Claude: Customize → Connectors → Add custom connector) with the URL https://asms.ai/mcp and OAuth sign-in. You log in to asms.ai, approve the app, and it uses your wallet. Disconnect it any time under Connected apps on your dashboard.

Step-by-step setup for Claude, ChatGPT, Codex, Cursor, Grok and more

Clients that take a URL and headers (Cursor, VS Code, Windsurf, Codex, Gemini CLI, ...):

add to your MCP client

{ "mcpServers": {
    "asms": {
      "url": "https://asms.ai/mcp",
      "headers": { "Authorization": "Bearer $ASMS_KEY" }
} } }

or with Claude Code

claude mcp add --transport http asms https://asms.ai/mcp \
  --header "Authorization: Bearer $ASMS_KEY"

Tools

Tool	Description
`get_balance`	Get the current wallet balance for the authenticated account.
`get_pricing`	Get the retail price per OTP activation for a service in a country. Omit `service` to list prices for every available service.
`get_inventory`	Get how many numbers are in stock for a service in a country. Omit `service` to list stock for every available service.
`create_otp_order`	Buy a number to receive an OTP: allocates a number, debits the wallet, and returns an orderId + phoneNumber. Then poll with poll_sms. If no code arrives, do NOT cancel to retry: simply call create_otp_order again for a fresh number and keep polling that one. Unfilled orders auto-refund within 10 minutes, so you only pay for codes that actually land and there is no penalty for ordering repeatedly. When a service keeps rejecting codes, order on the "us1" (Non-VoIP AT&T) pool, which has the highest delivery rate. WARNING: this spends real wallet balance.
`poll_sms`	Check for the SMS / OTP code on an order. Returns the code once it has arrived, otherwise an empty result: poll again after a few seconds. If nothing lands after a minute or two, the fastest path is to order a fresh number with create_otp_order (prefer the "us1" Non-VoIP pool) and leave the original: it auto-refunds within 10 minutes. Never cancel just to retry, and there is no charge for ordering again, you only pay for codes that arrive.
`list_active_orders`	List recent OTP orders for the account (awaiting a code or already received).
`cancel_order`	Rarely needed. To retry a verification do NOT cancel: just call create_otp_order again, because every unfilled order auto-refunds within 10 minutes on its own, and cancel is blocked for the first 10 minutes anyway. Only use this to release an order you are certain you no longer need once its 10-minute hold has passed.
`get_rental_offers`	List the rental periods and prices for a country (1 day to 12 months). A rented number is yours for the whole period and receives every SMS sent to it, unlike an OTP order, which is for one code. Omit `country` to list the countries numbers can be rented in.
`rent_number`	Rent a phone number in a country for a period (get the periods and prices from get_rental_offers first). Debits the wallet and returns the number and when the rental ends. Read its SMS with read_rental_sms. WARNING: this spends real wallet balance; confirm the country, period and price with the user first.
`list_rentals`	List the account's rented numbers with their country, period, end date and whether auto-renew is on. Ended rentals are left out unless `includeEnded` is true.
`read_rental_sms`	Read the SMS a rented number has received during this rental, newest first. Poll again every few seconds while waiting for a message.
`cancel_rental`	Cancel a rented number and refund it. Only possible between 5 and 120 minutes after renting, and only if the number has received no SMS; after that the rental runs to its end date.
`renew_rental`	Keep a rented number for another period: the period is added to its current end, at today's price for that period in its country (see get_rental_offers). Possible from 2 hours after renting until 20 minutes before the end. Debits the wallet only if the renewal goes through. WARNING: this spends real wallet balance; confirm the number, period and price with the user first.
`set_rental_auto_renew`	With auto-renew on, the number is renewed for its rental period from the wallet a day before it ends (6 hours before for a one-day rental); if the balance is short then, the account is emailed and nothing is charged. Turning it on lets the wallet be charged later: confirm with the user first.

When a code does not arrive

You are only ever charged for codes that actually land. When a number goes quiet, the fastest and cheapest fix is to order another one, not to cancel. There is no penalty for ordering as many times as you need, so agents should retry freely.

Order again, do not cancel

Every order auto-refunds 10 to 15 minutes after ordering if no code arrives, so a dead number costs you nothing. Instead of cancelling and waiting, place a fresh order and poll that one. Cancelling is blocked for the first 10 minutes anyway, so re-ordering is always the faster path.

Why a code can stall

Most misses are the receiving service flagging the number, not a fault on our side. Order a fresh number on the us1 Non-VoIP AT&T pool, try a different service, or check the receiving side: IP reputation, a flagged device, or a suspended account. Full troubleshooting →

retry pattern

# order -> poll briefly -> if quiet, order again (the first auto-refunds)
for attempt in 1 2 3; do
  id=$(curl -s -X POST https://asms.ai/api/v1/otp/order \
    -H "Authorization: Bearer $ASMS_KEY" \
    -d '{"service":"telegram","country":"us"}' | jq -r .activationId)

  for i in $(seq 1 20); do
    code=$(curl -s "https://asms.ai/api/v1/otp/sms?id=$id" \
      -H "Authorization: Bearer $ASMS_KEY" | jq -r '.sms.code // empty')
    [ -n "$code" ] && echo "got code: $code" && exit 0
    sleep 3
  done
  # ~1 min with no code: leave this order (it auto-refunds) and buy a fresh number
done

Start receiving codes

Top up a wallet, generate a key, and you are live. No subscription, refund on any code that does not arrive.

Create an account See pricing

Last updated July 9, 2026