TeleAccountHub API

Browse live Telegram products, purchase with wallet balance, check order status, and download completed orders — all from one simple REST API.

Authentication

Authenticated endpoints require your API key in the standard Authorization Bearer header.

Authorization: Bearer tgsk_YOUR_API_KEY

Generate your API key inside the Telegram bot from Api Docs → Api Key.

GET /api/v1/instant/categories

Returns live product categories and stock counts. No API key is required.

curl https://telenumber.telekartstar.com/api/v1/instant/categories

{
  "ok": true,
  "has_purchasable_products": true,
  "message": null,
  "categories": [
    {
      "category_id": 1,
      "category_name": "Asia",
      "total_stock": 53489
    }
  ]
}

GET /api/v1/instant/categories/{category_id}/products

Returns live products in a category. Prices are wallet prices shown to customers.

curl https://telenumber.telekartstar.com/api/v1/instant/categories/1/products

{
  "ok": true,
  "category_id": 1,
  "products": [
    {
      "product_id": 56,
      "product_name": "Philippines +63",
      "total_stock": 15242,
      "retail_price_usd": 0.7245,
      "wallet_price": "$0.72",
      "wallet_unit_price": "$0.72"
    }
  ]
}

GET /api/v1/balance

Returns the current wallet balance for the API key owner.

curl https://telenumber.telekartstar.com/api/v1/balance \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "balance_usd": 315.56,
  "balance_display": "$315.56"
}

GET /api/v1/phone-numbers/services

Lists locally stocked phone-number services. Use the returned subcategory_id with the phone checkout endpoint. No API key is required.

curl https://telenumber.telekartstar.com/api/v1/phone-numbers/services

{
  "ok": true,
  "services": [
    {
      "service_id": 3,
      "subcategory_id": 3,
      "slug": "number_3",
      "name": "Nigeria Numbers",
      "type": "number",
      "stock": 42,
      "min_price_usd": 0.26,
      "max_price_usd": 0.31
    }
  ],
  "categories": []
}

POST /api/v1/phone-numbers/checkout

Purchases one phone number from wallet inventory. Use the returned order_id to poll OTP and 2FA. Send a unique X-Idempotency-Key so retrying the same request cannot charge the wallet twice.

curl -X POST https://telenumber.telekartstar.com/api/v1/phone-numbers/checkout \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY" \
  -H "X-Idempotency-Key: phone-order-123" \
  -H "Content-Type: application/json" \
  -d '{"subcategory_id":3}'

{
  "ok": true,
  "order_id": 381,
  "order_number": "TAH-NUM-T6S0CZ-7A91AE",
  "status": "completed",
  "service": "Nigeria Numbers",
  "phone": "+2349128175414",
  "twofa_password": "example-password",
  "price_usd": 0.26,
  "price_display": "$0.26"
}

GET /api/v1/orders/{order_id}/login-code

Returns the OTP currently stored for a locally purchased phone-number order, together with the phone, 2FA password, and OTP history. If no code is stored, it queues a code request. Use the asynchronous POST /api/v1/orders/{order_id}/otp-fetch endpoint to read the account session in the background.

curl https://telenumber.telekartstar.com/api/v1/orders/381/login-code \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "order_id": 381,
  "status": "completed",
  "phones": ["+2349128175414"],
  "twofa_password": "example-password",
  "otp_available": true,
  "live_fetch": {
    "ok": true,
    "error": null,
    "message": null
  },
  "latest_otp": {
    "code": "12345",
    "phone": "+2349128175414",
    "source": "auto",
    "created_at": 1783169600
  },
  "otp_history": []
}

POST /api/v1/orders/{order_id}/otp-fetch

Starts OTP fetching in the background and returns immediately. The worker reads the latest Telegram login code and checks for up to approximately 45 seconds.

curl -X POST https://telenumber.telekartstar.com/api/v1/orders/381/otp-fetch \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "job_id": "f7a78e6d9f4c4f51a6f23db4d4ff0c12",
  "order_id": 381,
  "status": "running",
  "status_url": "/api/v1/orders/381/otp-status?job_id=f7a78e6d9f4c4f51a6f23db4d4ff0c12",
  "poll_after_seconds": 3,
  "message": "OTP fetch started. Poll the status endpoint."
}

GET /api/v1/orders/{order_id}/otp-status

Checks an OTP fetch job. Status can be running, completed, not_found, or failed. Both not_found and failed are terminal; create a new job to check again.

curl "https://telenumber.telekartstar.com/api/v1/orders/381/otp-status?job_id=f7a78e6d9f4c4f51a6f23db4d4ff0c12" \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "order_id": 381,
  "otp_available": true,
  "latest_otp": {
    "code": "12345",
    "phone": "+2349128175414",
    "source": "api_job",
    "created_at": 1783169600
  },
  "job": {
    "job_id": "f7a78e6d9f4c4f51a6f23db4d4ff0c12",
    "status": "completed"
  }
}

POST /api/v1/instant/checkout

Purchases a product using wallet balance. The API checks product availability and balance before charging. If checkout fails after balance reservation, the balance is refunded automatically.

curl -X POST https://telenumber.telekartstar.com/api/v1/instant/checkout \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":2281,"quantity":1,"category_id":86}'

{
  "ok": true,
  "order": {
    "id": 376,
    "order_number": "TAH-EXAMPLE",
    "status": "processing",
    "product_id": 2281,
    "product_name": "Nigeria +234",
    "quantity": 1,
    "charged_usd": 0.299,
    "charged_display": "$0.30",
    "download_ready": false,
    "poll_url": "https://telenumber.telekartstar.com/api/v1/instant/orders/376",
    "download_url": null
  },
  "charged_usd": 0.299,
  "charged_display": "$0.30"
}

GET /api/v1/instant/orders/{order_id}

Checks the order status. Use the local TeleAccountHub order id returned by checkout. Supplier order IDs are never exposed.

curl https://telenumber.telekartstar.com/api/v1/instant/orders/376 \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "order": {
    "id": 376,
    "order_number": "TAH-EXAMPLE",
    "status": "completed",
    "product_id": 2281,
    "product_name": "Nigeria +234",
    "quantity": 1,
    "download_ready": true,
    "download_filename": "order-376.zip"
  }
}

GET /api/v1/instant/orders/{order_id}/download

Downloads the completed order ZIP. This endpoint returns a file when download_ready is true.

curl -L https://telenumber.telekartstar.com/api/v1/instant/orders/376/download \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY" \
  -o order-376.zip

POST /api/v1/instant/orders/{order_id}/otp-fetch

Starts OTP fetching from a completed instant order. The API downloads the order ZIP internally, extracts the phone, session and 2FA file, then reads the latest Telegram login code in the background for up to approximately 45 seconds.

curl -X POST https://telenumber.telekartstar.com/api/v1/instant/orders/376/otp-fetch \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "job_id": "f7a78e6d9f4c4f51a6f23db4d4ff0c12",
  "order_id": 376,
  "status": "running",
  "status_url": "/api/v1/instant/orders/376/otp-status?job_id=f7a78e6d9f4c4f51a6f23db4d4ff0c12",
  "poll_after_seconds": 3,
  "message": "OTP fetch started. Poll the status endpoint."
}

GET /api/v1/instant/orders/{order_id}/otp-status

curl "https://telenumber.telekartstar.com/api/v1/instant/orders/376/otp-status?job_id=f7a78e6d9f4c4f51a6f23db4d4ff0c12" \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "order_id": 376,
  "otp_available": true,
  "phone": "+2349128175414",
  "twofa_password": "example-password",
  "latest_otp": {
    "code": "12345",
    "phone": "+2349128175414",
    "source": "instant_zip",
    "created_at": 1788076923
  },
  "job": {
    "job_id": "f7a78e6d9f4c4f51a6f23db4d4ff0c12",
    "status": "completed"
  }
}

A running response can look like this before the OTP arrives:

{
  "ok": true,
  "order_id": 376,
  "otp_available": false,
  "latest_otp": null,
  "job": {
    "job_id": "f7a78e6d9f4c4f51a6f23db4d4ff0c12",
    "status": "running"
  },
  "phone": "+2349128175414",
  "twofa_password": "example-password"
}

Errors

Errors return JSON with ok:false, an error code, and a human-readable message.

{
  "ok": false,
  "error": "invalid_product",
  "message": "This product is no longer available."
}

Background OTP worker failures are returned by the status endpoint with HTTP 200 and job.status: "failed". When available, job.error contains the failure reason.