Telegram Stars & Premium API for Fragment

KYC 0% · NO-KYC 0.25%

Buy Telegram Stars and gift Premium from a Telegram bot, shop, or reseller backend. Use the Python SDK or direct REST with TON and USDT on TON. No API key needed.

Current SDK: v2.1.7 · Endpoint: https://api.fragment-api.space

Python quick start · Direct REST · Build a shop · Русский

Try It Without a Wallet

Read current prices and API fees. These requests need no seed, cookies, or token and do not create a purchase:

curl https://api.fragment-api.space/api/v1/prices
curl https://api.fragment-api.space/api/v1/commission/rates

KYC has 0% API commission permanently; no-KYC has 0.25% API commission. Stars/Premium cost and blockchain fees are separate. Compare modes and payment methods.

Trust boundary: This is an independent service, not an official Telegram or Fragment API. This repository contains the client SDK, documentation, and examples, not the hosted backend. Purchase requests send your wallet seed to the API service for signing; KYC also sends Fragment session data. Base64 is encoding, not encryption. Use a dedicated operating wallet, keep its balance limited, and never put secrets in frontend code or public logs. See SECURITY.md.

Quick Start

Install on your backend:

pip install fragment-stars-api

Start with a read-only Python request:

from fragment_api import FragmentAPIClient

with FragmentAPIClient() as client:
    print(client.get_prices())
    print(client.get_rates())

The next example makes a real purchase. Set FRAGMENT_WALLET_SEED to your supported seed encoded as Base64 using your backend's secret configuration. Use a real recipient username in place of @telegram_user.

import os
from fragment_api import FragmentAPIClient

with FragmentAPIClient() as client:
    accepted = client.buy_stars(
        username="@telegram_user",
        amount=100,
        seed=os.environ["FRAGMENT_WALLET_SEED"],
        payment_method="ton",
        wait=False,
    )
    print(accepted.request_id)  # Persist against your shop order before polling.

This is no-KYC because cookies are omitted. For KYC, add cookies=os.environ["FRAGMENT_COOKIES"]. For Stars paid in USDT on TON, pass payment_method="usdt_ton"; keep TON for gas and any due API commission.

Poll client.get_status(request_id) until a final state. queued and processing are not delivery confirmation. With wait=True (the default), the SDK polls for you. On a timeout or uncertain payment, reconcile the existing request instead of sending another purchase. Python integration and recovery.

Choose Your Integration

The shop examples are starting points, not a substitute for your checkout authentication, payment verification, or order deduplication.

Runnable Examples

KYC/no-KYC and TON/USDT · Node.js · PHP · Go · Minimal shop

KYC vs No-KYC

Omitting payment_method keeps TON for existing clients. No-KYC Stars paid in USDT use USDT for the base price and TON for API commission. Commission accumulates per wallet and is collected when debt reaches 1 TON, not through an extra transfer on every order. The threshold is not an extra fee. Full comparison and collection rules.

Wallet Selection

Supported seed formats include a 24-word TON mnemonic, a supported 32-byte key, and a 12-word BIP39 mnemonic for V5R1. Send the complete supported seed as Base64 from your backend.

• seed only: a 12-word seed defaults to account_index=0; legacy formats keep their wallet selection behavior.
• seed + account_index: select a V5R1 account for a 12-word seed.
• seed + wallet_address: resolve or verify the wallet; use the resolver examples when you do not know its index.
• seed + wallet_address + account_index: verify the pairing before purchase.

Use POST /api/v1/wallet/resolve, never seed-bearing URL parameters. An address-resolution result is not proof that the wallet has enough funds to buy.

API Reference

Base URL: https://api.fragment-api.space — standard HTTPS, port 443.

No issued token, JWT, OAuth, Authorization, or X-API-Key is required for client routes. Full HTTP examples · Website reference.

Legacy endpoints https://api-fragment.duckdns.org and https://fragment-api.ydns.eu:8443 remain compatible. Existing integrations do not need to migrate immediately.

Common Client Mistakes

All error codes and recovery steps.

Help and Releases

Integration help · Contact @makecodev · Show your shop

SDK releases · SDK changelog · Public service updates · AI-readable docs

LIKE IT? STAR IT! A star helps other developers find the project. Integration feedback and real shop examples are welcome.

Contributing and License

Maintained by bbbuilt. See CONTRIBUTING.md and SECURITY.md. Never share seeds, cookies, private keys, or customer data in issues.

The client code and examples use the MIT License. This does not license the hosted backend or represent affiliation with Telegram or Fragment.