MrOTP API

Quick start

You'll need an API token. Create an account, sign in, and copy your token from the Profile page — then make your first call.

curl -X POST https://<host>/api/v1/get_phone \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

curl -X POST https://<host>/api/v1/get_otp \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "0195a2f0-1234-7abc-8def-123456789abc"}'

import requests, time

BASE  = "https://<host>/api/v1"
TOKEN = "your-api-token"
H     = {"X-Api-Token": TOKEN, "Content-Type": "application/json"}

# 1. get a phone number
r = requests.post(f"{BASE}/get_phone", headers=H, json={"service": "telegram"}).json()
request_id = r["data"]["request_id"]
phone      = r["data"]["phone"]
print("Phone:", phone, "(request_id:", request_id, ")")

# 2. poll until the code arrives
while True:
    r = requests.post(f"{BASE}/get_otp", headers=H, json={"request_id": request_id}).json()
    d = r["data"]
    if d["status"] == "otp":
        print("OTP:", d["otp"])      # e.g. 123456
        print("SMS:", d["sms"])
        break
    if d["status"] == "fail":
        print("Failed:", d["message"])
        break
    time.sleep(3)

Authentication

Every endpoint except /ping requires your API token. You can pass the token in any one of three places:

X-Api-Token: $TOKEN

?token=$TOKEN

{"token": "$TOKEN"}

Missing or invalid tokens return 401.

Response envelope

Every non-/ping response uses the same fixed shape. The HTTP status code always mirrors the code field.

{
  "code": 200,            // same as the HTTP status
  "message": "Success", // human-readable
  "data": { ... }        // endpoint-specific payload (or null)
}

Tip: branch on data for success values and on message for errors — but never on the code alone, since the same code can come with different messages.

How it works

The full lifecycle of a single OTP request, from your app to the SIM and back.

Liveness probe. The only endpoint that needs no token and returns plain text instead of JSON.

curl https://<host>/api/v1/ping

pong

Returns your current pre-paid balance as a string.

curl https://<host>/api/v1/balance \
  -H "X-Api-Token: $TOKEN"

{
  "code": 200,
  "message": "Success",
  "data": {
    "balance": "100.0000"
  }
}

Lists the active services (platforms) you can request, with the per-code cost and OTP timeout for each. Note data is a bare array, not wrapped in an object.

{
  "code": 200,
  "message": "Success",
  "data": [
    { "name": "telegram", "cost": "5.0000", "timeout_seconds": 120 },
    { "name": "whatsapp", "cost": "7.5000", "timeout_seconds": 180 }
  ]
}

Assigns an available SIM for a service and charges your balance. Use the request_id returned here to call get_otp.

curl -X POST https://<host>/api/v1/get_phone \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

{
  "code": 200,
  "message": "Success",
  "data": {
    "request_id": "0195a2f0-1234-7abc-8def-123456789abc",
    "phone": "8499880001",
    "service": "telegram",
    "cost": "5.0000"
  }
}

Possible errors: 404 no available SIM / unknown service, 400 missing service or insufficient balance, 503 maintenance mode.

Polls the status of a previous get_phone request. The data.status field tells you where you are in the lifecycle.

curl -X POST https://<host>/api/v1/get_otp \
  -H "X-Api-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "0195a2f0-1234-7abc-8def-123456789abc"}'

{ "status": "waiting", "phone": "8499880001" }

{ "status": "otp", "otp": "123456",
  "sms": "Your Telegram code is 123456",
  "voice_call": null, "phone": "8499880001" }

{ "status": "fail", "message": "timeout",
  "phone": "8499880001" }

Poll every few seconds until the status is otp or fail. A fail (timeout or error) refunds your balance automatically. Errors: 400 missing or invalid request_id, 404 request not found / not yours.

Error codes

All errors use the same envelope; the HTTP status equals code and the detail is in message.