How a Telegram Casino Pays Out Prizes While Everyone Sleeps

It is 3:07 in the morning and someone in São Paulo has just won 2,500 Telegram Stars from a case-opening bot. The animation lands, the confetti fires, the balance ticks up.

And then nothing happens, because the person who actually buys the prizes is asleep.

If you have built anything in this space — a casino, a case opener, a wheel, a raffle, a loyalty tier — you already know the shape of this problem. The game is the easy part. Randomness is a solved problem, the animation is a weekend, the Mini App shell is a template. What nobody tells you at the start is that the payout is the hard part, and that it is hard for a structural reason rather than a lazy one.

The wall every prize app hits

Here is the thing that surprises most builders, usually about a week before launch.

Telegram's Bot API will happily let your bot spend Stars. Since Bot API 8.0 in November 2024 you have had sendGift and giftPremiumSubscription, and since 9.0 in April 2025 you have had getMyStarBalance to read what is left. You can hand out prizes all day.

What you cannot do is put Stars in. There is no Bot API method to top up your own bot's Star balance. Not a slow one, not a rate-limited one — none. Your bot can drain a balance it already has and check how empty it is getting, and that is the whole surface.

So the Stars have to come from somewhere else. Which leads to the second wall: the bulk route is Fragment, and Fragment has no official public developer API. Every "Fragment API" you will find in a search — and there are dozens — is a reverse-engineered wrapper driving the web interface with a borrowed session. One of the more popular open-source ones opens its README by noting the author "didn't find any Official API" and built one anyway.

In November 2024 Fragment added mandatory identity verification to that purchase route. A meaningful slice of the wrapper industry now advertises "works without KYC" as its headline feature, which tells you precisely what those tools are for.

And the throughput question has no answer at all. A developer opened an issue on Telegram's own bot-api repository in June 2025 asking, in plain words, how many gifts per second can be sent through the Bot API. It was closed without a single reply. If you are planning capacity for a jackpot moment, you are guessing.

What the market actually does instead

Given all that, it is worth looking at what shipped products actually do. There are only two patterns out there, and neither is a pipeline.

Pattern one: recycle what users deposited. The large Telegram gift marketplaces work this way. The prize pool is other people's gifts — users deposit, the platform escrows and matches, and inventory is whatever the crowd happened to bring. It is elegant, it costs nothing to stock, and it means your prize pool is not something you control. You cannot decide to run a big weekend promotion if the crowd did not deposit the goods for it.

Pattern two: fund it by hand. The founder of one TON-based gift marketplace stated publicly that he personally put in over a million dollars to seed gift distribution on the platform. That is not a criticism — it clearly worked. But it is a person with a wallet, not a system, and it does not survive contact with a growth curve.

What is conspicuously missing is pattern three. Across everything we could find, no prize app publicly documents an automated way to buy its inventory. Not because teams are lazy, but because until recently the road did not exist: no official API, a KYC gate on the only bulk route, and a grey market of session wrappers in between.

The move that makes the problem disappear

The instinct is to solve inventory: buy in bulk, hold stock, monitor levels, top up before the weekend. Build a warehouse.

The better move is to notice you never needed a warehouse.

Prizes on Telegram are delivered to a username. That means you do not have to hold anything in advance — you can place one order at the exact moment a player wins, addressed straight to that player. The goods never sit on your books. There is no stock level to monitor, no capital parked in Stars you have not given away yet, and no 3 a.m. stockout, because there was never a stock.

The prize pool stops being a warehouse and becomes a line item.

Mechanically, a payout becomes four calls:

player wins
   │
   ├─ 1. GET  /v1/pricing            what does this prize cost right now?
   ├─ 2. POST /v1/recipients/check   can this player actually receive it?
   ├─ 3. POST /v1/orders             place it, with an Idempotency-Key
   │        └─ pay the order on-chain
   └─ 4. signed webhook  ──────────► credit the player, close the loop

Concretely, the order call looks like this:

curl -X POST https://api.mystars.tg/v1/orders \
  -H "X-Api-Key: $MYSTARS_API_KEY" \
  -H "Idempotency-Key: spin-8f24c1a7" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stars",
    "quantity": 2500,
    "recipient": { "username": "winner_handle" },
    "payment_currency": "ton",
    "callback_url": "https://your-app.example.com/webhooks/prizes"
  }'

That Idempotency-Key is doing more work than it looks like. We will come back to it.

The four things that break in production

Everything above is the happy path, and the happy path is not where prize systems fall over. These four are.

A retried spin pays twice. Your queue redelivers, your worker restarts mid-flight, a timeout fires while the request was actually fine. Now the same win is being paid a second time. This is why every order carries an idempotency key derived from the spin, not from the moment of the call: same spin, same key, and the second call returns the original order instead of creating another one. Get this wrong and you will find it during your first traffic spike, which is also the worst possible time.

The winner has no username. Telegram-side fulfilment resolves recipients by handle. A player with no @username set simply cannot be delivered to, and there is no clever workaround. The fix is ordering, not engineering: check eligibility before you render the win, and make setting a username part of the claim flow rather than a support ticket at 3 a.m.

The amount drifts. Crypto rounding, a wallet that shaves the last digit, a price that moved between quote and payment. Payments are matched inside a tolerance band — a little under, a little over — and anything outside it is not silently accepted. It is reversed on-chain to the sender, minus the network fee. Worth knowing in advance so it reads as designed behaviour rather than a bug.

Treating a non-final status as final. Order states include intermediate ones that look alarming and are not terminal. A held order is still being worked; it will resolve to delivered or reversed. Teams that treat it as failure re-create the order and pay for the same prize twice. Wait for the webhook — terminal means terminal.

Beyond the casino floor

The word in the title is "casino" because that is where the pain is sharpest, but the pattern is the same everywhere a machine has to hand a person something of value:

• Case and crate openers — the same flow, minus the wagering.
• Wheels and daily spins — retention mechanics that die the moment prizes need a human.
• Tournament and leaderboard payouts — settle a top-100 in one pass instead of one afternoon.
• Referral and loyalty tiers — "invite three friends, get Premium" only works if Premium actually arrives.
• Giveaways and quests — where drop-off is measured in minutes between winning and receiving.

One honest boundary: this covers Stars and Premium, not collectible NFT gifts. Those trade on their own secondary market and are a genuinely different problem. If your prize table is built on rare collectibles, this solves part of your stack and not all of it — and anyone who tells you otherwise is selling something.

A note on where this is legal

Worth saying plainly, because the category attracts a lot of loose talk.

Telegram removed a well-known casino brand's channel and bot in February 2025 for a terms-of-service violation, and Telegram's advertising rules restrict gambling content. Most of what surfaces when you search for "Telegram casino bot" is flagged by review outlets as unlicensed or outright fraudulent.

None of that is a reason to avoid building reward mechanics, and none of it is legal advice. It is a reason to know which business you are in. Prize fulfilment, loyalty rewards and lootbox mechanics sit in a different regulatory position than real-money wagering, and the licensing question is yours to answer with a lawyer in your jurisdiction — not something an API vendor can answer for you.

Where to start

If you are building any of the above, the shortest useful path is:

1. Read the developer overview to see whether the shape fits your stack.
2. Skim the API reference — the endpoints above are the whole payout surface.
3. Get a key from the bot and run a pricing call. Pricing and eligibility checks are reads; they cost nothing and move no money, so you can wire the whole flow before you commit to anything.

If you want the integration-level detail — SDK setup, the first backend route, webhook verification — that lives in our Fragment API SDK guide. And if you are new to what Stars actually are before you start handing them out, start with what Telegram Stars are.