fragment-api-py 4.0.0

Python client for the Fragment API with Sync and Async support

Fragment API Python

Professional Python library for Fragment.com API. Send Telegram Stars, Premium, TON, and run Giveaways with automatic wallet validation and multi-version support.

Full Documentation: fragment.s1qwy.ru

Features

• ✅ Sync & Async interfaces (Async requires [async] extra)
• ✅ Payments: Stars, Premium, and TON top-up
• ✅ Giveaways: Run Stars and Premium giveaways for channels
• ✅ Marketplace Search: Search for Usernames, Numbers, and Gifts
• ✅ Automatic Hash: No need to manually provide the API hash anymore
• ✅ Wallet Support: V4R2 and V5R1 (W5)
• ✅ Balance Validation: Automatic check before sending transactions
• ✅ Type Safety: Full type hinting and structured results

Installation

# Basic (Sync only)
pip install fragment-api-py

# With Async support
pip install fragment-api-py[async]

Quick Start

Synchronous (Default)

from fragment_api import FragmentClient

client = FragmentClient(
    seed="your 24 words mnemonic phrase...",
    api_key="your_tonapi_key",
    cookies={
        "stel_ssid": "...",
        "stel_dt": "...",
        "stel_token": "...",
        "stel_ton_token": "..."
    }
)

# Get wallet info
wallet = client.get_wallet()
print(f"Address: {wallet.address} | Balance: {wallet.balance} TON")

# Purchase Stars
result = client.purchase_stars("@username", amount=50)
print(f"Success! TX Hash: {result.transaction_id}")

Asynchronous

import asyncio
from fragment_api.async_client import AsyncFragmentClient

async def main():
    async with AsyncFragmentClient(
        seed="mnemonic...",
        api_key="tonapi_key",
        cookies="..." # Can be a JSON string or dict
    ) as client:
        # Run a Premium giveaway
        result = await client.giveaway_premium("@my_channel", winners=5, months=3)
        print(f"Giveaway started! TX: {result.transaction_id}")

asyncio.run(main())

---

Wallet Versions

Version	Alias	Description
V5R1	W5	Latest wallet version (Default)
V4R2	-	Most common standard wallet

client = FragmentClient(..., wallet_version="V4R2")

---

Marketplace Search

Search for available assets on Fragment:

# Search for usernames
usernames = client.search_usernames(query="durov", filter="auction")
for item in usernames.items:
    print(f"Name: {item['name']} | Price: {item['price']} TON")

# Search for anonymous numbers
numbers = client.search_numbers(query="888", sort="price_asc")

# Search for NFT Gifts
gifts = client.search_gifts(collection="artisanbrick")

---

Giveaways

Run official Telegram giveaways via Fragment:

# Stars Giveaway (Winners: 1-5)
client.giveaway_stars(channel="@my_channel", winners=3, amount=500)

# Premium Giveaway
client.giveaway_premium(channel="@my_channel", winners=10, months=6)

---

Methods Reference

Payments & Giveaways

• purchase_stars(username, amount, show_sender=True) — Send Stars to user (50 - 1M).
• purchase_premium(username, months, show_sender=True) — Gift Premium (3, 6, 12 months).
• topup_ton(username, amount, show_sender=True) — Top up Telegram Ads balance.
• giveaway_stars(channel, winners, amount) — Start Stars giveaway.
• giveaway_premium(channel, winners, months) — Start Premium giveaway.

Search

• search_usernames(query, sort, filter, offset_id)
• search_numbers(query, sort, filter, offset_id)
• search_gifts(query, collection, sort, filter, view, attr, offset)

Wallet & System

• get_wallet() — Returns WalletInfo (address, state, balance).
• call(method, data, page_url) — Make raw/custom API calls.

---

Setup Requirements

1. Fragment Cookies

You need the following cookies from an authenticated fragment.com session:

• stel_ssid, stel_dt, stel_token, stel_ton_token.

2. TON API Key

The library uses TonAPI. You can get a free key at tonconsole.com.

---

Error Handling

The library uses a descriptive exception hierarchy:

from fragment_api.exceptions import (
    WalletError, 
    UserNotFoundError, 
    ConfigError,
    TransactionError
)

try:
    client.purchase_stars("@unknown_user", 50)
except UserNotFoundError:
    print("User not found!")
except WalletError as e:
    print(f"Balance too low or wallet error: {e}")
except TransactionError as e:
    print(f"Blockchain error: {e}")

---

Requirements

• Python 3.10+ (Uses modern union types)
• httpx >= 0.23.0
• tonutils >= 0.3.0
• pytoniq-core >= 0.1.37

Changelog

v4.0.0

• Breaking Change: Renamed SyncFragmentAPI -> FragmentClient.
• Breaking Change: Renamed AsyncFragmentAPI -> AsyncFragmentClient.
• New Feature: Added Marketplace Search (Usernames, Numbers, Gifts).
• New Feature: Added Giveaways (Stars & Premium).
• Improvement: Automatic API Hash derivation (no more hash_value in config).
• Improvement: Switched from requests/aiohttp to httpx.
• Improvement: Default wallet version is now V5R1.

License

MIT License

Support

• GitHub: S1qwy/fragment-api-py
• Email: [e-mail]