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 用户名的名义购买 Telegram Stars 或 Telegram Premium，用 TON 区块链上的 GRAM 或 USDT 支付，且无需 API 密钥。
这是我调用的托管 API，还是必须自己运行服务器？它是一个带生产端点的托管 REST API；你可以直接调用，也可以通过提供的 Python SDK 调用，另有 Node.js 和 curl 的额外示例。你不需要自己托管任何东西。
怎么开始进行购买？从 examples/ 目录中选择一个示例（Stars 或 Premium，用 GRAM 或 USDT 支付），填入你的 TON 钱包助记词，然后用 Python SDK、Node.js 或 curl 运行它。
发起购买之前我需要准备什么？需要一个 TON 钱包助记词（24 词助记词或 Base64 的 32 字节私钥，或 12 词助记词加地址或账户索引），以及 TON 上用于支付的 GRAM 或 USDT；不需要 Fragment API 密钥。
可用性检查能保证我的购买一定成功吗？不能，它只是支付前进行的一次即时校验，不是预订，也不保证交付，而且接收方的状态之后仍可能变化。
使用这个 API 时应如何保管我的钱包助记词？凭据必须只从你的后端发送，绝不能放进前端代码或公开发布，包括在 GitHub issues 中。
通过 Fragment API 到底能买什么？数量从 50 到 1,000,000 的 Telegram Stars，或 3、6 或 12 个月的 Telegram Premium 订阅，两者都可用 TON 上的 GRAM 或 USDT 支付。
如何在重试时避免对客户重复扣款？每个逻辑订单使用一个幂等键，并使用同一个键进行重试；绝不要自动替换卡在对账所需状态的订单。
可以把这个和 Claude 或 Codex 这样的编程代理一起用吗？可以，有一个可安装的 AI skill（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