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 within 10 minutes, 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 →

The country field picks the number pool: us1 for Non-VoIP AT&T (highest delivery rate, best for strict services), us for cheaper VoIP, 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" } }

full loop

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

# 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.

add to your MCP client

{ "mcpServers": {
    "asms": {
      "url": "https://asms.ai/mcp",
      "headers": { "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 (ideally on the "us1" 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.

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 within 10 minutes 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. Switch to the us1 Non-VoIP AT&T pool (highest delivery), 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":"us1"}' | 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