Home / Telegram Stars API
Telegram Stars API

Send Telegram Stars with a single request

Send Stars to any Telegram user from your bot, store or Mini App. The purchase is executed via Fragment and paid from the TON wallet linked to your cashier.

How it works

  • Create a cashier in the dashboard — it gets its own API key.
  • Link a TON wallet to the cashier: create a new one or connect yours with a 12/24-word seed phrase.
  • Send username and amount to POST /stars/buy — the Stars are delivered and the response contains an order_id.

Integration flow

  1. Check the pricePOST /stars/pricing
  2. Check the usernamePOST /searchUser
  3. BuyPOST /stars/buy
  4. Track the statusGET /order/{order_id}

Request example

curl -X POST https://starsapi.uz/stars/buy \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "durov", "amount": 100}'

Response:

{
  "success": true,
  "data": {
    "transaction_id": "78f6a...",
    "order_id": "K7Q2MX"
  }
}

Parameters

FieldTypeDescription
X-API-KeyheaderThe cashier's API key. Required.
usernamestringRecipient's Telegram username (with or without @). Required.
amountintegerNumber of Stars: 50 to 100,000. Required.
currencystrington or usdt. Defaults to the cashier setting.
Idempotency-KeyheaderOptional. Not required: if the same order arrives twice in a row, the server drops the repeat itself. With a key, protection lasts 30 days.
waitbooleanOptional. By default success is returned as soon as the payment is broadcast (~1 s). true waits for on-chain confirmation (~3 s).

Pricing

The price comes from the current Stars rate on Fragment, plus a 1.5% service fee. If your account sold 100 000+ Stars in the last 7 days, the fee automatically drops to 1%. The first 20 orders on each account are fee-free, and failed orders are never charged. POST /stars/pricing returns the exact price.

Other endpoints

EndpointPurpose
POST /stars/pricingCurrent price for a given amount
POST /searchUserCheck a username before buying
GET /order/{order_id}Final order status
POST /premium/buyGift Telegram Premium

Frequently asked questions

What are the minimum and maximum amounts?

One order can send 50 to 100,000 Stars.

Which wallet pays for the order?

The TON wallet linked to the cashier, in Gram (TON) or USDT. Network gas is always paid in TON, so keep a small TON reserve in the wallet.

What if a request times out?

Resend it. If the same order arrives twice in a row, the server drops the repeat and returns the first order's response (duplicate: true). You can also check GET /order/{order_id}.

Minutes to your first order

Signing up and getting an API key is free. The first 20 orders on each account carry no service fee.

Start for free