Telegram Stars API for purchases and gifts

Validate a Telegram username, create an idempotent Stars order, reserve a funded TON or USDT balance, and confirm delivery without operating your own Fragment purchasing workflow.

Get an API key Open API documentation

Quantity: 50–1,000,000 Stars
Settlement: TON or USDT on TON
Delivery: Webhook and status polling
Retries: Idempotency-Key protected

What this API is for

Use the Telegram Stars API when your product needs to purchase or gift Stars to a supported Telegram username. The recipient-search endpoint validates the user and returns the provider hash required for the purchase. The order endpoint accepts quantities from 50 to 1,000,000 Stars and returns an asynchronous order record.

Fragment API is designed for server-side integrations. Your API key stays on your backend; your application sends a recipient search request, creates the order, stores its ID, and confirms the final result. The public contract is available as an OpenAPI document for code generators and AI coding tools.

This is a purchasing and gifting API. It is different from the Telegram Bot API flow for accepting Stars as payment inside a bot or Mini App. Use the product that matches the direction of value in your application.

Integration flow

Keep these steps in order so recipient validation, wallet reservation, and delivery state remain consistent.

01
Fund a developer balance
Deposit TON or official USDT on the TON network and wait until the selected balance is available.
02
Search the recipient
Call GET /star/recipient/search with the Telegram username and quantity. Store the returned recipient hash with your pending customer request.
03
Create the Stars order
POST the username, recipient hash, quantity, and wallet type with a unique Idempotency-Key header.
04
Confirm delivery
Store the order_id, handle order.completed or order.failed webhooks, and poll GET /orders/{order_id} as a fallback.

Create the order

The order call is asynchronous. A successful response reserves the amount and returns an order ID; it does not mean delivery is final.

POST /orders/starbash

curl -X POST "https://v1.fragmentapi.com/api/v1/partner/orders/star" \
  -H "API-Key: $FRAGMENT_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alexdev",
    "recipient_hash": "hash_from_recipient_search",
    "quantity": 100,
    "wallet_type": "TON"
  }'

Production decisions that matter

Search before every purchase

Recipient availability and provider data can change. Use the hash from the current search instead of keeping a permanent username-to-hash cache.

Treat 202 as accepted, not delivered

The create response confirms that the order was accepted and funds were reserved. Fulfill your customer only after the order reaches completed.

Retry with the same key

If a network timeout hides the first response, retry the same logical order with the same Idempotency-Key. A new key represents a new charge.

Price from the returned amount

The final order amount uses live provider pricing plus the 5% service margin. Keep your customer price and tax logic separate.

Frequently asked questions

Telegram's official Stars reference

What is the minimum Telegram Stars order?

The supported minimum is 50 Stars. The maximum supported quantity for one order is 1,000,000 Stars.

Can I send Stars to any Telegram username?

The recipient must be supported by the provider at the time of purchase. Always run recipient search first and stop if it reports that the username is unavailable.

Is this the same as accepting Stars in a Telegram bot?

No. Fragment API purchases or gifts Stars to a recipient. Accepting Stars as payment for digital goods inside a bot or Mini App uses Telegram's Bot Payments API.

How do I prevent duplicate Stars purchases?

Generate one unique Idempotency-Key for the logical customer order and reuse that key for retries of the same payload.

What happens when a Stars order fails?

When failure is definitive before successful settlement, the full reserved order amount is returned to the same developer balance and recorded as a wallet transaction.