DEV Community: StarGate

Telegram Stars refunds and the 21-day window: what a bot that pays out for Stars must handle

StarGate — Sat, 24 Oct 2026 11:50:11 +0000

If your bot sells something that cannot be taken back (crypto, a gift card, a payout of any kind) for Telegram Stars, a refund or chargeback can leave you with neither the Stars nor the goods. This post collects what the Bot API and Telegram's terms actually say about refunds, and the pattern we use in a production bot: hold the payout through the refund window, detect refunds by polling getStarTransactions, and let users post collateral to skip the hold.

What Telegram says

Stars are not available at once. Bot Platform Developer Terms, section 6.2.4:

For technical reasons, Stars in your balance may not become available for advertising credits or rewards for up to 21 days after their receipt.

Chargebacks hit the bot's balance. From the Bot API description of StarTransaction:

Note that if the buyer initiates a chargeback with the payment provider from whom they acquired Stars (e.g., Apple, Google) following this transaction, the refunded Stars will be deducted from the bot's balance. This is outside of Telegram's control.

The developer terms add that the seller "will be responsible for the funds returned" and that Telegram "expressly discourages the real-time sale of digital products" that cannot be reclaimed after a successful dispute or chargeback.

You must handle disputes. Payments in Telegram Stars requires bots to answer /paysupport and to be "prepared to correctly process disputes and chargebacks". A bot refunds a payment itself with refundStarPayment(user_id, telegram_payment_charge_id).

None of these pages gives a deadline for chargebacks. The 21 days is the availability delay, and it is the window most services use for their own hold.

The attack

Buy Stars through the App Store or Google Play.
Pay your bot's invoice; the bot sends crypto immediately.
File a chargeback with the store. The Stars are deducted from the bot's balance.

The crypto is gone for good. This is not theoretical: it happened to us before we added a hold.

Pattern 1: hold the payout through the window

On successful_payment, store telegram_payment_charge_id together with your order. If the order is above a risk threshold, give it a hold_until = paid_at + 21 days and pay out from a scheduled job once that time has passed. Show the user the exact release date; a hold without a date looks like a scam.

Keep the threshold and the per-user risk rules on the server. If the quote endpoint reveals exactly which users or amounts are held, it tells an attacker how to stay just under the line.

Pattern 2: detect refunds by polling `getStarTransactions`

There is no webhook for a chargeback. Refunds show up in the bot's transaction list instead:

getStarTransactions(offset, limit) returns transactions "in chronological order", up to 100 per call. Keep the offset in persistent storage and walk forward from it.
A refund is an outgoing transaction: receiver is set (the docs name "a user for a purchase refund" as an example), with receiver.type = "user" and receiver.transaction_type = "invoice_payment".
receiver.invoice_payload is optional, so do not rely on it alone.
StarTransaction.id "coincides with the identifier of the original transaction for refund transactions" and, for incoming payments, "coincides with SuccessfulPayment.telegram_payment_charge_id". That gives a reliable link from a refund back to your order.

Match by payload first and fall back to the charge id. If neither gives exactly one order, do not guess: a fuzzy match can punish the wrong user. On a confirmed match, mark the order forfeited, record the debt on the account and block it.

Pattern 3: collateral instead of waiting

A hold protects you, but a 21-day wait is bad for users who sell regularly. The way around it is collateral: the user deposits crypto, and while its free amount covers the refund risk of a swap, that swap pays out at once.

Rules that kept it safe for us:

Reserve, then pay. Reserve collateral for a swap after the payment is confirmed and before the payout, under a lock (we use Symfony Lock), so two parallel payouts cannot both spend the same collateral.
Freeze per swap. Each reserved portion has its own unlock date, the end of that swap's refund window. One deposit can have several.
Forfeit on refund. The refund detector from pattern 2 forfeits exactly the collateral reserved for the refunded swap.
Cooldown after withdrawal. A short cooldown after a collateral withdrawal stops a deposit, swap, withdraw, refund loop.
Cover held swaps first. When new collateral arrives, release swaps that are already waiting before new ones use it.

Checklist

[ ] telegram_payment_charge_id stored with every order
[ ] payouts above the threshold held, with the release date shown to the user
[ ] getStarTransactions polled from a persisted offset
[ ] refunds matched by payload, then by charge id, with no fuzzy matching
[ ] refund leads to forfeit, debt and block
[ ] collateral reserved under a lock and frozen per swap
[ ] /paysupport answered

Disclosure: we build StarGate, a Telegram bot and web app that swaps Stars for GRAM, USDT, ETH and BTC, and the patterns above come from running it. This post was drafted by an AI assistant from our code and notes, and its quotes were checked against the Telegram documentation linked above.

How to sell Telegram Stars for crypto

StarGate — Fri, 23 Oct 2026 13:25:23 +0000

Turn Telegram Stars into GRAM, USDT, ETH or BTC: the official route, the bot route, and the 21-day hold.

Short answer. You can sell Telegram Stars for crypto in two ways. If you are a channel or bot owner, Telegram's official Fragment platform withdraws earned Stars to a GRAM wallet once you have at least 1,000 Stars and 21 days have passed. Anyone else can pay Stars to a swap bot such as StarGate, which pays out GRAM, USDT, ETH or BTC to a wallet you choose, from 25 Stars.

Can you sell Telegram Stars at all?

Telegram Stars are Telegram's built-in currency. You buy them in the Telegram app or through official Telegram bots and spend them in bots and mini apps.

There is no button in Telegram that turns purchased Stars back into money. What you can do is spend Stars in a bot that pays you crypto in return. That is how Stars exchange bots work: you pay a normal Telegram invoice in Stars, and the bot sends crypto to your wallet.

Option 1: Fragment (channel and bot owners)

Fragment is Telegram's own platform. It is the route for Stars you earned as a creator: paid posts, subscriptions, bot sales.

Only Stars received by your channel or bot can be withdrawn, not Stars you bought.
The minimum is 1,000 Stars.
Earned Stars become withdrawable 21 days after you receive them.
The payout arrives in GRAM to the wallet you connect on Fragment.

Option 2: a Stars swap bot (anyone with Stars)

A swap bot accepts Stars as payment and sends crypto. With StarGate it works like this:

Open @stargateton_bot or stargate.zone.
Choose Stars as what you send and the coin you want: GRAM, USDT (Jetton or ERC-20), ETH or BTC.
Paste your wallet address. No wallet yet? A free wallet takes a minute to create.
The app shows the exact amount you will receive before you pay. Confirm the Telegram invoice with one tap.
Follow the order screen. The crypto goes to the address you gave.

One swap takes from 25 to 10,000 Stars. The rate follows the market and already includes the service fee: the amount shown before you confirm is the amount you get.

Why some Stars payouts wait 21 days

Telegram lets Stars buyers ask for a refund within 21 days. A fraudster could pay Stars, take the crypto and then refund the Stars. To protect against that, larger Stars swaps are paid out after the refund window closes. The order shows the exact release date, and the crypto arrives by itself after it.

You can skip the wait with collateral: a refundable deposit in crypto. While your collateral covers the swap, the payout is sent at once. Details: The 21-day hold and collateral.

Fragment or a bot: side by side

	Fragment	Swap bot (StarGate)
Who can use it	channel and bot owners	anyone with Stars
Which Stars	earned Stars	any Stars you can spend
Minimum	1,000 Stars	25 Stars
What you get	GRAM	GRAM, USDT, ETH or BTC
When	21 days after the Stars were earned	at once with collateral, otherwise after the refund window
Price	Telegram's rate	market rate, shown before you pay

How much will I get for 1,000 Stars?

It depends on the rate at the moment you swap: it follows the market and changes during the day. Do not trust a fixed number from an article, this one included. Open the swap form and enter the amount: it shows exactly what will arrive before you pay anything.

How to avoid scams when selling Stars

A real service never writes to you first. "Support" that messages you first is fake.
Nobody honest asks for your seed phrase (secret words).
Payouts go only to the address you entered. Nobody needs a "fee" from you to unlock a payout.
Check the bot's username letter by letter. StarGate's official bot is @stargateton_bot, support is t.me/stargate_bridge.
Be careful with bots that "buy NFT gifts" for more than they are worth: many are wallet drainers.

FAQ

Can I sell Stars I bought, not earned?
Not through Fragment. Through a swap bot, yes: you spend them on the bot's invoice like on any other purchase.

Which coin should I choose?
GRAM if you stay in the Telegram ecosystem, USDT if you want a stable value, ETH or BTC if you already hold them.

What if I paid and the order closed?
Pay the invoice before the order timer runs out: an unpaid order closes by itself and nothing is charged. If you paid an invoice after the order had closed, write to support with the order number.

Can someone else pay for my order?
Yes, a friend can pay the invoice. The order and its payout stay yours. If the Stars payment is later refunded through Telegram, the order is forfeited.

Official links

Bot: t.me/stargateton_bot
Website: stargate.zone
Support chat: t.me/stargate_bridge
Email: hello@stargate.zone
How a Stars swap works, step by step: stargate.zone/docs/stars-swaps

Written by the StarGate team. StarGate is a wallet, swap and bridge service for crypto and Telegram Stars. About us and contacts: stargate.zone/about.

Originally published on Medium.