Version 0.1.3 · Registry installation commands use exact versions.

Buy Telegram Stars with Python: safe server integration

A Python backend workflow for username checks, wallet balance, Telegram Stars/Premium gifts and 429 handling without duplicate purchase retries.

Purchase requests transmit your wallet mnemonic and Fragment session/cookie to the API operator.

Start with a public username lookup in Python. It needs no account or wallet credential. Check the publication report before installing the registry version; alternatively build the corresponding source directory.

Load the wallet mnemonic and Fragment session at runtime. Read balance first; balances are decimal strings. The sample enables purchases only with FRAGMENT_ALLOW_PURCHASES=yes and FRAGMENT_PURCHASE_KIND=stars or premium; exactly one selected gift.

Decide on one intended gift: Stars amount 50–1,000,000 or Premium duration 3/6/12. The example shows both API methods for reference, not an instruction to execute both gifts. Each purchase spends real funds.

Catch the typed flood-wait error and surface its wait hint to your job scheduler. Never automatically resubmit the purchase. After a timeout or unconfirmed transaction, reconcile wallet/recipient state before a new intentional submission.

Install

python -m pip install fragment-donor-sdk==0.1.3

Example

"""Server example; opt in and choose exactly one purchase kind explicitly."""

import os

from fragment_donor_sdk import (
    ApiError,
    FloodWaitError,
    FragmentDonorClient,
    WalletCredentials,
)


def main():
    allow_purchase = os.getenv("FRAGMENT_ALLOW_PURCHASES") == "yes"
    purchase_kind = os.getenv("FRAGMENT_PURCHASE_KIND")
    if allow_purchase and purchase_kind not in {"stars", "premium"}:
        raise SystemExit(
            "Set FRAGMENT_PURCHASE_KIND=stars or premium; no purchase sent"
        )
    client = FragmentDonorClient()
    username = os.getenv("FRAGMENT_USERNAME", "durov")
    try:
        user = client.get_user_info(username)
        print("Username:", user.username)
        if not os.getenv("FRAGMENT_MNEMONIC"):
            return
        credentials = WalletCredentials(
            mnemonic=os.environ["FRAGMENT_MNEMONIC"],
            cookie=os.getenv("FRAGMENT_COOKIE"),
            provider_key=os.getenv("TONCONSOLE_API_KEY"),
        )
        balance = client.wallet_balance(credentials=credentials)
        print("TON:", balance.ton, "USDT:", balance.usdt_ton)
        if allow_purchase and purchase_kind == "stars":
            # One intentional call; do not retry if the outcome is unknown.
            client.buy_stars(username, 50, credentials=credentials)
        elif allow_purchase and purchase_kind == "premium":
            client.buy_premium(username, 3, credentials=credentials)
    except FloodWaitError as error:
        print("FLOOD_WAIT seconds:", error.retry_after)
    except ApiError as error:
        print(
            type(error).__name__,
            "status:",
            error.status,
            "purchase outcome unknown:",
            error.purchase_outcome_unknown,
        )


if __name__ == "__main__":
    main()

Continue reading

Telegram Stars API: send Stars to a username · Python SDK for Telegram Stars and Premium · Payment timeout: prevent duplicate Telegram Stars purchases

OpenAPI 3.0 · Postman collection