Telegram Stars API: what the official Bot API can do and how to sell Stars through an API

The short version, if you came here for the answer: the official Telegram Stars API can accept Stars from users and spend them on gifting Premium, but you cannot buy Stars for money programmatically. There is no method for it in the Bot API, and Fragment has no public API either. That is why shops work through a supplier: they buy the product at the wholesale price, and the bot or site only places the order.

Below: a method-by-method breakdown with the parameters from the documentation, a minimal payment flow, the selling model, and a checklist for picking a supplier's API.

What the Bot API officially does with Stars

Everything listed here is in the reference at core.telegram.org/bots/api — checked on August 11, 2026.

Accept payment. sendInvoice and createInvoiceLink issue an invoice where currency equals XTR — the code for Telegram Stars. The user pays out of their own balance, and the Stars land on the bot's balance. This is how digital goods are monetized inside Telegram: access to content, a subscription to a service, features in a mini app.

Refund a payment. refundStarPayment returns successfully paid Stars to the user.

Check the history. getStarTransactions returns the list of operations on the bot's balance.

Gift Premium. giftPremiumSubscription issues a subscription to a specified user. The parameters are rigid, and that is worth remembering:

The method takes no other values — not one month, not an arbitrary amount.

Send a gift. sendGift sends a gift to a user or to a channel, and the recipient cannot convert it into Stars. Alongside it sit upgradeGift, transferGift, convertGiftToStars and getAvailableGifts.

Business account operations. getBusinessAccountStarBalance and transferBusinessAccountStars only work with a connected business account and the matching rights — for an ordinary bot that path is closed.

How to accept Stars payments in your own bot

If you sell a digital product inside the messenger, Telegram Stars are easier than wiring up card processing: the checkout is already built into the client, and the user pays in two taps. The official Telegram Bot Payments section describes the whole flow; here is the condensed version.

1. Invoice. The bot calls sendInvoice (or createInvoiceLink, if you need a link) with currency: "XTR" and a price in Stars. No provider_token is required for Stars invoices.
2. Confirmation. Before the charge, a pre_checkout_query arrives — you have ten seconds to answer it, or the payment is canceled.
3. Payment received. A message with successful_payment comes in, carrying the payment identifier. That is what you store in your database: refunds are made against it.
4. Delivery. From there your code hands the customer what they bought.

Setting up payment via Telegram Stars takes an evening, and it is the one place where the official Stars API does the job it was built for. It is no use for selling the Stars themselves for money — we get into why next.

What the Bot API does not have

The difference between "accepting Stars" and "buying Stars" breaks most plans, so let me say it plainly.

There is no method to buy Stars for money. Not with fiat, not with USDT, not with TON. The bot's balance fills up exactly one way — through payments from Telegram users. For a shop that is a catch-22: to sell the product you first have to get it somewhere, and there is nowhere to get it programmatically.

There is no way to send Stars to an arbitrary user. giftPremiumSubscription gifts a subscription, sendGift sends a gift, but "send 500 Stars to this username" does not exist in the Bot API.

There is no way to top up the bot's balance through the API. No method accepts money into the bot's account.

The conclusion: you cannot build a shop on the official Bot API. It is good for taking payment from customers, but it does not give you the product.

Why the "Fragment API" is not a Telegram product

Fragment is the platform where Telegram sells usernames and numbers, and it is also where people buy Stars and Premium. It has no public programmatic access: no keys, no method reference, no sandbox. Checked against current sources on August 11, 2026 — no official documentation exists.

Everything that comes back for the query "fragment api" is a third-party service. Some run their own infrastructure and sell access to it under that name; some wrap somebody else's dashboard. These projects have no connection to the messenger, and your agreement will not be with Telegram.

Building that plumbing yourself is doable, but count the full cost: a wallet holding spare TON to absorb rate swings, purchase automation, delivery monitoring, failure triage, and a rewrite every time something changes on the messenger's side. While the plumbing is down, sales are down.

How selling Stars actually works

The working model is simple:

1. You top up a balance with a supplier. That is prepayment for the product, usually in USDT.
2. The customer places an order with you — in a bot, on a site, in a mini app. You collect the payment through your own channels: card processing, bank transfers, crypto.
3. Your code sends the order to the supplier's Telegram Stars API — the recipient's username and the quantity.
4. The supplier delivers the product, you get the final status by webhook and show the customer the result.

Your revenue is the gap between your retail price and your cost. There is no warehouse, the product is digital, and all the logistics come down to a single HTTP request:

POST /api/partner/v1/orders
{
  "type": "stars",
  "params": { "quantity": 500, "recipient": "@username" },
  "idempotency_key": "order-1024"
}

The response carries the order number and a status; the final state arrives by webhook. That is how any decent Telegram Stars supplier works — the differences start in the details, and the details are what you should check.

Checklist: how to choose a supplier's API

Look at the mechanics, not at the price in the ad. Seven points, every one of which has cost somebody money.

Idempotency. An idempotency key in the order request is mandatory. Without it, a retry after a timeout creates a second order and a second charge — and timeouts on mobile networks happen constantly.

A recipient check before payment. A separate method that takes a username and returns the name from the profile. That way the customer sees who the purchase is going to, and a typo in the handle does not turn into a gift for a stranger.

Signed webhooks. The status should arrive as an event, and the body should be signed with HMAC so a forgery is visible at the door. Polling in a loop instead of webhooks is the mark of a half-built service.

Automatic refunds on failure. If an order cannot be delivered, the money returns to your balance by itself, with no support ticket.

Predictable behavior when funds run short. The right answer is an immediate refusal with a clear code. The wrong one is to leave the order hanging until you top up.

Published limits. How many requests per minute, the maximum in a single order, which Premium terms exist. If that is not in the documentation, you will learn the limits in production, under load.

Open documentation. Methods and error codes are visible before you connect. When the reference is handed over "only after you pay an activation fee", you cannot assess the integration in advance.

A separate word on price: compare the final figure per unit, not the percentages in the ad, and check whether there are fees per order and per top-up. Wording like "discounts up to 40%" usually means individual haggling, not a published rate.

What you have to write yourself

If you are building a bot for selling Stars, your code is responsible for four things: the storefront with its packages, taking payment, calling the supplier's API, and showing the customer a status. The delivery logic stays on the supplier's side — you do not need to write your own delivery script, and you will not need ready-made source code from a forum for it. Telegram Bot libraries exist for every common language: aiogram and telebot on Python, Telegram.Bot for .NET, telegraf on Node.

A dedicated Telegram bot is not required for this: the same model works on a site or in a mini app. A bot for selling Stars is simply the shortest path — the interface already exists, there is no sign-up, and you can take payment the ways your audience is used to.

Four mistakes that cost money

Here is what most often breaks for people doing their first integration.

Calculating the price on your side. The reference figures in the catalog are a guide, not a calculation. The order amount is fixed by the response to the order-creation call, and that is what you build on — otherwise, when the rate moves, you will sell at a loss.

Trusting an "in progress" status. Telegram Stars reach the recipient within minutes, but an order does not count as fulfilled until the final status arrives. Showing the customer "done" any earlier is a reliable way to get a dispute.

Not verifying the webhook signature. An open endpoint with no HMAC check is an invitation to forge a "completed" status and get the product for free.

Keeping one key for everything. Keep the key that can place orders separate from your test key, and restrict it by IP: a leaked key is your balance in someone else's hands.

All of this is easy to test on a small scale: build a storefront with one package and run the full cycle — invoice, payment, order, webhook. The Telegram Stars go to your own test account, and the whole check costs you the price of one package.

Our API, if you need a supplier

We supply wholesale Telegram Stars and Premium over a REST API: up to 50,000 Stars per order, 3, 6 or 12 months of Premium, delivery by official transfer to a username, usually within a couple of minutes. Everything from the checklist above is there — an idempotency key, a recipient check, webhooks signed with X-Signature, automatic refunds, 120 requests per minute per key.

The documentation and the OpenAPI spec are open before you connect: see the methods. You issue the key yourself in the dashboard, and the first top-up starts at 10 USDT.

Frequently asked questions

Can you buy Stars through the Bot API? No. There is no method for buying them with money; the bot's balance fills only through payments from Telegram users.

Is there an official Fragment API? No. There is no public documentation, no keys and no sandbox; services under that name are third-party.

Can you gift Premium through the API? Yes, giftPremiumSubscription — but it is charged to the bot's Stars balance: 1000 for 3 months, 1500 for 6, 2500 for 12.

How does a supplier's API differ from the Bot API? The Bot API takes payments inside the messenger; a supplier's API gives you the product. A shop needs both pieces: the first is optional, the second is mandatory.

Do you need a ready-made shop script? No. A storefront and an API call are enough. Delivery, statuses and refunds are on the supplier's side.