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 and prices for a service
POST	`/v1/activations`	Buy a number. Body `{ "service", "country" }`
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

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.

Claude / Cursor config

{
  "mcpServers": {
    "otphero": {
      "command": "node",
      "args": ["./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 or copy that file, 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.