FOR AGENTS AND BUILDERS

API & MCP.

Same wallet, same numbers. Drive OTP Hero from your scripts or from an AI agent.

Every customer can create a key in Account. Send it as Authorization: Bearer otp_live_…. Spend comes from that user’s wallet. Cancel before a code arrives and the credit returns, same as the website.

01 · KEYS

Authentication

Create a key on your account page. It’s shown once. Base URL for production is https://otphero.dev.

Header

Authorization: Bearer otp_live_…

02 · REST /v1

HTTP API

Method	Path	What it does
GET	`/v1/balance`	Wallet USD balance
GET	`/v1/services`	Catalog. Optional `?country=`
GET	`/v1/countries?service=wa`	Countries, cheapest prices, and available price tiers
POST	`/v1/activations`	Buy a number. Required: `service`, `country`. Optional: `tierId`, `expectedPriceCents`.
GET	`/v1/activations`	Your activations
GET	`/v1/activations/:id`	Status + SMS code when it lands
POST	`/v1/activations/:id/sms`	Request another SMS
POST	`/v1/activations/:id/cancel`	Cancel and refund if no code yet
GET	`/v1/deposit-addresses`	BTC / ETH / USDT TRC-20 addresses
GET	`/v1/deposits`	Deposit history

Each country’s priceCents is its cheapest in-stock price. Its tiers list contains each option’s id, priceCents, and stock. Pass a tier’s ID as tierId to select that exact price option; omit it to choose the cheapest available tier. Pass expectedPriceCents to reject a changed quote with PRICE_CHANGED. Sold-out options return NO_NUMBERS without upgrading to a more expensive tier.

Buy a number

curl -s https://otphero.dev/v1/activations \
  -H "Authorization: Bearer otp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"0"}'

Poll for the code

curl -s https://otphero.dev/v1/activations/ACTIVATION_ID \
  -H "Authorization: Bearer otp_live_…"

Poll every few seconds while status is wait. When the SMS arrives, status is ok and smsCode is set.

03 · MCP

For AI agents

The MCP server wraps the same REST routes as tools. Point Claude, Cursor, or any MCP client at it with your API key. Tools: get_balance, list_services, list_countries, create_activation, get_activation, cancel_activation, resend_sms, get_deposit_addresses, list_activations, get_deposits.

Claude / Cursor config

{
  "mcpServers": {
    "otphero": {
      "command": "node",
      "args": ["/absolute/path/to/otphero/packages/mcp/index.mjs"],
      "env": {
        "OTPHERO_API_KEY": "otp_live_…",
        "OTPHERO_BASE_URL": "https://otphero.dev"
      }
    }
  }
}

The server script lives in the OTP Hero repo at packages/mcp/index.mjs. Clone the repository, run npm ci with Node.js 20 or newer, and use the absolute script path in your client configuration. Then set OTPHERO_API_KEY from Account.

04 · ERRORS

Error shape

JSON

{ "error": "Not enough balance", "code": "NO_BALANCE" }

Common codes: UNAUTHORIZED, NO_BALANCE, NO_NUMBERS, NOT_CANCELLABLE, NOT_FOUND, PURCHASE_PENDING. If allocation is unconfirmed, funds remain reserved for support review. Do not automatically retry a purchase: purchase requests are not idempotent.