Telegram Stars API — MyStars Fulfilment API documentation

Changelog

Every change to the public API, newest first.

  1. v2.3.0feature

    Fragment's order refusals come back before payment, and on the webhook that closes an order

    `POST /v1/recipients/check` takes an optional `quantity` and `payment_currency`. With them, the check also opens that exact order at Fragment (no payment link, nothing signed), so a refusal that depends on the order rather than on the recipient — for example "You can buy a minimum of 12,500 stars" — comes back as `eligible: false` with Fragment's text in `telegram_message`. A Stars check opens the order when `quantity` is given (paid in `payment_currency`, `ton` if omitted); a Premium check opens it for `months` when `payment_currency` is given. A `quantity` outside 50–1,000,000 answers `400`. `POST /v1/orders` now runs the same check for the order's own quantity or months and currency, so such a refusal answers `422 recipient_ineligible` with `telegram_message` before the order exists, and counts toward the daily refusal budget like every other `recipient_ineligible`. `telegram_message` on `POST /v1/recipients/check` and on the `422 recipient_ineligible` error now carries Fragment's own text only for a refusal we recognise: our own sentences (such as `Username "x" not found on Fragment`) and unrecognised texts (such as "Unknown error") come back as `null` on the check and with no `telegram_message` on the 422. `reason` is unchanged: branch on `eligible` and `reason`, not on whether the text is present. The `order.failed` and `order.reversed` webhooks now carry `telegram_message`: Fragment's verbatim text of the last refusal it gave for this order, present only on `failed` or `reversed` orders; `null` when Fragment never refused it. `GET /v1/orders/{id}` returns the same text. Tenant webhook envelopes now carry `api_version: "2.3.0"`. Apart from `telegram_message`, requests without the new fields behave as before.

  2. v2.2.0breaking

    Order replays stop repeating payment details; new giveaway refusals, safe retries and hashes that match the results

    A `200` idempotent replay of `POST /v1/orders` now returns `payment` and `expires_at` as `null` once the order is no longer `awaiting_payment`: check `payment` (or `status`) before you pay. `POST /v1/orders` answers `429 rate_limited` once a tenant has collected the day's budget of `422 recipient_ineligible` refusals (200 by default), with `retry_after` and a `Retry-After` header that run to 00:00 UTC; a replay of an existing order still answers `200`. While the budget's last places are held by the tenant's own checks still running, a create gets a short `429` instead, with a `Retry-After` of a few seconds and no `retry_after`: retry it after `Retry-After`. `POST /v1/giveaways/{id}/fund` naming another currency than the giveaway's open funding order now answers `409 funding_order_open_in_other_currency` (with `currency`, the open order's currency) instead of `200`; a call with no body asks for `ton`, so while a `usdt_ton` order is open, send `currency: "usdt_ton"`. A batch that would take a partner condition past its cap is refused with `409 attestation_limit_reached` (with `limit`, the cap); a batch made only of ids the condition already holds (revoking or re-asserting them) is always accepted, even over the cap. An attestation batch that waits more than about 2 seconds for another batch of the same giveaway answers `409 busy` and writes nothing: send it again with the same key. A cancelled giveaway's attestations are deleted from 7 days after the cancellation (by default). A same-key retry of a keyed giveaway or series write after a timeout or `503` now gets the first `2xx` answer, or `409 idempotency_in_flight` with `Retry-After: 1` while that write still runs, instead of running it again; a refusal or a `5xx` is never kept, so a corrected request may reuse the key. The shared giveaway-quote ceiling's `429` carries `Retry-After`. Tenant webhook envelopes now carry `api_version: "2.2.0"`. `POST /v1/giveaways/{id}/close` now answers `closed_at` too, the same value as `GET /v1/giveaways/{id}`. A close whose entrant list is fixed too late for its own close time to anchor a beacon still in the future (a close finished by a retry) carries the moment the list was fixed as `closed_at`, and the draw's beacon follows it. `funding.tx_hash` in the giveaway detail is the transaction hash a TON explorer takes (64 hex characters or the 44-character base64 form), with no leading `0x`; a recorded value that is not a hash is `null`. `giveaway.delivery_updated` carries `purchase_tx` by the same rule as `winners[].delivery.purchase_tx` in the results, so a base64 hash is no longer `null`, and a state sent before its hash was known gets one more event for the same `delivery_id` and `status` with the hash. A `null` `purchase_tx` never replaces one already received for the same `delivery_id`: the two events share `created_at` and can arrive in either order. `giveaway.reversal_resolved` is sent once per reversal reaching `sent`, `skipped` or `cancelled`, the automatic refund included; an approval alone sends nothing, and `tx_hash` (as in `results.reversals[].tx_hash`) is `null` for a value that is not a hash. An entry's `seq` is its ID, one sequence shared by every giveaway: it orders entries but is neither a count nor a position in a giveaway. The draw's beacon is the first masterchain block at or after second `floor(closed_at) + min_delay_sec`, anchored on the published `closed_at`, and block `seqno - 1` precedes that second. For a beacon generated before 2027-01-01T00:00:00Z (by its time on chain), which was chosen to the second, a same-second `seqno - 1` is reported by the public verifier as unchecked, never as a pass or a failure; from then on it fails.

  3. v2.1.4fix

    Order webhooks carry the reversal reference

    The `order.failed` and `order.reversed` webhooks now carry `reversal_tx`, as the order webhook schema always declared: the reference of the reversal that returned your payment, or `null` while none has gone out (a reversal that goes out later sends no webhook — read it from `GET /v1/orders/{id}`). `order.delivered` and `order.expired` carry none. A payment returned after an order expired or was cancelled now also shows in that order's `reversal_tx` when we returned it outside the automatic flow. Tenant webhook envelopes now carry `api_version: "2.1.4"`; nothing else changes on the wire.

  4. v2.1.3fix

    A payment returned after a cancel shows on the cancelled order

    A payment that names an order you already cancelled is reversed to its sender as before, and the `cancelled` order now shows the reference of that reversal in `reversal_tx`, as an `expired` order already does for a late payment. The status stays `cancelled` and no webhook is sent for it. `Order.reversal_tx` now documents when it is set, and `reversal_tx` is now only ever a transaction reference or `null`, as documented: an order or campaign whose reversal is still in flight, or was confirmed without a reference we can show, reads `null` there (in `campaign.*` webhooks too) instead of an internal placeholder. Tenant webhook envelopes now carry `api_version: "2.1.3"`; nothing else changes on the wire.

  5. v2.1.2fix

    A payment without a usable memo no longer changes an order

    A payment that arrives with no memo, or with a memo that names no order, is reversed to its sender as before, but it is no longer matched to one of your pending orders by amount: no order is marked `failed` because of it and no `failed` callback is sent. The order it was meant for stays `awaiting_payment` and ends `expired` unless a payment carrying its memo arrives in time. `failure_reason` `no_memo` and `wrong_memo` are no longer set; orders failed earlier keep them. Tenant webhook envelopes now carry `api_version: "2.1.2"`; nothing else changes on the wire.

  6. v2.1.1fix

    Contract declares the 422 for a currency that is not offered

    Where USDT payments are not offered, `usdt_ton` answers `422 currency_not_available` and creates nothing. The reference now declares that 422 on GET /v1/pricing, GET /v1/pricing/batch and GET /v1/gifts, and POST /v1/orders lists it beside `recipient_ineligible`. The `payment` block of an order or campaign is present only while it awaits payment in a currency that is offered: a `usdt_ton` one reads `null` there, so pay in GRAM (`ton`) instead. Tenant webhook envelopes now carry `api_version: "2.1.1"`; nothing else changes on the wire.

  7. v2.1.0feature

    Partner marketing: campaigns, star gifts, giveaways, tenant webhooks

    New products on the same API key, enabled per tenant on request. Campaigns (`/v1/campaigns`, `/v1/capacity`) deliver Stars, Premium or a star gift (`/v1/gifts`) to a list of usernames: you see which recipients will not work and why before you pay, pay ONE transfer, and the undelivered value is reversed in one transfer at the end. Giveaways (`/v1/giveaways`, `/v1/giveaways/series`) run provably-fair giveaways in your Telegram chats, one-off or recurring, with your own attested entry conditions and an anti-bot policy; each is funded through its own one-time deposit address (`memo: null`, `address_kind: one_time_deposit`). Their events go to a tenant webhook endpoint as an envelope `{id, type, created_at, api_version, data}` signed with the new `X-Faas-Signature-V2` (HMAC over the send time and the body). Order callbacks are unchanged apart from additive fields: the `X-Faas-Signature-V2`, `X-Faas-Event-Id` and `X-Faas-Event-Type` headers and `id`, `type`, `created_at` after the existing body fields. Nothing existing was removed or renamed.

  8. v2.0.0breaking

    payment_currency is required

    POST /v1/orders, GET /v1/pricing and GET /v1/pricing/batch no longer default payment_currency to `ton` (the native coin GRAM, not USDT): a request without it is rejected with 400 bad_request, so no order or quote is ever made in a currency you did not choose. The `warnings` array and the `payment_currency_defaulted` warning are gone with the default. An idempotent retry must carry the currency too — for an order you created without it, retry with `payment_currency: "ton"`. Pass `payment_currency` on every create and pricing call.

  9. v1.15.0deprecation

    The payment block names the asset; omitting payment_currency is deprecated

    `payment_currency` defaults to `ton` — the native coin GRAM (ex TON), not USDT — and a payment in the wrong asset used to go unhandled until the order expired. Three changes. (1) The `payment` block on POST /v1/orders now also says what to send: `asset` (`GRAM` or `USDT`), `decimals` (9 or 6), `amount_smallest_unit` (the exact integer to send), `transfer` (`native` or `jetton`) and `jetton_master` (the USDT jetton master, `null` for GRAM). GET /v1/orders/:id and GET /v1/orders now carry `payment_currency` on every order, and the `payment` block while the order is `awaiting_payment` (`null` otherwise). Existing fields are unchanged, and `amount_ton` is now documented accurately: the order's GRAM price, which is the amount due only on a `ton` order. (2) Omitting `payment_currency` is deprecated and it will become required: POST /v1/orders, GET /v1/pricing and GET /v1/pricing/batch now return `warnings: [{ code: "payment_currency_defaulted" }]` when they applied the default — pass the currency explicitly. (3) A payment that names your order but arrives in the other asset is now reversed to the sender in the asset received, and the order is normally marked `failed` with the new `failure_reason` value `wrong_currency` once the payment has been returned (reference in `reversal_tx`, `failed` webhook sent). If that step cannot complete, the order expires and the payment is still returned.

  10. v1.14.0feature

    failure_reason now describes an order that is held, not only one that finished

    GET /v1/orders/:id could already return a `held` order, but `failure_reason` only documented the terminal values, so a held order carried a reason the spec never defined. Two values are now part of the contract. `reversal_pending` — the goods could not be delivered and your funds are still being returned; the order reaches `reversed` when that lands. `reversal_unsettled` — the return itself could NOT be delivered to your address (it kept refusing the transfer), so you do NOT have your money back yet and a person is settling it by hand; the order stays `held` until they do. Read the second one carefully against `undeliverable`: they share a word and point in opposite directions — `undeliverable` is about the GOODS and ends with you made whole, `reversal_unsettled` is about the RETURN and does not. No field was added or removed, and no terminal value changed.

  11. v1.13.0feature

    USDT (TON) orders can carry a network-gas-only processing fee

    For `usdt_ton`, the `fee` object on GET /v1/pricing, GET /v1/pricing/batch and the POST /v1/orders `payment` block now comes in one of two forms. A swap-backed order keeps the fee it has today — the 1% swap fee plus GRAM swap gas, labelled "1% swap + <gas> GRAM gas". An order settled without a swap is charged network gas alone, labelled "TON network gas": its `processing_fee` is a few cents, so its `amount` is lower for the same item. To tell the two apart, every `fee` object now carries a `kind` field — `swap` or `network` — so you can choose your own wording without parsing `description`, which stays a display label. The change is additive: no existing field changed, and `subtotal + processing_fee == total == amount` still holds, so keep paying exactly `amount`. An order whose fee is network gas alone never passes through the `swapping` status.

  12. v1.12.0feature

    Payment window extended to 2 hours

    An order now stays open for payment for 2 hours instead of 1. Nothing changed in the shape of any request or response: expires_at on the order is still the single source of truth for the deadline, it simply lands further out. If you read expires_at rather than assuming a duration, your integration needs no change — and the spec no longer quotes a duration anywhere, precisely so it cannot go stale again. One thing worth re-checking: the SDK helpers that wait for an order to settle default to a 30-minute budget, which is now a quarter of the window rather than half, so raise it if you rely on the default to cover a full payment window.

  13. v1.11.0feature

    Recipient checks now tell you when they could not decide

    POST /v1/recipients/check always returns an `indeterminate` boolean. It is `true` when the probe could not reach a verdict and the endpoint failed open — meaning `eligible: true` is a permissive default, not a measurement — and `false` on every real verdict. Previously the two were indistinguishable on the wire, so a degraded probe looked exactly like a confirmed-deliverable recipient. Treat indeterminate as "unknown", never as "yes": proceeding to POST /v1/orders is safe (it runs its own authoritative check), but do not show the buyer a confirmed recipient. Strictly additive — the field was previously absent, and absent means the same as `false`.

  14. v1.10.0feature

    Batch pricing + a dedicated order-lifecycle rate-limit bucket

    New GET /v1/pricing/batch quotes up to 200 Stars quantities in ONE request (deduped, sorted; per-entry amount + fee match GET /v1/pricing cent-for-cent) — built for storefronts refreshing a whole pack catalog. Also: POST /v1/orders, GET /v1/orders/{id} and POST /v1/orders/{id}/cancel are now metered by a dedicated per-minute bucket of the same size as your general budget, isolated from read traffic — a burst of pricing or catalog reads can no longer 429 an order create, status poll, or cancel (and vice versa). Both changes are strictly additive; keep reading the RateLimit-* headers.

  15. v1.9.0feature

    Payment window extended to 1 hour

    An order now stays open for payment for 1 hour instead of 15 minutes. The order's expires_at field is unchanged in shape and remains the single source of truth for the deadline — it simply lands further out, giving payers more time. No request or response field changed; if you read expires_at (rather than assuming 15 minutes) nothing in your integration needs to change.

  16. v1.8.2feature

    Order create response echoes what was ordered

    POST /v1/orders now returns type plus quantity (for Stars) or months (for Premium) — the field that doesn't apply is null — so the created order is self-describing, just like GET /v1/pricing and the order view. You no longer have to correlate the response back to your request. Purely additive; existing fields are unchanged.

  17. v1.8.1fix

    Clearer docs: request-flow diagram + recipient-check guidance

    The reference now leads with the recommended call order (pricing → recipient check → order create) and a request-flow diagram in Quick start. POST /v1/recipients/check explains why type is required and warns that a recipient who already has an active Premium subscription can't be gifted Premium — Telegram blocks it (eligible:false, reason already_subscribed; the order would 422). Docs only — no contract change.

  18. v1.8.0feature

    USDT payments show a processing-fee breakdown

    For usdt_ton, GET /v1/pricing and the order-create payment block now include a fee object — subtotal, processing_fee (the 1% swap + 0.5 GRAM gas), total and a description — so you can see exactly what the swap costs. The fee was ALWAYS included in amount; this only itemises it (fee.total equals amount, never adds to it). GRAM quotes return fee: null. Purely additive.

  19. v1.7.1feature

    Pricing response echoes what it priced

    GET /v1/pricing now returns type plus quantity (for Stars) or months (for Premium) — the field that doesn't apply is null — so the amount is self-describing and you no longer have to correlate the quote back to your request. Purely additive; existing fields are unchanged.

  20. v1.7.0feature

    New: list available products

    A new GET /v1/products endpoint returns the product catalog — the two product types (stars, premium) and the buyable shape of each (stars: a continuous quantity range 50–1000000; premium: the fixed tiers 3/6/12 months). It's price-free metadata so you can build your own catalog/UI without guessing the bounds; keep using GET /v1/pricing for the price.

  21. v1.6.1fix

    Reversal terminology standardised

    The docs now use 'reversal' consistently to match the reversed order status and the reversal_tx field — the section is now 'Reversals & delivery' and adds a 'When a reversal happens' breakdown of the exact cases. No behaviour change: when and how your funds are returned is unchanged.

  22. v1.6.0feature

    Unmatched payments are auto-refunded

    A payment that arrives with no order reference (a missing or unrecognised memo) is now returned to the sender minus the network fee. If it can be attributed unambiguously to one of your pending orders, that order ends failed with failure_reason no_memo / wrong_memo and the refund reference in reversal_tx.

  23. v1.5.0feature

    Rate limits documented; probe cap raised to 30/min

    The overview now documents the per-minute request budget, the RateLimit-* / Retry-After headers, the daily order cap and the per-recipient guard. The tighter pricing & recipient-check probe cap was raised from 10 to 30 requests/min.

  24. v1.4.0feature

    Pricing response adds quote freshness + GRAM↔USDT rate

    GET /v1/pricing now returns quoted_at and valid_until (a re-quote hint) plus usdt_per_ton (the current public GRAM↔USDT rate; the field name is frozen for wire compatibility).

  25. v1.3.0feature

    Terminal failed and expired order-status webhooks now fire

    If you set a callback_url, you now also receive the terminal failed and expired webhook events — previously only delivered and reversed were delivered.

  26. v1.2.0breaking

    Pricing response returns amount + currency only

    GET /v1/pricing now returns just the final amount and currency. The previous breakdown object has been removed — amount is already the full, all-in total to pay, so no change is needed unless you read breakdown fields.

  27. v1.1.0feature

    Pay in USDT (TON), plus a price breakdown

    Orders and quotes now accept payment_currency: usdt_ton alongside ton (GRAM). The pricing response gained a breakdown object (Fragment cost, markup, gas, and DEX fee + swap gas for USDT).

  28. v1.0.0breaking

    recipient is now an object, not a bare string

    Create-order and recipient-check requests take recipient: { username } instead of a top-level username string. Update your request bodies before this version — the old shape is rejected with 400 bad_request.