Shiba Bank
EnglishEN
Open the app

Telegram Stars API: Stars and Premium through an API

The Shiba Bank Stars API: buy Telegram Stars and Telegram Premium for any @username with USDT or GRAM on TON, an MCP server for AI agents, a 3 % margin, request examples and answers.

Updated 2026-09-30 · 6 min read

The Stars API is the HTTP API of the Shiba Bank bot. Your service, bot or AI agent buys Telegram Stars and Telegram Premium for any public @username and pays with USDT or GRAM on TON, or with Stars already in its wallet in the bot. The bot buys the Stars through Fragment itself, delivers them to the recipient and answers with the transaction hash, so the delivery can be seen in a TON explorer.

What the API does

  • Buys Stars for any @username, from 50 Stars an order.
  • Buys Telegram Premium for 3, 6 or 12 months, as a gift to any account.
  • Checks the recipient before payment: a person or a channel, whether the account charges for messages, whether it already has Premium.
  • Sends Stars from your wallet to people's wallets in the bot: rewards, prizes, payouts.
  • Works with AI agents through an MCP server: prices, recipient checks, orders and their status as ready tools.

How it works

  1. In the bot, open /api, create a key and turn orders on; they are off by default.
  2. Get the price: GET /api/v1/quote?product=stars&quantity=1000.
  3. Check the recipient: POST /api/v1/recipients/check.
  4. Create the order: POST /api/v1/orders with product, quantity, recipient, pay and idempotency_key.
  5. Pay the invoice: the answer holds the project's address, the exact amount and a comment. For GRAM it also holds a ready TON Connect transaction; for USDT too, if you pass your wallet's address as payer_address.
  6. Wait for delivery: GET /api/v1/orders/{id}?wait=25 answers as soon as the status changes. Stars usually reach the recipient within a minute or two of the payment.
Important

The payment comment is the only thing that ties a transfer to the order. A transfer without the comment cannot be found.

What it costs

The margin on orders through the API is 3 % over what the Stars cost at Fragment, below the bot's own. GET /api/v1/quote returns the exact price in USDT, GRAM and wallet Stars. The price is fixed when the order is created, and max_price refuses an order above your ceiling. Orders paid with wallet Stars go one for one, with no fee.

Paying with wallet Stars

If your wallet in the bot holds Stars, send pay: "wallet": Stars go to the recipient one for one, and Premium is charged at its Stars price from /quote. Delivery starts at once, with no transfer on chain. Such orders count against the key's Stars limits together with transfers.

An MCP server for AI agents

Claude, Cursor, ChatGPT and any MCP client take the API as a set of tools at one address:

  • address: https://shiba-bank.com/api/mcp;
  • header: Authorization: Bearer <key>;
  • tools: get_prices, check_recipient, create_order, get_order, list_orders, send_stars, get_account.

For Claude Code it is one command: claude mcp add --transport http shiba-bank https://shiba-bank.com/api/mcp --header "Authorization: Bearer $SHIBA_API_KEY".

Tip

Have the agent pass an idempotency_key with every order and repeat the same key on a retry: a dropped connection then never becomes a second order.

Security

  • A key is 256 random bits. The bot keeps only its fingerprint and shows the key once.
  • Orders stay off until you turn them on in /api.
  • Limits: the amount of one invoice and of a day's invoices in dollars, Stars per transfer and per day; an allowlist of IP addresses.
  • Every order carries your idempotency_key: a repeated request never creates a second order.
  • The API answers servers only: a page on another site cannot use your key from a browser.
  • A key cannot change its own limits, turn orders on for itself or see other people's data: settings change only in the bot.

How it differs from buying on Fragment

Fragment is Telegram's platform where Stars and Premium are bought by hand: signing in with Telegram, a TON wallet, confirming every transfer. Through the API your service does the same in one request, and the bot takes care of buying on Fragment and of proving the delivery. About the platform itself, see Fragment on Telegram.

Fragment API: is there an official one

Fragment has no public API for buying Stars and Premium: as of September 2026, fragment.com offers developers neither documentation nor keys. The site is built for people: signing in with Telegram, a TON wallet and confirming every transfer in the wallet.

Whatever search results call a "Fragment API" is a third-party service or library, not Fragment and not Telegram. Some of them ask for your TON wallet's seed phrase, a sign-in to your Telegram or its session files, so they can pay on Fragment in your name.

Important

Never send anyone your seed phrase, the 24 words of your wallet. Whoever knows it controls all the money in the wallet, and there is no getting it back. The same goes for your Telegram login code and session files: they are access to the account. A genuine service never asks for them.

The Shiba Bank Stars API asks for none of it: the key is issued in the bot, and you pay the invoice with an ordinary transfer from your own wallet, or with Stars already in your wallet in the bot.

Questions

Is there an official Fragment API?

No: Fragment has no public API for buying Stars and Premium. Services that call themselves a "Fragment API" are third parties. Never give them your wallet's seed phrase or your Telegram sign-in.

What does connecting cost?

The key and the requests cost nothing: you pay for orders only, with a 3 % margin.

Can I buy Stars for somebody else's account?

Yes, for any public @username. Check the recipient before paying: a channel, group or bot cannot receive Stars, and an account with paid messages takes no fewer Stars than its message costs.

What happens if the Stars could not be delivered?

The order is refunded by the bot's rules, usually as Stars to the key owner's wallet, and its status becomes refunded.

What if I repeat a request after a dropped connection?

Send the same request with the same idempotency_key: the same order comes back, never a second one.

How many orders can I create?

One Stars invoice at a time, and no more than ten unpaid invoices within ten minutes. You set the ceilings for one invoice and for a day's invoices yourself in /api.

Where is the full documentation?

In the API documentation: every address, field, error code and examples in Python, Node.js and PHP. The machine-readable description is /api/v1/openapi.json.

Related guides