afragment

Async Python library for the Fragment.com API. Purchase Telegram Stars, Premium subscriptions, and TON balance topups programmatically.

Installation

pip install afragment

Authentication

You need two credentials from Fragment.com:

• FRAGMENT_HASH - Session hash (from URL parameter)
• FRAGMENT_COOKIE - Session cookie (from browser)

How to get credentials

1. Go to Fragment.com and log in
2. Complete KYC verification if you haven't already
3. Open Developer Tools (F12 or Right-click → Inspect)
4. Go to the Network tab
5. Select Fetch/XHR filter
6. Perform any action on the site (e.g., search for a username)
7. Click on any API request and find the credentials as shown below:

• FRAGMENT_HASH: Found in the request URL as ?hash=... parameter
• FRAGMENT_COOKIE: Found in the Request Headers under Cookie

Quick Start

One call = ready transaction! Just pass username, value, and wallet address.

🌟 Buy Telegram Stars

import asyncio
from afragment import AsyncFragmentClient, nano_to_ton

async def main():
    async with AsyncFragmentClient(
        fragment_hash="your_hash",
        fragment_cookie="your_cookie"
    ) as client:
        # Pay with TON (default)
        result = await client.buy_stars("username", 100, "your_wallet_address")
        
        # Or pay with USDT
        result = await client.buy_stars("username", 100, "your_wallet_address", payment_method="usdt")
        
        # Get transaction details
        tx = result["transaction"]["messages"][0]
        print(f"Recipient: {result['recipient']['name']}")
        print(f"Price: {result['amount']} TON")
        print(f"Send to: {tx['address']}")
        print(f"Amount: {nano_to_ton(int(tx['amount']))} TON")

asyncio.run(main())

⭐ Gift Telegram Premium

async def gift_premium():
    async with AsyncFragmentClient(
        fragment_hash="your_hash",
        fragment_cookie="your_cookie"
    ) as client:
        # Gift 12 months of Premium
        result = await client.buy_premium("username", 12, "your_wallet_address")
        
        tx = result["transaction"]["messages"][0]
        print(f"Send to: {tx['address']}")
        print(f"Amount: {tx['amount']} nanoTON")

💎 TON Balance Topup

async def topup_ton():
    async with AsyncFragmentClient(
        fragment_hash="your_hash",
        fragment_cookie="your_cookie"
    ) as client:
        # Topup 10 TON
        result = await client.buy_ton_topup("username", 10, "your_wallet_address")
        
        tx = result["transaction"]["messages"][0]
        print(f"Send to: {tx['address']}")
        print(f"Amount: {tx['amount']} nanoTON")

API Reference

Main Methods

Method	Parameters	Description
buy_stars(username, quantity, wallet_address, payment_method="ton")	quantity >= 50	Purchase Telegram Stars
buy_premium(username, months, wallet_address, payment_method="ton")	months: 3, 6, or 12	Gift Telegram Premium
buy_ton_topup(username, amount, wallet_address, payment_method="ton")	amount >= 1 (whole number)	TON balance topup

Payment Methods

All purchase methods accept payment_method parameter:

• "ton" — pay with TON (default)
• "usdt" — pay with USDT

Return Value

All methods return a dictionary:

{
    "recipient": {
        "name": "User Name",
        "photo": "photo_url"
    },
    "amount": "2.5",  # Price in TON
    "transaction": {
        "messages": [{
            "address": "EQ...",      # Where to send TON
            "amount": "2500000000",  # Amount in nanoTON
            "payload": "base64..."   # Transaction payload
        }]
    }
}

Utility Functions

Payload Decoding

from afragment import decode_payload, extract_ref_id, extract_transaction_text

payload = result["transaction"]["messages"][0]["payload"]

# Extract reference ID
ref_id = extract_ref_id(payload)

# Extract human-readable comment
comment = extract_transaction_text(payload, "stars", quantity=100)
# Output: "100 Telegram Stars\n\nRef#abc123"

Amount Conversion

from afragment import nano_to_ton, ton_to_nano

ton = nano_to_ton(1500000000)  # 1.5 TON
nano = ton_to_nano(1.5)        # 1500000000 nanoTON

Error Handling

from afragment import (
    AsyncFragmentClient,
    FragmentAPIError,
    AuthenticationError,
    PriceChangedError,
    InvalidRecipientError,
)

async def safe_purchase():
    async with AsyncFragmentClient(
        fragment_hash="your_hash",
        fragment_cookie="your_cookie"
    ) as client:
        try:
            result = await client.buy_stars("username", 100, "wallet_address")
        except InvalidRecipientError:
            print("User not found!")
        except PriceChangedError:
            print("Price changed, try again")
        except AuthenticationError:
            print("Session expired, refresh credentials")
        except ValueError as e:
            print(f"Validation error: {e}")

Exceptions

Exception	Description
FragmentAPIError	Base exception for all API errors
AuthenticationError	Invalid or expired credentials
PriceChangedError	Price changed during request (retry recommended)
InvalidRecipientError	User not found or not eligible
ValueError	Invalid input (validation failed)

Validation Rules

Method	Parameter	Validation
buy_stars	quantity	Minimum 50
buy_premium	months	Must be 3, 6, or 12
buy_ton_topup	amount	Minimum 1, whole numbers only

Contact

• Telegram: @thebraina1r

Donate

If you find this library useful, you can support the development:

• TON Wallet: thebrainair.ton