Fragment API Python SDK

Async Python library for Fragment.com automation
v12.1.0 — Gift Filters & Attributes | No-KYC Mode | Pydantic V2 | Selectolax Parser | Session Storage | Full Marketplace

Features

• Async-first — Full async/await support with FragmentClient.
• Two Modes — KYC-required mode with cookies + wallet, or No-KYC mode via MarketApp API.
• Pydantic Models — All API responses return strongly-typed Pydantic models.
• Selectolax Parsing — Robust CSS-selector based HTML parsing.
• Session Storage — Persist cookies in files or Redis.
• Purchases — Stars (50–10M), Premium (3/6/12 months), GRAM Ads top-up.
• Batch Operations — Multiple purchases in grouped on-chain transactions or via MarketApp.
• EVM Payments — USDT/USDC on Ethereum, Polygon, and BASE chains.
• Giveaways — Stars and Premium giveaways for channels (up to 24K winners).
• Marketplace — Search/bid on usernames, numbers, and gifts.
• Auctions — Start auctions, set fixed prices, place bids, buy-now.
• Offers — Make offers on unlisted items.
• Gateway — Recharge Telegram Gateway credits.
• NFTs — Transfer gifts, withdraw to wallet.
• Wallet — V4R2 and V5R1 support via tonutils.
• Authentication — Auto-authenticate via TON wallet proof + Telegram OAuth.
• Anonymous Numbers — Login codes, toggle delivery, terminate sessions.

Installation

pip install fragment-api-py

Requirements:

• Python 3.10+
• For KYC mode: Fragment cookies (stel_ssid, stel_dt, stel_token; stel_ton_token for wallet ops) + TON wallet seed phrase (12/18/24 words) + Tonconsole or Toncenter API key
• For No-KYC mode: MarketApp API token + TON wallet seed phrase (12/18/24 words) + Tonconsole or Toncenter API key

Get a free API key at tonconsole.com.

Quick Start

KYC Mode (with Fragment.com cookies)

import asyncio
from FragmentAPI import FragmentClient
from FragmentAPI.types.results import EvmPaymentResult

async def main():
    async with FragmentClient(
        cookies={
            "stel_ssid": "...",
            "stel_token": "...",
            "stel_dt": "...",
            "stel_ton_token": "..."
        },
        seed="word1 word2 ... word24",
        api_key="AF...",
        wallet_version="V5R1",
    ) as client:
        
        # Wallet info
        wallet = await client.get_wallet()
        print(f"Balance: {wallet.gram_balance} GRAM, {wallet.usdt_balance} USDT")
        
        # Purchase Stars
        result = await client.purchase_stars("durov", 100)
        print(f"TX: {result.transaction_id}")
        
        # Batch operations
        batch = await client.batch_purchase([
            {"type": "premium", "username": "durov", "months": 3},
            {"type": "stars", "username": "telegram", "amount": 250},
        ])
        print(f"Batch: {batch.succeeded}/{batch.total} succeeded")

        # EVM payment
        evm = await client.purchase_stars("durov", 50, payment_method="usdc_base")
        if isinstance(evm, EvmPaymentResult):
            inv = evm.invoice
            print(f"Send {inv.invoice_amount} {inv.token_symbol} to {inv.invoice_address}")

asyncio.run(main())

No-KYC Mode (via MarketApp API)

import asyncio
from FragmentAPI import FragmentClient

async def main():
    async with FragmentClient(
        marketapp_token="your_marketapp_token",
        seed="word1 word2 ... word24",
        api_key="AF...",
        wallet_version="V5R1",
    ) as client:
        
        # Purchase Stars without KYC
        result = await client.purchase_stars("durov", 100)
        print(f"Purchase: {result}")
        
        # Purchase Premium without KYC
        result = await client.purchase_premium("durov", 3)
        print(f"Purchase: {result}")
        
        # Run a giveaway without KYC
        result = await client.giveaway_stars(
            channel="@my_channel",
            amount=1000,
            winners=10,
            duration_days=7
        )
        print(f"Giveaway: {result}")

asyncio.run(main())

Session Storage

Persist cookies across restarts:

from FragmentAPI import FragmentClient, FileSessionStorage, RedisSessionStorage

# File-based storage
storage = FileSessionStorage(directory=".fragment_sessions")
client = await FragmentClient.from_storage(
    session_storage=storage,
    session_id="my_session",
    seed="word1 word2 ... word24",
    api_key="AF...",
)

# Redis storage
storage = RedisSessionStorage(redis_url="redis://localhost:6379/0", ttl=3600)
client = await FragmentClient.from_storage(
    session_storage=storage,
    session_id="my_session",
    seed="word1 word2 ... word24",
    api_key="AF...",
)

Authentication

import asyncio
from FragmentAPI import FragmentClient

async def main():
    # Auto-authenticate via TON wallet + Telegram
    cookies = await FragmentClient.authenticate(
        seed="word1 word2 ... word24",
        wallet_version="V5R1",
        phone="+71234567890",  # Omit for QR code flow
    )
    
    async with FragmentClient(
        cookies=cookies,
        seed="word1 word2 ... word24",
        api_key="AF...",
    ) as client:
        profile = await client.get_profile()
        print(f"Logged in as: {profile.name}")

asyncio.run(main())

Payment Methods

API Overview

Purchases & Giveaways

Marketplace

Asset Info & History

Account & Assets

NFTs & Withdrawals

Gateway

Anonymous Numbers

Low-Level

Exceptions

All exceptions inherit from FragmentError:

Operating Modes

KYC Mode (Traditional)

• Requires Fragment.com cookies
• Requires TON wallet with sufficient balance
• Full access to all Fragment.com features
• KYC verification required for some operations

No-KYC Mode (New in v12.0.0)

• Requires MarketApp API token (get at marketapp.io)
• Requires TON wallet with sufficient balance
• Supports purchases, giveaways, and price lookups
• No KYC verification needed
• Limited compared to full Fragment API

Choose the mode by providing either cookies (KYC mode) or marketapp_token (No-KYC mode) when initializing FragmentClient.

Support & License

Issues: GitHub Issues

Support the Project:

UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj

License: MIT — free for commercial and personal use.

GitHub • Documentation • Telegram