💎 Fragment API

Python library for the Fragment.com API — gift Telegram Stars, Premium, and top up TON Ads balance.

Report Bug · Request Feature · Donate TON

---

✨ Features

• 💰 TON Advertisement Topups — Top up Telegram Ads balance (1–1,000,000,000 TON)
• 👑 Telegram Premium Gifts — Gift Premium to any user (3, 6, or 12 months)
• ⭐ Telegram Stars Purchases — Gift Stars to any Telegram user (50–1,000,000 Stars)
• 🔐 Multi-wallet support — V4R2 and V5R1 wallet contract versions
• ⚡ Async-first — Built on httpx and asyncio

---

📦 Installation

pip install pyfragment

Requires Python 3.12+.

---

🚀 Quick Start

import asyncio
from pyfragment import FragmentClient

client = FragmentClient(
    seed="word1 word2 ... word24",
    api_key="YOUR_TONAPI_KEY",
    cookies={
        "stel_ssid": "...",
        "stel_dt": "...",
        "stel_token": "...",
        "stel_ton_token": "...",
    },
)

async def main():
    # Gift 6 months of Telegram Premium
    result = await client.gift_premium("@username", months=6)
    print(result.transaction_id)

    # Gift 500 Stars
    result = await client.gift_stars("@username", amount=500)
    print(result.transaction_id)

    # Top up 10 TON to Ads balance
    result = await client.topup_ton("@username", amount=10)
    print(result.transaction_id)

asyncio.run(main())

See the examples/ folder for ready-to-run scripts.

---

🔧 Configuration

FragmentClient parameters

Parameter	Type	Required	Default	Description
seed	str	✅	—	24-word TON wallet mnemonic phrase
api_key	str	✅	—	Tonapi key from tonconsole.com
cookies	dict | str	✅	—	Fragment session cookies (dict or JSON string)
wallet_version	str	❌	"V5R1"	Wallet contract version: "V4R2" or "V5R1"

Methods

Usernames can be passed with or without @.

Method	Returns	Description	Limits
gift_premium(username, months, show_sender=True)	PremiumResult	Gift Telegram Premium subscription	months: 3, 6, or 12
gift_stars(username, amount, show_sender=True)	StarsResult	Gift Telegram Stars	amount: 50–1,000,000
topup_ton(username, amount, show_sender=True)	AdsTopupResult	Top up Telegram Ads balance	amount: 1–1,000,000,000
get_wallet()	WalletInfo	Get wallet address, state, balance	—

---

⚙️ Getting Required Credentials

🍪 Fragment.com Cookies

Prerequisites: Log in to fragment.com, connect your TON wallet.

1. Install Cookie Editor
2. Open fragment.com while logged in
3. Click the extension → Export → JSON
4. Extract these four fields:

{
  "stel_ssid": "...",
  "stel_dt": "...",
  "stel_token": "...",
  "stel_ton_token": "..."
}

⚠️ Cookies expire. Refresh them if you start getting FragmentPageError or auth errors.

🔑 Tonapi Key

1. Go to tonconsole.com
2. Register and generate a new API key
3. Pass it as api_key to FragmentClient

🌱 Wallet Seed Phrase

If you don't have a TON wallet, create one in Tonkeeper.
Go to Settings → Backup → copy the 24 words.

⚠️ Never share your seed phrase. Store it offline.

🔐 Wallet Version

Version	Use when
V5R1	Default — Tonkeeper / MyTonWallet (wallets created after 2024)
V4R2	Older Tonkeeper or hardware wallets

---

🗂️ Error Handling

All exceptions inherit from FragmentError — see pyfragment/types/exceptions.py for the full list.

from pyfragment import FragmentClient, UserNotFoundError, ConfigurationError, WalletError

try:
    result = await client.gift_stars("@unknown", amount=100)
except UserNotFoundError:
    print("User not found on Fragment")
except WalletError as e:
    print(f"Wallet issue: {e}")
except ConfigurationError as e:
    print(f"Bad params: {e}")

---

Made with ❤️ by @bohd4nx

Star ⭐ this repo if you found it useful!