fragment-api-py 3.0.2

Python client for the Fragment API

Fragment API Python

Professional Python library for Fragment.com API with async and sync support. Send Telegram Stars, Premium, and TON with automatic wallet validation.

Features

• ✅ Async & Sync interfaces
• ✅ 3 payment methods (Stars, Premium, TON)
• ✅ Automatic wallet balance validation
• ✅ WalletV4R2 support
• ✅ Comprehensive error handling
• ✅ Type hints & logging

Installation

pip install fragment-api-py

Quick Start

Synchronous

from FragmentAPI import SyncFragmentAPI

api = SyncFragmentAPI(
    cookies="your_cookies",
    hash_value="your_hash",
    wallet_mnemonic="your mnemonic...",
    wallet_api_key="your_api_key"
)

result = api.buy_stars('username', 100)
if result.success:
    print(f"TX: {result.transaction_hash}")
else:
    print(f"Error: {result.error}")

api.close()

Asynchronous

import asyncio
from FragmentAPI import AsyncFragmentAPI

async def main():
    api = AsyncFragmentAPI(
        cookies="your_cookies",
        hash_value="your_hash",
        wallet_mnemonic="your mnemonic...",
        wallet_api_key="your_api_key"
    )
    
    result = await api.buy_stars('username', 100)
    if result.success:
        print(f"TX: {result.transaction_hash}")
    
    await api.close()

asyncio.run(main())

Methods

buy_stars(username, quantity)

Send Telegram Stars to user

• username (str): Target username
• quantity (int): Number of stars (1-999999)

gift_premium(username, months)

Gift Premium subscription (3, 6, or 12 months)

• username (str): Target username
• months (int): Duration in months

topup_ton(username, amount)

Top up Telegram Ads account with TON

• username (str): Target username
• amount (int): Amount of TON (1-999999)

get_wallet_balance()

Get current wallet balance and address

Setup

1. Get Fragment Cookies

1. Open fragment.com in browser
2. Press F12 → Application → Cookies
3. Copy cookies: stel_ssid, stel_token, stel_dt, stel_ton_token
4. Combine: stel_ssid=value; stel_token=value; ...

2. Get Hash Value

From DevTools Network tab → fragment.com/api requests → copy hash parameter

3. Setup TON Wallet

1. Get 24-word seed phrase from TON wallet (Tonkeeper, MyTonWallet, etc)
2. Fund wallet with TON for transactions

4. Get API Key

1. Go to https://tonconsole.com
2. Create project
3. Generate API key from Settings

Exceptions

• AuthenticationError - Invalid cookies/hash
• UserNotFoundError - User doesn't exist
• InvalidAmountError - Invalid quantity/amount
• InsufficientBalanceError - Low wallet balance
• TransactionError - TX execution failed
• NetworkError - Network request failed
• WalletError - Wallet operation failed
• PaymentInitiationError - Fragment API error

Error Handling

from FragmentAPI import InsufficientBalanceError, UserNotFoundError

try:
    result = api.buy_stars('username', 100)
    if not result.success:
        print(f"Error: {result.error}")
except InsufficientBalanceError as e:
    print(f"Low balance: {e}")
except UserNotFoundError as e:
    print(f"User not found: {e}")
finally:
    api.close()

Security

Store credentials in environment variables:

import os

api = SyncFragmentAPI(
    cookies=os.getenv('FRAGMENT_COOKIES'),
    hash_value=os.getenv('FRAGMENT_HASH'),
    wallet_mnemonic=os.getenv('WALLET_MNEMONIC'),
    wallet_api_key=os.getenv('WALLET_API_KEY')
)

Requirements

• Python 3.7+
• requests >= 2.28.0
• aiohttp >= 3.8.0
• tonutils >= 0.3.0
• pytoniq-core >= 0.1.0

Documentation

Full documentation: https://github.com/S1qwy/fragment-api-py

License

MIT License

Support

• GitHub: https://github.com/S1qwy/fragment-api-py
• Issues: https://github.com/S1qwy/fragment-api-py/issues