API Documentation — Telegram Auth API

Authentication

All client requests must include an API key in the request headers. User-facing endpoints on your mini-app should pass this key from your backend — never expose it in client-side code.

Header	Scope	Description
`X-API-Key`	Client application	Issued to your client account. Attach to every request your backend makes to the API.

⚠️ Security Notice
Keep your API key on the server side only. Never embed it in your mini-app frontend, mobile app, or public repository.

Workflow Overview

End-to-end flow for submitting and processing an account:

┌─────────────────────────────────────────────────────────┐
│  CLIENT (your backend / mini-app)                        │
│  1. POST /user/register        → register your end-user  │
│  2. GET  /pricing/view         → show prices to user     │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  USER (end-user submitting an account)                   │
│  3. POST /auth/request-otp     → receive OTP on phone    │
│  4. POST /auth/verify-otp      → submit OTP              │
│  5. POST /auth/verify-2fa      → (if required) password  │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  STATUS TRACKING                                         │
│  6. GET  /account/status       → poll by phone           │
│  7. GET  /user/balance         → check credited balance  │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│  WEBHOOK (optional)                                      │
│  POST your callback URL on account completion            │
└─────────────────────────────────────────────────────────┘

Client Integration For Developers

Endpoints your backend calls to manage users and pricing.

POST /user/register ›

Register a new end-user under your client account. Returns a personal identifier and starting balance.

Request Body

Field	Type	Required	Description
`endpoint_name`	string	required	Your registered endpoint identifier
`telegram_user_id`	int	required	The end-user's Telegram numeric ID
`username`	string	optional	Telegram username (without `@`)
`first_name`	string	optional
`last_name`	string	optional

Example Request

curl -X POST https://tg-server-t88w.onrender.com/user/register \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_name": "default",
    "telegram_user_id": 123456789,
    "username": "johndoe"
  }'

Example Response

{
  "success": true,
  "message": "User registered successfully",
  "endpoint_name": "default",
  "user_identifier": "123456789",
  "api_key": "tma_xxxxxxxxxxxxxxxx",
  "balance": 0.0,
  "currency": "USD"
}

✓ Save the returned api_key. You can use it as user_identifier in subsequent requests to track this specific user's activity.

GET /pricing/view ›

Retrieve current pricing for your endpoint, optionally filtered by country.

Query Parameters

Name	Type	Required	Description
`endpoint_name`	string	required	Your endpoint identifier
`countries`	string	optional	Comma-separated: ISO code (`BD`), name (`Bangladesh`), or partial match

Examples

# All countries
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/pricing/view?endpoint_name=default"

# Specific countries
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/pricing/view?endpoint_name=default&countries=BD,IN,US"

Example Response

{
  "success": true,
  "message": "Pricing retrieved from cache",
  "data": {
    "endpoint_name": "default",
    "total_countries": 2,
    "pricing": {
      "BD": {
        "fresh_price": 3.50,
        "regular_price": 2.00,
        "spam_price": 0.80,
        "banned_price": 0.00
      },
      "IN": {
        "fresh_price": 4.00,
        "regular_price": 2.50,
        "spam_price": 1.00,
        "banned_price": 0.00
      }
    },
    "not_found": [],
    "currency": "USD",
    "cache_last_loaded": "2026-09-17T12:00:00"
  }
}

POST your-webhook-url ›

If you provide a webhook_url when submitting an account, the API will call it when processing completes.

Headers Sent

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`TgAuth-Webhook/1.0`
`X-Webhook-Event`	`account.completed`
`X-Webhook-Session`	Session UUID

Payload

{
  "event": "account.completed",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "+8801700000000",
  "endpoint_name": "default",
  "user_identifier": "123456789",
  "user_identifier_type": "telegram",
  "status": "completed",
  "account_status_type": "fresh",
  "credited_amount": 3.50,
  "final_price": 3.50,
  "balance_after": 12.80,
  "currency": "USD",
  "completed_at": "2026-09-17T12:15:00Z"
}

Retry Policy: Failed webhooks are retried up to 5 times with exponential backoff. Always respond with a 2xx status to acknowledge receipt.

User — Auth Flow For End-Users

Your mini-app calls these endpoints on behalf of a user who is submitting a Telegram account.

POST /auth/request-otp ›

Send an OTP to the user's phone number to start authentication.

Request Body

Field	Type	Required	Description
`phone_number`	string	required	E.164 format (e.g. `+8801700000000`)
`endpoint_name`	string	required	Your endpoint identifier
`user_identifier`	string	optional	The Telegram user ID of the submitter
`user_identifier_type`	string	optional	`telegram` · `email` · `username` · `custom_id`
`timeout_seconds`	int	optional	OTP validity window (30–3600, default 300)
`country_code`	string	optional	ISO-2 override (e.g. `BD`)
`use_proxy`	bool	optional	Route request through proxy (default `true`)
`webhook_url`	string	optional	Callback URL for completion notification

Example Request

curl -X POST https://tg-server-t88w.onrender.com/auth/request-otp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+8801700000000",
    "endpoint_name": "default",
    "user_identifier": "123456789",
    "user_identifier_type": "telegram",
    "use_proxy": true
  }'

Example Response 200 OK

{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+8801700000000",
    "endpoint_name": "default",
    "reject_2fa": false,
    "timeout_seconds": 300,
    "country_code": "BD",
    "proxy_used": true,
    "webhook_configured": false,
    "expires_in": 300
  }
}

POST /auth/verify-otp ›

Submit the OTP the user received on their phone.

Request Body

Field	Type	Required	Description
`session_id`	UUID	required	From `/auth/request-otp`
`otp_code`	string(5)	required	5-digit numeric OTP

Example Request

curl -X POST https://tg-server-t88w.onrender.com/auth/verify-otp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "otp_code": "12345"
  }'

Example Response — Success

{
  "success": true,
  "message": "Authentication successful. Session string saved to database.",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+8801700000000",
    "endpoint_name": "default",
    "session_string_saved": true,
    "pricing": {
      "fresh_price": 3.50,
      "regular_price": 2.00,
      "spam_price": 0.80,
      "banned_price": 0.00
    },
    "hold_info": {
      "hold_amount": 3.50,
      "expected_time": "6 hours",
      "message": "Your account is under review. Balance will be credited after processing."
    }
  }
}

Response variations:

requires_2fa: true → proceed to /auth/verify-2fa
is_rejected: true → endpoint does not accept 2FA accounts

POST /auth/verify-2fa ›

Submit the 2FA password when the account has two-factor authentication enabled.

Request Body

Field	Type	Required	Description
`session_id`	UUID	required	Same session
`password`	string	required	The Telegram 2FA password

Example Request

curl -X POST https://tg-server-t88w.onrender.com/auth/verify-2fa \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "password": "mySecretPassword"
  }'

GET /auth/check-session ›

Get the current state of an in-progress authentication session.

Query Parameters

Name	Type	Required
`session_id`	UUID	required

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/auth/check-session?session_id=550e8400-e29b-41d4-a716-446655440000"

POST /auth/logout ›

Terminate the session and clear the stored credentials.

curl -X POST https://tg-server-t88w.onrender.com/auth/logout \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'

User — Account For End-Users

Track submission status and view balance.

GET /account/status ›

Look up a submitted account's processing status by phone number.

Query Parameters

Name	Type	Required	Description
`endpoint_name`	string	required	Your endpoint identifier
`phone_number`	string	required	E.164 format
`user_identifier`	string	optional	Scope the lookup to this user

Example Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/account/status?endpoint_name=default&phone_number=%2B8801700000000"

Example Response — Completed

{
  "success": true,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "endpoint_name": "default",
  "phone_number": "+8801700000000",
  "status": "completed",
  "substatus": null,
  "message": "Account processed and credited",
  "hold_amount": null,
  "credited_amount": 3.50,
  "currency": "USD",
  "spam_status": "spam_free",
  "account_status_type": "fresh",
  "submitted_at": "2026-09-17T12:00:00",
  "completed_at": "2026-09-17T12:15:00"
}

GET /account/status/by-session/{session_id} ›

Look up account status by session UUID.

Path Parameters

Name	Type	Description
`session_id`	UUID	The session UUID

curl -H "X-API-Key: YOUR_API_KEY" \
  https://tg-server-t88w.onrender.com/account/status/by-session/550e8400-e29b-41d4-a716-446655440000

Status values: pending · processing · waiting_device_retry · completed · failed

GET /user/balance ›

Get a user's current balance.

Query Parameters

Name	Type	Required
`endpoint_name`	string	required
`user_identifier`	string	required

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/user/balance?endpoint_name=default&user_identifier=123456789"

Example Response

{
  "success": true,
  "endpoint_name": "default",
  "user_identifier": "123456789",
  "balance": 12.80,
  "currency": "USD"
}

GET /user/transactions ›

Get a user's transaction history (credits, holds, etc.).

Query Parameters

Name	Type	Required	Description
`endpoint_name`	string	required
`user_identifier`	string	required
`limit`	int	optional	Max results (default 50)

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tg-server-t88w.onrender.com/user/transactions?endpoint_name=default&user_identifier=123456789&limit=20"

Payment Method

We accept payments through Heleket — a fast and secure cryptocurrency payment gateway. Use it to top up your client balance for user payouts.

💎

Heleket Crypto Payments

Instant, low-fee cryptocurrency payments with automatic conversion. Supports BTC, ETH, USDT, TRX, and more.

heleket.com →

How it works: When your client balance is low, initiate a top-up via the Heleket payment link provided in your dashboard. Payments are credited automatically after network confirmation.

Status Codes

Code	Meaning
`200`	Success
`400`	Bad request — validation error, duplicate phone, expired OTP
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — resource not accessible to this user
`404`	Not found — session or resource does not exist
`429`	Too many requests — rate limit exceeded
`500`	Internal server error