pyfragment/README.md

Fragment API

Async Python client for the Fragment.com API — buy Telegram Stars and Premium, run giveaways, top up TON, Ads balance, manage anonymous numbers, and search the marketplace for usernames, numbers, and gifts.

Report Bug · Request Feature · Donate TON

Disclaimer: This project is not affiliated with, endorsed by, or in any way officially connected with Fragment or Telegram.

---

Installation

pip install pyfragment

To install the latest unreleased changes from the dev branch:

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

Requires Python 3.12+.

---

Configuration

Parameter	Type	Default	Description
seed	str	—	24-word TON wallet mnemonic
api_key	str	—	Tonapi key from tonconsole.com
cookies	dict | str	—	Fragment session cookies
wallet_version	str	"V5R1"	"V4R2" or "V5R1"
timeout	float	30.0	HTTP request timeout in seconds

---

Credentials

Fragment cookies — log in to fragment.com, install Cookie Editor, and export these four keys: stel_ssid, stel_dt, stel_token, stel_ton_token. Pass them as a dict or as a JSON string. Refresh when you get authentication errors.

Tonapi key — generate at tonconsole.com.

Seed phrase — 24-word mnemonic from your TON wallet (Tonkeeper → Settings → Backup). Never share it.

---

Usage

import asyncio
from pyfragment import (
    FragmentClient,
    FragmentError,       # base — catches everything below
    UserNotFoundError,   # username doesn't exist on Fragment
    WalletError,         # insufficient balance or misconfiguration
    CookieError,         # cookies are missing or expired
    TransactionError,    # on-chain broadcast failed
    ConfigurationError,  # invalid argument (months, amount, etc.)
    FragmentAPIError,    # unexpected Fragment API response
)


async def main() -> None:
    async with FragmentClient(
        seed="word1 word2 ... word24",  # 24-word TON wallet mnemonic
        api_key="YOUR_TONAPI_KEY",       # from tonconsole.com
        cookies={
            "stel_ssid": "...",
            "stel_dt": "...",
            "stel_token": "...",
            "stel_ton_token": "...",
        },
    ) as client:
        try:
            # Purchase 6 months of Telegram Premium
            result = await client.purchase_premium("@username", months=6)
            print(f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}")

            # Purchase 500 Stars
            result = await client.purchase_stars("@username", amount=500)
            print(f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}")

            # Top up 10 TON to Telegram balance
            # wallet must hold at least amount + ~0.056 TON for gas
            result = await client.topup_ton("@username", amount=10)
            print(f"{result.amount} TON successfully sent to {result.username} | tx: {result.transaction_id}")

        except UserNotFoundError:
            print(f"User was not found on fragment.com — check the username and try again.")
        except WalletError as e:
            print(f"Wallet error — insufficient balance or misconfiguration: {e}")
        except CookieError:
            print("Authentication failed — session cookies are missing or expired. Refresh them and retry.")
        except TransactionError as e:
            print(f"Transaction failed to broadcast on-chain: {e}")
        except ConfigurationError as e:
            print(f"Invalid argument: {e}")
        except FragmentAPIError as e:
            print(f"Unexpected response from Fragment API: {e}")
        except FragmentError as e:
            # catch-all for any other pyfragment error
            print(f"Unexpected error: {e}")


asyncio.run(main())

---

Made with ❤️ by @bohd4nx

Star ⭐ this repo if you found it useful!