fragment-api-dev

The focused Python SDK for buying Telegram Stars and Telegram Premium through Fragment.

• GRAM and USDT on TON
• No API key
• Automatic status polling
• Zero runtime dependencies
• Pre-payment recipient checks without wallet credentials

Install

pip install fragment-api-dev

Quick start

This example uses a 12-word wallet at account index 0. If you use a 24-word TON mnemonic or a Base64 32-byte private key, remove account_index.

import os

from fragment_api import FragmentAPI


api = FragmentAPI()

check = api.check_stars_availability("@telegram_user", 50, "gram")
if not check.available:
    raise SystemExit(f"{check.message} {check.action or ''}")

# Accept customer payment only after the check succeeds.
purchase = api.buy_stars(
    username="@telegram_user",
    amount=50,
    payment_method="gram",
    seed=os.environ["TON_WALLET_SEED"],
    account_index=0,  # Required for a 12-word seed
)

result = api.wait(purchase.purchase_id)

if result.completed:
    print("Delivered:", result.transaction_hash)
else:
    print("Not completed:", result.status, result.error)

The SDK checks the recipient, generates an idempotency key, submits the purchase, and provides a typed Purchase result.

Use check_premium_availability("@telegram_user", 3, "usdt") for Premium. These checks never need or accept a seed, wallet address, account index, or API key.

Run the check shortly before payment. It is not a reservation or guarantee. If the API returns 429, wait for error.retry_after; on 503, retry later and do not charge yet.

12-word wallets

A 12-word wallet can contain many TON accounts. Tell the API which account pays:

A 12-word seed alone is not enough. Send wallet_address or account_index.

wallet = api.resolve_wallet(
    seed=os.environ["TON_WALLET_SEED"],
    wallet_address=os.environ["TON_WALLET_ADDRESS"],
)

purchase = api.buy_stars(
    username="@telegram_user",
    amount=50,
    payment_method="gram",
    seed=os.environ["TON_WALLET_SEED"],
    account_index=wallet.account_index,
)

If you already know the index, skip resolve_wallet() and pass account_index=0 (or your actual index). You may also pass wallet_address="UQ..." directly. The API searches indices 0..20 during a purchase and 0..100 through resolve_wallet().

For a 24-word TON mnemonic or Base64 32-byte private key, omit both wallet selectors.

Wallet selection errors

FragmentAPIError exposes code and action so your app can show the correct next step.

Prices

Get the 50-Stars reference price and Premium prices for 3, 6, and 12 months before showing a price to your customer:

catalog = api.get_prices()
print(catalog.stars.amount, catalog.stars.prices.gram, catalog.stars.prices.usdt)

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

Use get_premium_price(3), get_premium_price(6), or get_premium_price(12) for Premium. Price values are strings to preserve their exact decimal value. A quote can have stale=True when the latest available quote is being served.

Telegram Premium

purchase = api.buy_premium(
    username="@telegram_user",
    months=3,
    payment_method="usdt",
    seed=os.environ["TON_WALLET_SEED"],
    account_index=0,  # Required for a 12-word seed
)

result = api.wait(purchase.purchase_id)

Premium durations are 3, 6, or 12 months.

Payments

USDT purchases require a small GRAM balance for the network fee.

Public API

No authentication token or API key is required.

Links

• GitHub repository
• REST and Node.js examples
• OpenAPI specification
• API status
• Integration support