Quickstart: your first verification code in four requests

export FASTOTP_KEY="sk_live_..."

curl https://fastotp.io/api/v1/account \
  -H "Authorization: Bearer $FASTOTP_KEY"

{ "balance": "12.35" }

curl "https://fastotp.io/api/v1/routes?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $FASTOTP_KEY"

{
  "routes": [
    {
      "service": "whatsapp",
      "country": "indonesia",
      "price": "0.13",
      "status": "on_sale",
      "delivery": { "rate": 94.2, "orders": 1340, "window_days": 30 }
    }
  ],
  "next": null
}

curl -X POST https://fastotp.io/api/v1/orders \
  --max-time 30 \
  -H "Authorization: Bearer $FASTOTP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service": "whatsapp", "country": "indonesia", "max_price": "0.13"}'

{
  "id": "ord_9f2k1x",
  "status": "active",
  "service": "whatsapp",
  "country": "indonesia",
  "phone": "+6283150707440",
  "price": "0.13",
  "code": null,
  "created_at": "2026-10-12T08:55:30Z",
  "expires_at": "2026-10-12T09:15:30Z",
  "seconds_to_code": null
}

curl https://fastotp.io/api/v1/orders/ord_9f2k1x \
  -H "Authorization: Bearer $FASTOTP_KEY"

{
  "id": "ord_9f2k1x",
  "status": "completed",
  "service": "whatsapp",
  "country": "indonesia",
  "phone": "+6283150707440",
  "price": "0.13",
  "code": "482913",
  "created_at": "2026-10-12T08:55:30Z",
  "expires_at": "2026-10-12T09:15:30Z",
  "seconds_to_code": 11
}

curl -X DELETE https://fastotp.io/api/v1/orders/ord_9f2k1x \
  -H "Authorization: Bearer $FASTOTP_KEY"

{
  "id": "ord_9f2k1x",
  "status": "cancelled",
  "refunded": "0.13"
}

// verify.mjs: needs Node.js 18 or later, no packages.
// Run it with: FASTOTP_KEY=sk_live_... node verify.mjs
import { randomUUID } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";

const BASE = "https://fastotp.io/api/v1";
const KEY = process.env.FASTOTP_KEY;
const POLL_EVERY_MS = 4_000; // poll every 3 to 5 seconds
const GIVE_UP_AFTER_MS = 5 * 60_000; // keep above 2 minutes: no cancelling before that

if (!KEY) throw new Error("Set FASTOTP_KEY first.");

class ApiError extends Error {
  constructor(res, error) {
    super(`${res.status} ${error.code}: ${error.message}`);
    this.status = res.status;
    this.code = error.code;
    this.body = error; // extra fields live here: price, retry_after, fields
    this.retryAfter = Number(res.headers.get("retry-after")) || null; // seconds
  }
}

async function api(method, path, { body, headers, timeoutMs = 10_000 } = {}) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body && { "Content-Type": "application/json" }),
      ...headers,
    },
    body: body && JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new ApiError(res, data.error ?? { code: "unknown", message: res.statusText });
  return data;
}

// One Idempotency-Key per purchase, reused on every retry, so a retry after
// a timeout returns the first order instead of buying a second number.
async function createOrder(service, country, maxPrice) {
  const idempotencyKey = randomUUID();
  for (let attempt = 1; ; attempt++) {
    try {
      return await api("POST", "/orders", {
        body: { service, country, max_price: maxPrice },
        headers: { "Idempotency-Key": idempotencyKey },
        timeoutMs: 30_000,
      });
    } catch (err) {
      // Timeouts, network errors, 429 and 5xx are worth another try. Other errors are final.
      const final = err instanceof ApiError && err.status !== 429 && err.status < 500;
      if (final || attempt === 4) throw err;
      await sleep((err.retryAfter ?? 2 ** attempt) * 1000);
    }
  }
}

// Poll while the order is active, until the code arrives or we give up.
async function waitForCode(order) {
  const giveUpAt = Date.now() + GIVE_UP_AFTER_MS;
  while (order.status === "active" && Date.now() < giveUpAt) {
    await sleep(POLL_EVERY_MS);
    try {
      order = await api("GET", `/orders/${order.id}`);
    } catch (err) {
      if (!(err instanceof ApiError)) continue; // timeout or network error: poll again
      if (err.status === 429) await sleep((err.retryAfter ?? 5) * 1000);
      else if (err.status < 500) throw err; // a 4xx will not fix itself
    }
  }
  return order;
}

// Giving up: cancel, so the price comes back now and not when the order expires.
async function cancel(order) {
  for (;;) {
    try {
      return await api("DELETE", `/orders/${order.id}`);
    } catch (err) {
      if (err.code === "cancel_too_early") {
        await sleep(err.body.retry_after * 1000);
      } else if (err.code === "not_cancellable") {
        // It ended on its own. The code may have arrived this very second.
        return api("GET", `/orders/${order.id}`);
      } else {
        throw err; // left alone, the order still expires and is refunded
      }
    }
  }
}

const { routes } = await api("GET", "/routes?service=whatsapp&country=indonesia");
const route = routes[0];
if (route?.status !== "on_sale") throw new Error("That route is not on sale right now.");

let order = await createOrder(route.service, route.country, route.price);
console.log(`Number: ${order.phone}. Enter it in the app; waiting for the SMS.`);

order = await waitForCode(order);
if (order.status === "active") order = await cancel(order);

if (order.status === "completed") {
  console.log(`Code: ${order.code} (arrived in ${order.seconds_to_code} s)`);
} else {
  console.log(`No code. Order ${order.status}, refunded in full.`);
}

"""verify.py: needs Python 3.8 or later and the requests package.

Run it with: FASTOTP_KEY=sk_live_... python verify.py
"""
import os
import time
import uuid

import requests

BASE = "https://fastotp.io/api/v1"
POLL_EVERY = 4  # seconds; poll every 3 to 5 seconds
GIVE_UP_AFTER = 5 * 60  # seconds; keep above 120: no cancelling before that

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['FASTOTP_KEY']}"


class ApiError(Exception):
    def __init__(self, response):
        try:
            error = response.json()["error"]
        except (ValueError, KeyError, TypeError):
            error = {"code": "unknown", "message": response.reason}
        super().__init__(f"{response.status_code} {error['code']}: {error['message']}")
        self.status = response.status_code
        self.code = error["code"]
        self.body = error  # extra fields live here: price, retry_after, fields
        self.retry_after = int(response.headers.get("Retry-After", 0)) or None  # seconds


def api(method, path, timeout=10, **kwargs):
    response = session.request(method, BASE + path, timeout=timeout, **kwargs)
    if not response.ok:
        raise ApiError(response)
    return response.json()


def create_order(service, country, max_price):
    # One Idempotency-Key per purchase, reused on every retry, so a retry after
    # a timeout returns the first order instead of buying a second number.
    headers = {"Idempotency-Key": str(uuid.uuid4())}
    body = {"service": service, "country": country, "max_price": max_price}
    attempt = 1
    while True:
        try:
            return api("POST", "/orders", json=body, headers=headers, timeout=30)
        except ApiError as err:
            # 429 and 5xx are worth another try. Other errors are final.
            if attempt == 4 or not (err.status == 429 or err.status >= 500):
                raise
            time.sleep(err.retry_after or 2**attempt)
        except requests.RequestException:  # timeout or network error
            if attempt == 4:
                raise
            time.sleep(2**attempt)
        attempt += 1


def wait_for_code(order):
    # Poll while the order is active, until the code arrives or we give up.
    give_up_at = time.monotonic() + GIVE_UP_AFTER
    while order["status"] == "active" and time.monotonic() < give_up_at:
        time.sleep(POLL_EVERY)
        try:
            order = api("GET", f"/orders/{order['id']}")
        except ApiError as err:
            if err.status == 429:
                time.sleep(err.retry_after or 5)
            elif err.status < 500:
                raise  # a 4xx will not fix itself
        except requests.RequestException:
            pass  # timeout or network error: poll again
    return order


def cancel(order):
    # Giving up: cancel, so the price comes back now and not when the order expires.
    while True:
        try:
            return api("DELETE", f"/orders/{order['id']}")
        except ApiError as err:
            if err.code == "cancel_too_early":
                time.sleep(err.body["retry_after"])
            elif err.code == "not_cancellable":
                # It ended on its own. The code may have arrived this very second.
                return api("GET", f"/orders/{order['id']}")
            else:
                raise  # left alone, the order still expires and is refunded


routes = api("GET", "/routes", params={"service": "whatsapp", "country": "indonesia"})["routes"]
if not routes or routes[0]["status"] != "on_sale":
    raise SystemExit("That route is not on sale right now.")
route = routes[0]

order = create_order(route["service"], route["country"], route["price"])
print(f"Number: {order['phone']}. Enter it in the app; waiting for the SMS.")

order = wait_for_code(order)
if order["status"] == "active":
    order = cancel(order)

if order["status"] == "completed":
    print(f"Code: {order['code']} (arrived in {order['seconds_to_code']} s)")
else:
    print(f"No code. Order {order['status']}, refunded in full.")