๐ Fragment API
Python library for the Fragment.com API โ gift Telegram Stars, Premium, and top up TON Ads balance.
[](https://pypi.org/project/pyfragment/)
[](https://pypi.org/project/pyfragment/)
[](https://python.org)
[](LICENSE)
[](https://github.com/bohd4nx/pyfragment/stargazers)
[](https://github.com/bohd4nx/pyfragment/actions)
[Report Bug](https://github.com/bohd4nx/pyfragment/issues) ยท [Request Feature](https://github.com/bohd4nx/pyfragment/issues) ยท [**Donate TON**](https://app.tonkeeper.com/transfer/UQCppfw5DxWgdVHf3zkmZS8k1mt9oAUYxQLwq2fz3nhO8No5)
---
## โจ 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
```bash
pip install pyfragment
```
Requires **Python 3.12+**.
---
## ๐ Quick Start
```python
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/`](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](https://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](https://fragment.com), connect your TON wallet.
1. Install [Cookie Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)
2. Open [fragment.com](https://fragment.com) while logged in
3. Click the extension โ **Export** โ **JSON**
4. Extract these four fields:
```json
{
"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](https://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](https://tonkeeper.com).
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`](pyfragment/types/exceptions.py) for the full list.
```python
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](https://t.me/bohd4nx)
**Star โญ this repo if you found it useful!**