Version 0.1.3 · Registry installation commands use exact versions.
Python SDK for Telegram Stars and Premium
Install the independent Fragment Donor Python SDK, check usernames, gift Stars/Premium, and handle rate limits safely.
Purchase requests transmit your wallet mnemonic and Fragment session/cookie to the API operator.
Runtime: Python 3.10+. Version 0.1.3 is published; use the exact registry command shown on this page.
The client exposes username lookup, Stars purchase, Premium gift, and wallet balance with native naming for Python. Required request bodies use form-urlencoded. Wallet balances remain decimal strings; unknown response fields are retained.
Configure a request timeout and wallet credentials on your backend. Read retries are opt-in and bounded; purchase calls never retry automatically. Review the package README for the exact constructor and error classes.
Install
python -m pip install fragment-donor-sdk==0.1.3Example
"""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
Handle Telegram Stars API 429, Retry-After, and flood wait · Protect wallet credentials in API integrations · Fragment Donor API and SDK FAQ