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
usernameandamounttoPOST /stars/buy— the Stars are delivered and the response contains anorder_id.
Integration flow
- Check the price
POST /stars/pricing - Check the username
POST /searchUser - Buy
POST /stars/buy - Track the status
GET /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
| Field | Type | Description |
|---|---|---|
X-API-Key | header | The cashier's API key. Required. |
username | string | Recipient's Telegram username (with or without @). Required. |
amount | integer | Number of Stars: 50 to 100,000. Required. |
currency | string | ton or usdt. Defaults to the cashier setting. |
Idempotency-Key | header | Optional. Not required: if the same order arrives twice in a row, the server drops the repeat itself. With a key, protection lasts 30 days. |
wait | boolean | Optional. 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
| Endpoint | Purpose |
|---|---|
POST /stars/pricing | Current price for a given amount |
POST /searchUser | Check a username before buying |
GET /order/{order_id} | Final order status |
POST /premium/buy | Gift 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.