A Telegram bot script for selling Stars: what ready-made builds include and what they leave out

The short answer for anyone looking for a Telegram bot script that sells Stars: it gives you the storefront, the checkout and the admin panel — but not the Stars themselves. The goods still come from outside: either from a third-party service, or from the owner by hand.

I read the source of the three builds that Yandex ranks first for queries about Telegram Stars shop scripts. In the first one, an admin sends the Stars by hand. In the second, automatic delivery costs you the mnemonic of your wallet. The third is a tidy 65-file project, and it is simply wired into somebody else's supplier API. All three lead to the same conclusion, and it has nothing to do with how well the code is written.

What a Stars shop script actually does

Any build of this kind is five pieces: a menu of packages, taking the money, an order database, an admin panel and delivery of the Stars. The script covers the first four. The fifth — sending them to the recipient — is covered by none of them, because you cannot buy Stars programmatically inside Telegram: the Bot API has no method for buying them with money, and a bot's balance fills up only from user payments.

The entire difference between the builds is how they solve a problem that is not theirs.

Build one: tidy, with a supplier over API

evansvl/telegram-stars-bot — open source under MIT, 65 files, aiogram 3, PostgreSQL, Redis, alembic migrations, Docker, two locales, a referral program. Created June 18, 2026, last commit July 3, 2026. You can tell it was written to be run, not to be screenshotted.

Buyers pay by card or SBP through WATA, plus TON: a separate poller watches the wallet for incoming transfers. The Stars themselves come from a service called GreenGamePay, in four requests:

POST /api/token            → token, lives about 15 minutes
POST /api/get_stars_price  → wholesale price of N Stars
POST /api/check_balance    → our prepaid balance
POST /api/buyStars         → deliver N Stars to @username, debit the balance

Even the most decent build is a shop on top of somebody else's balance. The arrangement is the same: the supplier buys and delivers, the script sells.

Things worth knowing about this project before you launch it:

• Authentication by login and password. The .env file holds GGP_USERNAME and GGP_PASSWORD, and a token is pulled from them every 15 minutes. If that access leaks, the whole account leaks; you cannot revoke one key and keep the rest.
• Delivery has no idempotency key. Only the username and the quantity go to buyStars. At the same time, the client retries on a timeout and on 429/500/502/503/504 — up to three attempts with a delay. A retry cannot tell "it never arrived" from "it arrived and the response was lost" — protection against a second delivery sits entirely on the service's side, and nothing in the code confirms it is there.
• Your markup is capped by the checkout. The pricing module shows it: the order total cannot be more than 1.5× the minimum — a WATA requirement. It works from 50 to 50,000 Stars.
• .env.example instead of .env. The author's keys are not in the repository. As you will see below, that is rare.

Build two: the Stars arrive on their own, but in exchange for your wallet

dobrozor/tg_buy_stars — ten files, telebot, SQLite, order export to Excel, YooKassa and TON payments, a small fixed referral bonus. Created in September 2025, last commit April 2, 2026. There is no license file in the repository at all.

Here the Stars come through a third-party service, api.fragment-api.com, and the mechanics are worth reading closely — they are typical:

POST /auth/authenticate/
{
  "api_key": "...",
  "phone_number": "+7...",
  "mnemonics": ["word", "word", ...],
  "version": "V4R2"
}

The response is a JWT, which is saved to a file next to the script, and the order goes out as a single POST /order/stars/ with a username and a quantity.

Look at what leaves your machine: a phone number and the mnemonic of the wallet — the seed phrase itself. Whoever knows it controls the money in that wallet. This is not a hole in one particular build, it is the condition of the deal: for the wrapper to buy Stars on your behalf, it has to pay from your wallet, which means owning it.

The rest is small stuff, but the small stuff costs money:

• creating a payment in YooKassa does have an idempotency key, but the Stars order again has none;
• payment is detected by polling the status; there is no webhook with signature verification;
• the price of a Star is a constant, STAR_PRICE = 1.5 in the config, with a minimum of 50 Stars;
• the repository has .env committed — with the bot token, the checkout's secret key, the TON API key, and the key and mnemonic for the wrapper. I did not check whether the values are live; what matters is that this is what passes for normal in this genre.

Build three: storefront and checkout, delivery by hand

MrShoon/StarsShopTG — a single 1,265-line main.py, aiogram 3, SQLite, Apache-2.0 license. Created and last updated on January 6, 2026, and untouched since.

Inside are six packages — 100, 250, 500, 1,000, 2,500 and 5,000 Stars — with the price of each hard-coded as a constant. Two payment methods: YooKassa and a card transfer confirmed by hand. The list of admin IDs sits right in the code, on line 26.

And now the main thing: searching the whole file turns up no fragment, no XTR currency, and no other way of sending Stars at all. It works like this: the admin presses a button, the status flips to completed, and the buyer gets "The administrator has issued you N Telegram Stars". Whether the admin actually sent anything, the code neither knows nor checks.

This is not a shop, it is an order form. A buyer pays in the middle of the night, and in the middle of the night somebody has to buy the Stars and send them by hand. The prices have not moved since January either: the 100-star pack costs about 10% more per unit than the 5,000-star one, and both rates are frozen in the source. It looks attractive to a buyer, but the moment your own cost goes up, every order is a loss.

What all three have in common

Not one of the three Telegram bots takes delivery to the point where you could leave it unattended. The list of what is missing from every build is short, but it is exactly what separates "works in the author's video" from "works for you with real buyers":

• idempotency on delivery — a retry after a timeout can send the goods twice;
• an automatic refund — delivery falls over, the money is left hanging on somebody else's side, and you are the one who sorts it out;
• a recipient check before payment — a typo in a username is paid for with your goods;
• sensible behavior when funds run out — the order hangs instead of failing honestly;
• handling of partial delivery — what to do when half the order arrives is a question none of them answer.

This is not about the storefront, it is about the delivery layer. A storefront you can take ready-made and finish to taste. Delivery you cannot.

Four risks a script brings with it

Somebody else's keys in the bundle. If the archive contains a filled-in .env, you have no idea whose keys those are or who else is reading them. The first thing to do after unpacking is to throw out every value and issue your own.

An unclear license. MIT and Apache-2.0 are permission. A missing license file means the opposite: by default all rights stay with the author, and formally you may not use the code in your own project.

Abandonment. Two of the three builds have not been touched in months, and Telegram has changed the Bot API more than once in that time. Not one of them has tests — fixing it will be on you.

Forum builds with no source. Half the results for the query are threads on closed forums where a build along the lines of "automated Stars and Premium shop" is sold as a file. You cannot read the code before you pay, and afterwards it is too late: you will not find a backdoor in a hundred kilobytes of obfuscated Python. If you buy one anyway, run it on a separate server and with separate keys.

How to check somebody else's script in fifteen minutes

Do not read all the code — look for the answers to seven questions. The first three you find with an ordinary search across the folder:

grep -ril "fragment\|buyStars\|order/stars\|XTR\|sendGift" .
grep -rin "mnemonic\|seed\|phrase\|private_key" .
grep -rn "Idempot\|idempotency" .

1. How the Stars are delivered. The first search finds nothing — delivery is manual, and this is an order form.
2. Whether it asks for a mnemonic. The second search hits inside the auth code — you are handing your wallet to somebody else.
3. Whether the order has idempotency, not just the payment. That is exactly where the difference lies.
4. Where the price comes from. A constant in the config means that when rates move, you sell at a loss.
5. How payment is detected. Polling in a loop, or a webhook with signature verification.
6. The date of the last commit. git log -1 --date=short — then compare it with the date of the latest Bot API changes.
7. The license. No file, no permission.

What to write yourself, and what not to

The question "how do I build a bot that sells Stars" comes down to four things, and your own code is needed for exactly those: packages on the storefront, the checkout, one request to the supplier, and showing the buyer a status. That is an evening's work in aiogram or telebot, and the ready-made builds do fine as a reference — look at how they handle keyboards, states and order storage.

What you should not write yourself is the buying of the Stars. Purchase logic, delivery to a username, retries, refunds and statuses are the supplier's job. That happens automatically on their side, and that is precisely what you pay for in this arrangement. How the shop bot itself is put together is covered separately: what a bot for selling Stars is made of.

The "your own TON wallet plus your own plumbing into Fragment" route works too, but it is not an evening's script: you keep a TON reserve against price swings, watch every delivery, work through the failures, and rewrite the plumbing after each change on Telegram's side.

Our API covers the half a script does not

We are a Telegram Stars supplier: Stars and Premium at wholesale over a REST API, up to 50,000 Stars per order, with the Stars going to the recipient as an official transfer to their username — usually within a couple of minutes. An idempotency key on the order, a recipient check before payment, webhooks signed with X-Signature, an automatic refund on failed delivery, 120 requests per minute per key.

The wallet and the mnemonic stay with us. You get a key of the form pk_live_... — you can restrict it by IP and reissue it at any time in the dashboard, without changing your account password. What every method does and which errors exist is visible up front: the Telegram Stars API documentation and the machine-readable spec are public.

FAQ

Is there a free Stars shop script that works out of the box? A storefront with checkout, yes — several are public, and one of them is written well. None of them comes with goods: the script either leaves delivery to an admin, or calls a service you have to get access to separately.

Why do the wrappers ask for a wallet mnemonic? Because buying Stars on Fragment is paid for out of a wallet. Without access to it, the service cannot make the payment for you. There is one way around it — work with a supplier that pays from its own wallet and hands you the finished goods.

Can I take a forum build and just change the keys? Changing them is mandatory, but it is not enough: the code you never read is still there. The minimum is a separate server, a separate bot token and a test payment setup for your first orders.

What is wrong with an Idempotence-Key on the payment only? It protects the buyer from being charged twice, but not from the goods being delivered twice. These are different requests to different systems, and both of them need a key.

Do I need a database? Yes, SQLite at the very least: without stored orders you cannot settle disputes or issue a refund. Keep the payment ID and the order's idempotency key alongside the order.