SDKs: TypeScript, Python and Go
Buy a real number and get its SMS code in a few lines. This guide takes about five minutes.
1Get an API key
Create an account (you get free credit, no card), then open Dashboard → Developer and create a key. Keys start with notp_.
Save it as an environment variable. Every SDK, the CLI and the MCP server read it from there:
$ export NOTP_API_KEY=notp_your_key_hereread,buy scope.2Install
$ npm install numberotp$ pip install numberotp$ go get github.com/DishantSinghDev2/numberotp-goPackages: npm (Node 20+, Deno, Bun, edge runtimes, browsers) · PyPI (Python 3.9+, sync and async) · pkg.go.dev (Go 1.24+).
3Buy a number and wait for the code
createAndWaitbuys the number, hands it to you so you can type it into the app you're verifying, then waits for the SMS. Service wa is WhatsApp and country 16 is the United Kingdom.
import { NumberOTP } from 'numberotp' const notp = new NumberOTP() // reads NOTP_API_KEY const act = await notp.activations.createAndWait( { service: 'wa', country: '16' }, { onNumber: n => console.log('Use this number:', n.phoneNumber) },)console.log('Code:', act.otp) // no SMS in 20 min? refunded automaticallyActivationClosedError.4Find service and country codes
Search by name or by the website you're signing up on, then compare countries by price, stock and success rate.
await notp.services.search({ q: 'discord.com' }) // → [{ code: 'ds', name: 'Discord' }]await notp.countries.list()await notp.prices.get({ service: 'ds' }) // by country and pool5Step by step: resend, finish, cancel
When you need more control than createAndWait, use the individual calls. max_price makes sure you never pay more than you expect.
const n = await notp.activations.create({ service: 'tg', country: '187', max_price: 3 })console.log(n.data.phoneNumber) const act = await notp.activations.waitForCode(n.data.id, { timeout: '10m' })await notp.activations.resend(n.data.id) // another SMS on the same numberawait notp.activations.finish(n.data.id) // done — close it// or, if nothing arrived:await notp.activations.cancel(n.data.id) // full refund6Handle errors
Every error has an HTTP status and a stable code. Branch on the code, not on the message.
| Error | When | What to do |
|---|---|---|
InsufficientBalanceError | 402 — not enough balance | Top up in the dashboard. |
NotFoundError | 404 — e.g. code NO_NUMBERS_AVAILABLE | Try another country or pool. |
ActivationClosedError | The number expired or was canceled | It was refunded. Buy a new one if you still need a code. |
WaitTimeoutError | Your wait timeout passed first | The number is still open: wait again, or cancel it. |
AuthenticationError | 401 — missing or revoked key | Check NOTP_API_KEY. |
RateLimitError | 429 — too many requests | Already retried for you; slow down. |
Network errors, 429 and 5xx are retried automatically, and purchases carry an Idempotency-Key, so a retry can never buy twice.
The full list of codes is on the Error Codes page.
7Live events and webhooks
For many numbers at once, don't wait on each one. Stream every event, or let us call your server.
for await (const e of notp.events.stream()) { if (e.type === 'activation.code_received') console.log(e.data.otp)}Verify against the raw request body, before any JSON parsing. Payloads are described in the API reference.
8Configuration
| Option | TypeScript | Python | Go |
|---|---|---|---|
| API key | apiKey | api_key | WithAPIKey |
| Base URL (reseller domains) | baseURL | base_url | WithBaseURL |
| Timeout | timeout | timeout | WithTimeout |
| Retries (default 2) | maxRetries | max_retries | WithMaxRetries |
9Signing users in (apps, extensions, CLIs)
Building a client for other people? Don't ask for their API key. Use device sign-in: the user approves your app on numberotp.com, and you get tokens that refresh by themselves. Save them in secure storage with onTokens.
const notp = new NumberOTP({ onTokens: t => secureStore.save(t) })await notp.auth.deviceLogin({ client: 'cli', onCode: c => console.log('Open', c.verification_uri_complete, 'and confirm', c.user_code),})