Public API reference

Fragment API is a backend API for buying Telegram Stars and gifting Telegram Premium through Fragment. Telegram bots, shops, marketplaces, and services can integrate it through the Python SDK or REST API, pay with GRAM or USDT on TON, and track delivery with one purchase ID.

The API turns Fragment's purchase flow into a small server-to-server interface: create a purchase, store the returned ID, poll the status, and finish only after a terminal result. No API key is required, and the public API does not add an API access fee.

The Telegram Stars API is designed for services that already manage an order and need a reliable backend purchase step. It fits Telegram bots, digital-goods shops, reseller panels, marketplaces, support tools, and automated Premium gifting systems.

Choose the Python SDK for the shortest typed integration. Choose direct REST when your backend uses Node.js, PHP, Go, Java, another language, or requires complete control over HTTP requests and persistence.

Check whether a Telegram recipient can receive the selected Stars or Premium purchase before you accept payment from your customer. This request does not create an invoice and does not need wallet credentials.

Availability is a point-in-time check, not a reservation or delivery guarantee. Check again whenever the product, username, amount, or payment method changes.

from fragment_api import FragmentAPI

api = FragmentAPI()
check = api.check_stars_availability(
    '@telegram_user', 50, 'gram',
)
print(check.available, check.message, check.action)

Availability results

Python SDK 1.4.0 — use check_stars_availability() or check_premium_availability().

Price endpoints need no API key, username, wallet seed, or payment method. Prices are informational and not reserved; Fragment creates a fresh invoice when a purchase starts.

from fragment_api import FragmentAPI

api = FragmentAPI()
quote = api.get_stars_price(100)
print(quote.prices.gram, quote.prices.usdt, quote.stale)

Python SDK 1.4.0 — use get_prices(), get_stars_price(amount), or get_premium_price(months).

Resolve the exact account before creating a purchase. This is required when a 12-word seed can derive more than one wallet.

from fragment_api import FragmentAPI

# pip install fragment-api-dev==1.4.0
# POST https://api-stars.duckdns.org/api/v1/wallets/resolve
# A 12-word seed alone is invalid; resolution requires wallet_address or account_index (0..100).
api = FragmentAPI()
wallet = api.resolve_wallet(
    seed='<12_WORD_BIP39_SEED>',
    wallet_address='<TON_WALLET_ADDRESS>',
)
print(wallet.account_index, wallet.wallet_version)

Python SDK 1.4.0 — use resolve_wallet() before a Stars or Premium purchase.

Wallet recovery

The same endpoint handles Stars and Premium. The product decides how amount is interpreted.

Accepted response

{
  "purchase_id": "9ea17a5e-...",
  "status": "queued",
  "status_url": "/api/v1/purchases/9ea17a5e-..."
}

Poll using the returned ID. Use a measured interval, keep the same purchase record, and persist the final result.

curl 'https://api-stars.duckdns.org/api/v1/purchases/<PURCHASE_ID>' \
  -H 'Accept: application/json'

Completed response

{
  "purchase_id": "9ea17a5e-...",
  "status": "completed",
  "transaction_hash": "<TRANSACTION_HASH>"
}

Generate the idempotency key in your order system before calling the API. Reuse it when retrying the same order; create a new one only for a genuinely new order.

Log purchase_id, idempotency_key, HTTP status, error code, and response details. Never log the wallet secret.

The public GitHub repository includes a portable Fragment API integration skill for Codex and Claude. It gives a coding agent the current request fields, wallet rules, examples, status handling, idempotency requirements, and safe retry behavior.

# Codex
cp -R skills/fragment-api-integration "${CODEX_HOME:-$HOME/.codex}/skills/"

# Claude
cp -R skills/fragment-api-integration "$HOME/.claude/skills/"

Then ask your coding agent: Use $fragment-api-integration to add Telegram Stars purchases to this project.

• Use HTTPS and set strict request timeouts.
• Persist purchase IDs before acknowledging the customer order.
• Rotate credentials if a secret appears in logs or source control.

Create a checkout with a public payer address. Your wallet signs the returned transaction; this flow accepts no seed.

Send product, username, amount, payment_method, payer_address, and idempotency_key to create. Persist checkout_id, approve only a payable transaction before validUntil, then submit the signed boc. Only completed confirms delivery.

Read the full signing and recovery guide. The Python SDK provides create_checkout, get_checkout, submit_checkout, and wait_checkout on both sync and async clients.

Use the public repository as the source for runnable examples, the REST specification, Python SDK installation, wallet resolver guidance, and integration support. The production API endpoint remains separate from the documentation and source repository.