TeleKart Stars API

Browse Telegram Premium, Stars, and Gifts, place orders using wallet balance, and check order status from your own panel or app.

Authentication

Authenticated endpoints require your API key in the Authorization header.

Authorization: Bearer tah_YOUR_API_KEY

Generate your key inside the Telegram bot from API Docs then API Key. Keep it private because API orders spend your main wallet balance.

GET /api/v1/products

Returns all available product groups with product IDs and wallet prices. No API key is required.

curl https://api.telekartstar.com/api/v1/products

{
  "ok": true,
  "data": {
    "premium": [
      {
        "id": "premium_3m",
        "type": "premium",
        "title": "Telegram Premium 3 Months",
        "duration_months": 3,
        "price_usd": 13.49
      }
    ],
    "stars": [
      {
        "id": "stars_1000",
        "type": "stars",
        "title": "1000 Telegram Stars",
        "stars": 1000,
        "price_usd": 16.5
      }
    ],
    "gifts": [
      {
        "id": "gift_h_heart",
        "type": "gift",
        "source": "standard",
        "title": "Heart",
        "stars": 15,
        "price_usd": 0.26
      }
    ]
  }
}

GET /api/v1/products/premium

Returns Telegram Premium durations and prices.

curl https://api.telekartstar.com/api/v1/products/premium

{
  "ok": true,
  "data": {
    "premium": [
      {
        "id": "premium_3m",
        "type": "premium",
        "title": "Telegram Premium 3 Months",
        "duration_months": 3,
        "price_usd": 13.49
      },
      {
        "id": "premium_6m",
        "type": "premium",
        "title": "Telegram Premium 6 Months",
        "duration_months": 6,
        "price_usd": 17.99
      }
    ]
  }
}

GET /api/v1/products/stars

Returns Telegram Stars packs and the custom stars option.

curl https://api.telekartstar.com/api/v1/products/stars

{
  "ok": true,
  "data": {
    "stars": [
      {
        "id": "stars_50",
        "type": "stars",
        "title": "50 Telegram Stars",
        "stars": 50,
        "price_usd": 0.83
      },
      {
        "id": "stars_custom",
        "type": "stars",
        "title": "Custom Telegram Stars",
        "price_note": "Send stars in the order body. Price = stars * current star rate.",
        "star_rate_usd": 0.0165
      }
    ]
  }
}

GET /api/v1/products/gifts

Returns standard and custom Telegram gifts.

curl https://api.telekartstar.com/api/v1/products/gifts

{
  "ok": true,
  "data": {
    "gifts": [
      {
        "id": "gift_h_heart",
        "type": "gift",
        "source": "standard",
        "title": "Heart",
        "stars": 15,
        "price_usd": 0.26
      },
      {
        "id": "gift_c_1",
        "type": "gift",
        "source": "custom",
        "title": "Custom Gift",
        "stars": 500,
        "price_usd": 8.5
      }
    ]
  }
}

GET /api/v1/balance

Returns the current main wallet balance for the API key owner.

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

{
  "ok": true,
  "data": {
    "user_id": 123456789,
    "balance_usd": 25.5
  }
}

POST /api/v1/orders

Creates an order and deducts the required amount from your main wallet balance. Orders are sent to admin for delivery.

Premium order

curl -X POST https://api.telekartstar.com/api/v1/orders \
  -H "Authorization: Bearer tah_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"premium_3m","target":"@username"}'

Stars order

curl -X POST https://api.telekartstar.com/api/v1/orders \
  -H "Authorization: Bearer tah_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"stars_1000","target":"@username"}'

Custom stars order

curl -X POST https://api.telekartstar.com/api/v1/orders \
  -H "Authorization: Bearer tah_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"stars_custom","stars":750,"target":"@username"}'

Gift order

curl -X POST https://api.telekartstar.com/api/v1/orders \
  -H "Authorization: Bearer tah_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"gift_h_heart","target":"@username"}'

Response

{
  "ok": true,
  "data": {
    "order_id": "202607050001",
    "user_id": 123456789,
    "product_id": "stars_1000",
    "product_name": "stars_1000",
    "title": "1000 Telegram Stars",
    "quantity": 1,
    "target_accounts": "@username",
    "target_link": "https://t.me/username",
    "price_usd": 16.5,
    "status": "pending"
  }
}

GET /api/v1/orders/{order_id}

Checks an order created by your API key.

curl https://api.telekartstar.com/api/v1/orders/202607050001 \
  -H "Authorization: Bearer tah_YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "order_id": "202607050001",
    "product_name": "stars_1000",
    "price_usd": 16.5,
    "status": "pending",
    "target_accounts": "@username",
    "target_link": "https://t.me/username",
    "created_at": "2026-07-05 12:30:00"
  }
}

Errors

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

{
  "ok": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Not enough main wallet balance for this order.",
  "balance_usd": 2.5,
  "required_usd": 16.5
}