PayStars API for developers: the full flow for selling Stars and Premium in your bot
How the PayStars REST API works end to end: X-API-Key, username checks, USD quotes with max_usd, idempotent orders, the 409 price_changed error and TxId verification, as an integration plan.
Published: · Updated:

Want to sell Telegram Stars and Premium inside your own bot, shop or app? The PayStars API gives you one HTTPS interface and a USD balance shared with the website. Rather than repeating the API reference, this article shows how to build the integration from start to finish.
The architecture at a glance
Your system does three things: funds the balance with USDT, asks for a price and creates an order. Everything else, including delivery through Telegram's official purchase flow, happens on the PayStars side.
| Part | What it does |
|---|---|
| Access | X-API-Key header; keys are created in the dashboard |
| Balance | USD, topped up with USDT (TON, BEP20 or TRC20) |
| Price | Fragment price × 1.05, rounded up to the cent |
| Limit | 10 requests per second per key |
| Transparency | A public TxId for every completed order |
Stage 1: fund the balance
POST /usd/invoice with an amount and a chain ("ton", "bsc" or "trc20") returns an exact amount valid for 30 minutes. The minimum is 0.1 USDT.
Stage 2: verify the recipient
POST /api/v1/check-username checks the recipient and returns a short-lived verification token. That prevents payments to usernames that don't exist: if a customer makes a typo, you find out before anything is charged.
Stage 3: get and cap the price
POST /api/v1/usd/quote returns the current price (usd) and the markup (markup_percent: 5). The price follows the market, so:
- request a fresh quote before each order;
- pass max_usd equal to the quoted amount;
- always send currency: "USD", otherwise the account's saved preference is used.
Stage 4: create the order
POST /api/v1/stars/buy or /api/v1/premium/buy. Every request must carry an Idempotency-Key, so if the connection drops and you retry, you are not charged twice. Store the key alongside the order ID in your database.
Stage 5: track the status
GET /api/v1/order/{id} and /api/v1/orders give you statuses and history. Most orders are delivered within minutes. A completed order gets a TxId that both you and your customer can check on the PayStars public ledger.
Handling errors properly
- 409 price_changed means the price went above max_usd and nothing was charged. Get a new quote and show the customer the updated price.
- Rate limit: don't exceed 10 requests per second; add a queue or backoff.
- Retries: always reuse the same Idempotency-Key.
Before going live
- Keep the API key in a server environment variable, not in the code.
- Run the whole flow with a small real order of 50 Stars.
- Show customers their TxId, which builds trust.
Full docs and quickstarts: PayStars Stars API and USD pricing for the API. For in-bot payments, see digital goods in bots are paid only in Stars.
FAQ
Is there a sandbox?
There is no separate sandbox; test with small real orders (50 Stars) while integrating.
Which programming languages work?
Any language that can make HTTPS requests. There are quickstarts for Python, Node.js and PHP.
How do I fund the balance?
With USDT on TON, BEP20 or TRC20, minimum 0.1 USDT; each invoice has an exact amount valid for 30 minutes.
Sources
Related pages
Buy Stars and Premium with USD (USDT)
Via API key: 0% (plain Fragment price). Via the website: 5%.
More news
Telegram Stars and Premium in Uzbekistan: pay by card or with USDTBuying Telegram Stars or Premium in Uzbekistan: Uzcard and Humo through @StarKerakBot, USDT on paystars.uz/uz/, the official app routes and the local rules to know.Read →
How to reward contest winners with Telegram Stars or Premium: an organizer's playbookDelivering Telegram Stars or Premium to winners of your own quiz, contest or hackathon: budget, collecting @usernames, delivery through PayStars, and a follow-up report.Read →
PayStars FAQ: common questions about signing in, USDT top-ups, and Stars and Premium ordersThe most common PayStars questions on one page: signing in with Telegram, topping up with USDT (TON, BEP20 or TRC20), ordering Stars and Premium, delivery times, safety and the API.Read →