pyfragment 2026.3.2

Async Python client for the Fragment API. Buy Stars and Premium, top up GRAM (ex TON) and Ads balances, run giveaways, manage anonymous numbers, and search Fragment listings.

pyfragment

Async Python client for the Fragment marketplace API. Buy Stars & Premium, run giveaways, top up GRAM (ex TON) and Ads balances, manage anonymous numbers, and search Fragment listings.

Documentation · Examples · Changelog · Donate GRAM

Disclaimer: This project is not affiliated with Fragment or Telegram.

---

Installation

pip install pyfragment

# Latest dev build
pip install git+https://github.com/bohd4nx/pyfragment.git@dev

---

Quick Start

import asyncio

from pyfragment import FragmentClient
from pyfragment.enums import PaymentMethod


async def main() -> None:
    async with FragmentClient(
        seed="word1 word2 ... word24",
        api_key="YOUR_API_KEY",  # tonconsole.com (tonapi, default) or t.me/toncenter
        cookies={
            "stel_ssid": "...",
            "stel_dt": "...",
            "stel_token": "...",
            "stel_ton_token": "...",
        },
        wallet_version="V5R1",   # or "V4R2", "HighloadV2", "HighloadV3R1"
        api_provider="tonapi",   # or "toncenter"
    ) as client:
        wallet = await client.get_wallet()
        print(f"GRAM: {wallet.gram_balance} | USDT: {wallet.usdt_balance}")

        recipient = "https://t.me/username"  # also: @username, username

        stars = await client.purchase_stars(recipient, amount=500, payment_method=PaymentMethod.USDT_GRAM)
        print(f"Sent {stars.amount} Stars to {stars.username} | tx: {stars.transaction_id}")

        premium = await client.purchase_premium(recipient, months=6, payment_method=PaymentMethod.GRAM)
        print(f"Sent Premium {premium.amount}m to {premium.username} | tx: {premium.transaction_id}")


asyncio.run(main())

---

Configuration

Parameter	Type	Default	Description
seed	str	—	12- or 24-word GRAM (ex TON) wallet mnemonic
api_key	str	—	API key for the chosen provider (see api_provider)
cookies	dict | str	—	Fragment session cookies
wallet_version	str	"V5R1"	"V4R2" or "V5R1" — also accepts WalletVersion literal
api_provider	str	"tonapi"	"tonapi" (tonconsole.com) or "toncenter" (t.me/toncenter)
timeout	float	30.0	HTTP request timeout in seconds

---

Credentials

Fragment cookies

Log in to fragment.com and connect your GRAM (ex TON) wallet.

Automatically (recommended) — reads directly from your browser, no extension needed:

pip install "pyfragment[browser]"

from pyfragment import get_cookies_from_browser

result = get_cookies_from_browser("chrome")  # firefox, edge, brave, ...
# result.cookies  — dict[str, str] ready to pass to FragmentClient
# result.expires  — ISO 8601 expiry of stel_ssid, or None for session cookies

Manually — use Cookie Editor and export: stel_ssid, stel_dt, stel_token, stel_ton_token. Pass as a dict or JSON string.

Refresh cookies when you get authentication errors.

Tonapi key

Generate at tonconsole.com.

Seed phrase

12- or 24-word mnemonic from your GRAM (ex TON) wallet (Tonkeeper → Settings → Backup). Never share it.

---

Logging

pyfragment uses the standard logging module under the pyfragment namespace and is silent by default:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("pyfragment").setLevel(logging.DEBUG)  # for detailed request logs

---

Error Handling

All exceptions inherit from FragmentError:

from pyfragment import (
    ConfigurationError,   # invalid arguments (amount, months, payment_method…)
    UserNotFoundError,    # recipient not found on Fragment
    WalletError,          # insufficient GRAM (ex TON) or USDT balance
    TransactionError,     # broadcast failed, duplicate seqno, invalid payload
    FragmentAPIError,     # Fragment API returned an error response
    FragmentPageError,    # page fetch or hash extraction failed
    AnonymousNumberError, # number not owned, wrong state, login code issues
    CookieError,          # missing or malformed session cookies
    ParseError,           # failed to decode Fragment payload
    VerificationError,    # on-chain verification step failed
    OperationError,       # generic operation-level failure
    UnexpectedError,      # unexpected API response structure
)

---

Made with ❤️ by @bohd4nx · Contributing · Security

Star ⭐ if you found it useful