fragment-api-dev README

The project's README from github.com/slightbasebo/fragment-api-dev. As one markdown file: README.md.

Telegram Stars API & Telegram Premium API

Free Fragment API for buying Telegram Stars and Premium with GRAM or USDT on TON.

PyPI Python API License

Free · No API key · Python SDK + REST API · GRAM + USDT on TON

Check availability · Quick start · Examples · AI skill · Prices · OpenAPI

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.

Product Supported values Payment
Telegram Stars 50 to 1,000,000 Stars GRAM or USDT on TON
Telegram Premium 3, 6, or 12 months GRAM or USDT on TON

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.

Code Meaning
AVAILABLE Continue to customer payment
RECIPIENT_NOT_FOUND Check the Telegram username
RECIPIENT_INELIGIBLE Do not accept payment for this recipient
PREMIUM_ALREADY_ACTIVE Use another recipient or retry after the subscription ends
PAYMENT_METHOD_UNAVAILABLE Use the payment method shown in action

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

Wallet data What to send
24-word TON mnemonic or Base64 32-byte private key seed
12-word seed and wallet address seed + wallet_address
12-word seed and known account index seed + account_index

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:

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

Resources

Resource Link
All examples examples/README.md
AI integration skill skills/fragment-api-integration
Python SDK fragment-api-dev
REST API specification openapi.yaml
Production endpoint https://api-stars.duckdns.org

Support

Open an issue or contact @tondotdev.

Never post wallet credentials in an issue. Report security concerns through SECURITY.md.

LIKE IT? STAR IT!

fragment-api-dev (slightbasebo/fragment-api-dev)

Searching Database…

167 ·GitHub
Fragment-api-dev
Что это?Это бесплатный API (плюс Python SDK) для покупки Telegram Stars или Telegram Premium для заданного имени пользователя Telegram, с оплатой в GRAM или USDT на блокчейне TON, причём API-ключ не требуется.
Это hosted API, который я вызываю, или придётся самому держать сервер?Это hosted REST API с продакшен-эндпоинтом; вы вызываете его напрямую или через прилагаемый Python SDK, есть дополнительные примеры для Node.js и curl. Хостить что-то самому не нужно.
С чего начать, чтобы сделать покупку?Возьмите пример из каталога examples/ (Stars или Premium, оплата GRAM или USDT), подставьте сид своего кошелька TON и запустите с Python SDK, Node.js или curl.
Что нужно, прежде чем отправить покупку?Сид кошелька TON (мнемоника из 24 слов или приватный ключ Base64 на 32 байта, либо сид из 12 слов плюс адрес или индекс аккаунта) и GRAM или USDT на TON для оплаты; ключ Fragment API не нужен.
Гарантирует ли проверка доступности, что покупка пройдёт?Нет, это лишь проверка на момент времени, выполняемая прямо перед оплатой, а не бронирование и не гарантия доставки, и статус получателя всё ещё может измениться после.
Как обращаться с сидом своего кошелька при работе с этим API?Учётные данные должны отправляться только с вашего бэкенда и никогда не помещаться в код фронтенда или публичные посты, включая GitHub issues.
Что именно можно купить через Fragment API?Telegram Stars в количестве от 50 до 1 000 000 или подписки Telegram Premium на 3, 6 или 12 месяцев — и то и другое оплачивается GRAM или USDT на TON.
Как избежать двойного списания с клиента при повторах?Используйте один ключ идемпотентности на логический заказ и повторяйте с тем же самым ключом; никогда не заменяйте автоматически заказ, зависший в состоянии reconciliation-required.
Можно ли использовать это с Claude или Codex как агентом кодинга?Да, есть устанавливаемый AI-скилл (skills/fragment-api-integration), который обучает агента кодинга всему процессу: проверки доступности, вызовы SDK/REST, выбор кошелька, идемпотентность и обработка ошибок.
А если у меня только сид из 12 слов?Одного сида из 12 слов недостаточно; вместе с ним нужно передать адрес кошелька или известный индекс аккаунта.
What are similar projects?robinhood-lp-bot, sphere-sdk-connect-example, Polymarket-Telegram-Bot, USDT-Payment-Gateway, nuvex, shardeum, UCashier-USDT-Payment, Telethon
Which topics is it in?curl, api-client, telegram-bot, wallet, payments, pypi, openapi, cryptocurrency, web3, blockchain, telegram, sdk
Creator
slightbasebo
Size
0.1 MB
Stars
167
Updated
CommitOct 11Releasev1.4.0Oct 11
Age
1mo
Commits · 90 Days