Guide · PayStars

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:

PayStars API for developers: the full flow for selling Stars and Premium in your bot

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.

PartWhat it does
AccessX-API-Key header; keys are created in the dashboard
BalanceUSD, topped up with USDT (TON, BEP20 or TRC20)
PriceFragment price × 1.05, rounded up to the cent
Limit10 requests per second per key
TransparencyA 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

  1. Keep the API key in a server environment variable, not in the code.
  2. Run the whole flow with a small real order of 50 Stars.
  3. 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

Buy Stars and Premium with USD (USDT)

Via API key: 0% (plain Fragment price). Via the website: 5%.

Get started