Developers · API v1
API for Telegram Stars and Premium
Deliver Telegram Stars and Premium by @username straight from your shop, bot or CRM. One POST request and the customer has it. Wholesale prices, sandbox, webhooks and protection against double charges.
POST /v1/orders
Authorization: Bearer sk_live_…
{
"type": "stars",
"qty": 100,
"username": "@john",
"orderId": "order-123"
}{
"ok": true,
"orderId": "order-123",
"status": "completed",
"qty": 100,
"price": 0.121
}- 2–3 second delivery
- Idempotency by orderId
- Zero-cost sandbox
- HMAC-signed webhooks
Quick start
curl -X POST https://api.krab.gg/v1/orders \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"type":"stars","qty":100,"username":"@john","orderId":"order-123"}'Field names are also accepted in their "technical" form (recipient, externalId / idempotencyKey, product, quantity) — if you copy an example from another doc, no renaming needed.
Who it's for
Telegram shops and bots
Selling Stars and Premium in your bot or on your site? Take payment however you like and delegate delivery to the API — by @username, instantly.
Resellers
Buy wholesale from a USDT balance and resell at your own markup. The price is locked before the order via /price — predictable margin.
CRM and automation
Embed Stars and Premium delivery into your funnel: an order from your CRM → POST /orders → the customer gets it, no manual work.
Services and SaaS
Add Telegram top-ups as a feature of your product — no inventory, no manual fulfilment, one HTTP call.
What the API does
Stars and Premium
Deliver Telegram Stars (50 to 1,000,000 per order) and Premium for 3, 6 or 12 months by recipient @username — no password or wallet.
2–3 second delivery
Orders are fulfilled synchronously: call POST /orders and the customer gets the stars. Long cases finish in the background; status via API or webhook.
Idempotency by orderId
Your own order id on every request. Repeating the same orderId never creates a duplicate or double-charges — safe on retries.
Sandbox
A test key sk_test_ or dryRun: true — everything is calculated, but no balance is charged and nothing is delivered. Debug with zero cost.
Signed webhooks
order.completed / order.failed are pushed to your URL with an HMAC-SHA256 signature — no need to poll.
Single USDT balance
One USDT balance, topped up with crypto (USDT on TON). GET /price returns the exact order price before any charge.
Core endpoints
- GET
/v1/priceQuote a price (Stars / Premium) before ordering - GET
/v1/checkValidate a recipient by @username (can you send) - POST
/v1/ordersCreate and fulfil an order (idempotent by orderId) - GET
/v1/orders/:idOrder status: recipient, quantity, state - GET
/v1/balanceAvailable USDT balance - GET
/v1/depositUSDT top-up details (address + memo) - GET
/v1/webhookCurrent webhook and signing secret - POST
/v1/webhookSet the push-notification URL (+ signing secret)
Getting started
- 01
Get a key
Open the @apistarsbot cabinet bot, submit a request and issue an sk_live_ key (and sk_test_ for testing).
- 02
Top up the balance
Send USDT on TON to your address with the given memo. Crediting takes seconds.
- 03
Fulfil orders
Call POST /v1/orders with the recipient @username — the customer receives Stars or Premium.
FAQ
What can I deliver through the API?
+
Telegram Stars (50 to 1,000,000 per order) and Telegram Premium for 3, 6 or 12 months. The recipient is given by @username — no password or wallet needed.
How is it priced?
+
Prices are wholesale, settled from a single USDT balance. GET /v1/price returns the exact amount for a given order before you create it, so there are no rate surprises.
What prevents double charges?
+
Idempotency by your orderId: repeating a request with the same orderId returns the already-created order and does not charge again — safe on retries and flaky networks.
Is there a test environment?
+
Yes. A test key sk_test_ or dryRun: true — the order is fully calculated, but no balance is charged and nothing is delivered. Integrate with zero cost.
How do I know an order is done?
+
Two ways: poll GET /v1/orders/:id, or use a webhook — we POST to your URL with an HMAC signature on completion (order.completed / order.failed).
How is the API different from buying on the site?
+
The API is for shops, bots and CRMs: wholesale prices, programmatic delivery by @username, a single balance and idempotency. Buying on the site is for end customers.
Can I resell Stars and Premium at a markup?
+
Yes. You buy at the wholesale price from a USDT balance and set your own retail price — the margin is yours. The API just delivers the product to the recipient by @username.
Is the API suitable for a Telegram bot or shop?
+
Yes, that's the main use case: you take payment on your side and deliver Stars or Premium with a single POST /v1/orders. Idempotency by orderId prevents double delivery.
How do I get access?
+
Keys are issued in the @apistarsbot cabinet bot: open it, submit a request and issue your key. For volume terms — message support.
Need access?
Create a connection in the @apistarsbot cabinet bot and issue your key — sk_live_ and sk_test_ for testing. Need help with integration or volume terms — message support @heIIo_stars.