slightbasebo/fragment-api-dev: telegram Stars API & Telegram Premium API

Fragment API gives shops, Telegram bots, and backend services a simple way to buy Telegram Stars or Telegram Premium for any supported Telegram username. Use the Python SDK or call the REST API directly.

API access is free. You pay only the Fragment purchase amount and TON network fees.

Check before charging

Check whether the recipient can receive the purchase before accepting customer payment. The check needs no seed, wallet address, or API key.

from fragment_api import FragmentAPI

api = FragmentAPI()
check = api.check_stars_availability("@telegram_user", 100, "gram")

if not check.available:
    print(check.message, check.action)
    # Do not accept payment.

Run the check shortly before payment. It is a point-in-time validation, not a reservation or delivery guarantee. On 429, wait for retry_after; on 503, retry later and do not accept payment yet.

Quick start

pip install fragment-api-dev==1.3.0

import os
from fragment_api import FragmentAPI

api = FragmentAPI()

purchase = api.buy_stars(
    username="@telegram_user",
    amount=50,
    payment_method="gram",
    seed=os.environ["TON_WALLET_SEED"],
)

result = api.wait(purchase.purchase_id)
print(result.status, result.transaction_hash or result.error)

This minimal example uses a 24-word TON mnemonic or a Base64 32-byte private key. Credentials are sent only by your backend; never place a seed in frontend code.

Choose your wallet setup

A 12-word seed alone is not enough. If you know the address but not its index, use the wallet resolver example.

Ready-to-run examples

The examples/ directory contains explained examples for:

• Stars with GRAM
• Stars with USDT on TON
• Premium with GRAM
• Premium with USDT on TON
• 24-word wallets without a selector
• 12-word wallets with an address or account index
• Python SDK, Node.js, and curl
• Recipient availability checks before customer payment

USDT purchases require a small GRAM balance for TON network fees.

AI-assisted integration

Install the same portable skill for Codex or Claude:

# Codex
cp -R skills/fragment-api-integration "${CODEX_HOME:-$HOME/.codex}/skills/"

# Claude
cp -R skills/fragment-api-integration "$HOME/.claude/skills/"

Then ask your coding agent:

Use $fragment-api-integration to add Telegram Stars purchases to this project.

The skill covers pre-payment availability checks, Python SDK and REST integrations, Stars and Premium, GRAM and USDT, wallet selection, idempotency, polling, and safe error handling.

Prices

Get an informational quote without creating a purchase:

quote = api.get_stars_price(100)
print(quote.prices.gram, quote.prices.usdt)

curl 'https://api-stars.duckdns.org/api/v1/prices/quote?product=stars&amount=100'

Price values are exact decimal strings. Fragment creates a fresh quote when the purchase starts.

Important

• Use one idempotency_key for each logical order.
• Retry the same order with the same key.
• Wait for the final status; creating a purchase does not mean it is complete.
• Never automatically replace an order in reconciliation_required.

Resources