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

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

6.5 KiB Raw Blame History