fragment-stars-api 2.1.1

Python SDK for Fragment API - Buy Telegram Stars and Premium

Fragment Stars API

Python SDK for purchasing Telegram Stars and Premium via Fragment.com

Buy Telegram Stars and Premium subscriptions programmatically using TON blockchain. Simple API, automatic transaction signing, queue management for Stars.

🇷🇺 Русская версия

• Documentation website: https://api-fragment.duckdns.org
• Production API endpoint: https://fragment-api.ydns.eu:8443
• Example Telegram shop: https://github.com/bbbuilt/tg_stars_premium_shop
• AI integration prompts: Codex / Claude / llms.txt / llms-full.txt

Production Endpoint and Auth

Use this endpoint for direct HTTP calls and SDK clients:

https://fragment-api.ydns.eu:8443

Normal client endpoints do not require issued API tokens, X-API-Key, JWT, OAuth, or Authorization headers. The API identifies and tracks commission debt by the wallet derived from the provided seed. Only internal admin endpoints use X-Admin-Key.

Health check:

curl https://fragment-api.ydns.eu:8443/health

/health returns the current API availability status.

Vibe Coding / AI Agent Setup

If a client integrates this API with Codex, Claude, Cursor, or another AI coding agent, give the agent the ready-made skill file first. This prevents common mistakes like inventing API tokens, putting wallet seeds in frontend code, or retrying a purchase twice.

Codex

1. Add CODEX_SKILL.md to the client's project.
2. If the project uses AGENTS.md, add:

@CODEX_SKILL.md

3. Ask Codex: Integrate Fragment Stars API using the project skill.

Claude

1. Add CLAUDE_SKILL.md to the client's project.
2. Copy its content into CLAUDE.md, or tell Claude to read CLAUDE_SKILL.md before coding.
3. Ask Claude: Integrate Fragment Stars API following CLAUDE_SKILL.md.

Important rules for AI agents:

• Client API calls do not need issued API tokens or X-API-Key.
• Wallet seeds and Fragment cookies must stay backend-only.
• KYC mode is permanently free with 0% API commission.
• Do not blindly retry after a transaction may have been signed or sent.

Features

• ⭐ Buy Telegram Stars — gift stars to any Telegram user
• 💎 Buy Telegram Premium — 3, 6, or 12 month subscriptions
• 🔐 KYC is free forever — KYC mode has 0% API commission; call get_rates() if you want to verify rates before use
• 💵 TON or USDT on TON — pass payment_method="usdt_ton" when you want Fragment to invoice in USDT; default stays ton
• 🧩 Two modes — KYC with your Fragment cookies, or Non-KYC without user cookies
• ⚡ Automatic transactions — just provide seed phrase, SDK handles the rest
• 📊 Queue management — Stars purchases are queued and polled automatically
• 🛡️ Type hints — full typing support for IDE autocompletion

Installation

pip install fragment-stars-api

Quick Start

from fragment_api import FragmentAPIClient

# Initialize with the production API server
client = FragmentAPIClient("https://fragment-api.ydns.eu:8443")

# Buy 50 stars for user
result = client.buy_stars("username", 50, seed="your_seed_base64")

if result.success:
    print(f"✅ Sent {result.amount} stars!")
    print(f"💰 Cost: {result.cost_ton} TON")
else:
    print(f"❌ Error: {result.error}")

Usage Examples

Buy Stars (No KYC)

Uses owner's Fragment account. Higher commission, but no user cookies needed.

from fragment_api import FragmentAPIClient

client = FragmentAPIClient("https://fragment-api.ydns.eu:8443")

result = client.buy_stars(
    username="telegram_user",
    amount=100,
    seed="your_wallet_seed_base64"
)

print(f"Success: {result.success}")
print(f"Transaction ID: {result.transaction_id}")

Payment Method: TON or USDT on TON

All existing integrations keep working because payment_method defaults to ton.

# Default TON payment
result = client.buy_stars("telegram_user", 100, seed="your_wallet_seed_base64")

# USDT on TON payment
result = client.buy_stars(
    username="telegram_user",
    amount=100,
    seed="your_wallet_seed_base64",
    payment_method="usdt_ton",
)

Behavior:

• KYC mode accepts ton or usdt_ton and keeps API commission at 0%.
• Non-KYC Stars accepts ton or usdt_ton; with usdt_ton, the Stars base price is paid in USDT on TON and the API commission is paid in TON.
• Non-KYC Premium currently uses TON.
• Use GET /api/v1/prices to display both TON and USDT-on-TON rates before purchase.

Buy Stars (With KYC)

Uses user's Fragment cookies. KYC mode has 0% API commission permanently.

result = client.buy_stars(
    username="telegram_user",
    amount=100,
    seed="wallet_seed_base64",
    cookies="user_fragment_cookies_base64"
)

Buy Premium

Premium purchases are processed immediately by the API and return the final result directly.

# 3 months
result = client.buy_premium("username", 3, seed="...")

# 6 months
result = client.buy_premium("username", 6, seed="...")

# 12 months
result = client.buy_premium("username", 12, seed="...")

Check Commission Rates

KYC mode is free forever, but you can call the API before using it if you want to verify the currently configured rates.

rates = client.get_rates()

print(f"No KYC rate: {rates.rate_no_kyc}%")
print(f"With KYC rate: {rates.rate_with_kyc}%")

Check Queue Status

status = client.get_queue_status()

print(f"Queue length: {status['queue_length']}")
print(f"Estimated wait: {status['estimated_wait_seconds']}s")

Check Premium Eligibility

result = client.check_premium_eligibility("username")

if result['eligible']:
    print("✅ User can purchase Premium")
else:
    print(f"❌ Not eligible: {result.get('reason', 'Unknown reason')}")

Async Mode (Don't Wait)

# Returns immediately with request_id
response = client.buy_stars("user", 50, seed="...", wait=False)
print(f"Request ID: {response.request_id}")
print(f"Position in queue: {response.position}")

# Check status later
status = client.get_status(response.request_id)
print(f"Status: {status.status}")

API Reference

FragmentAPIClient

FragmentAPIClient(
    base_url: str,              # Required - your API server URL
    timeout: float = 30.0,
    poll_timeout: float = 300.0
)

Methods

Method	Description
buy_stars(username, amount, seed, cookies?, local_storage?, payment_method?, wait?)	Buy Telegram Stars through the queue
buy_premium(username, duration, seed, cookies?, local_storage?, payment_method?, wait?)	Buy Telegram Premium directly
get_prices()	Get current TON and USDT-on-TON prices
get_rates()	Get commission rates
get_queue_status()	Get queue status and statistics
check_premium_eligibility(username)	Check if user is eligible for Premium
get_status(request_id)	Get request status

Exceptions

from fragment_api import FragmentAPIError, QueueTimeoutError

try:
    result = client.buy_stars("user", 50, seed="...")
except QueueTimeoutError:
    print("Request timed out")
except FragmentAPIError as e:
    print(f"Error [{e.error_code}]: {e.message}")

How It Works

1. For Stars, you call buy_stars() and the API adds the request to the queue
2. The SDK polls GET /api/v1/queue/:request_id until the Stars purchase is completed or failed
3. For Premium, you call buy_premium() and the API returns the final purchase result directly
4. Server opens Fragment.com in headless browser
5. Server signs TON transaction with your seed phrase
6. Stars/Premium delivered to recipient's Telegram

Requirements

• Python 3.9+
• TON wallet with sufficient balance for gas and TON purchases
• For payment_method="usdt_ton": USDT on TON balance, plus a small TON balance for gas and API commission
• Wallet seed phrase (24 words, base64 encoded)

How to encode seed phrase

echo -n "word1 word2 word3 ... word24" | base64

How to get Fragment cookies (for KYC mode)

KYC mode requires your Fragment.com cookies and has 0% API commission permanently.

📖 See detailed Cookie Guide for step-by-step instructions with screenshots and troubleshooting.

Quick Guide

Required cookies:

• stel_token - Session authentication token
• stel_ssid - Session ID
• stel_ton_token - TON wallet connection token (CRITICAL - required for purchases)
• stel_dt - Timezone offset

Steps:

1. Login to Fragment: Go to https://fragment.com and login via Telegram
2. Connect TON Wallet: Click "Connect Wallet" and connect Tonkeeper/MyTonWallet
3. Open DevTools: Press F12 → Application → Cookies → https://fragment.com
4. Copy cookie values: Copy the Value field for each required cookie
5. Create JSON:

   {
       "stel_token": "your_value",
       "stel_ssid": "your_value",
       "stel_ton_token": "your_value",
       "stel_dt": "-180"
   }
   

6. Encode to base64:

   cat cookies.json | base64 -w 0
   

7. Use in code:

   result = client.buy_stars(
       username="user",
       amount=50,
       seed="your_seed_base64",
       cookies="your_cookies_base64"
   )
   

⚠️ Important: The stel_ton_token cookie is required for purchases. Make sure your TON wallet is connected on fragment.com before extracting cookies!

💡 Tip: KYC mode is free forever when you provide Fragment cookies. If you don't want to deal with cookies, use No-KYC mode (just omit the cookies parameter); it has a commission but no cookies are needed.

Author

Basebay — Backend developer focused on automation, bots, and infrastructure tools.

• Telegram: @makecodev
• GitHub: bbbuilt

Support

• GitHub Issues: fragment-stars-api/issues
• Telegram: @makecodev

License

MIT License - see LICENSE file.