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
What is this?It is a free API (plus a Python SDK) for buying Telegram Stars or Telegram Premium on behalf of a Telegram username, paid with GRAM or USDT on the TON blockchain, with no API key required.
Is this a hosted API I call, or do I have to run a server myself?It is a hosted REST API with a production endpoint; you call it directly or through the provided Python SDK, with extra examples for Node.js and curl. You don't need to host anything yourself.
How do I get started making a purchase?Pick an example from the examples/ directory (Stars or Premium, paid with GRAM or USDT), plug in your TON wallet seed, and run it with the Python SDK, Node.js, or curl.
What do I need before I can send a purchase?A TON wallet seed (24-word mnemonic or Base64 32-byte private key, or a 12-word seed plus an address or account index) and either GRAM or USDT on TON to pay with; no Fragment API key is needed.
Does the availability check guarantee my purchase will succeed?No, it's only a point-in-time validation done right before payment, not a reservation or a delivery guarantee, and the recipient's status can still change afterward.
How should I handle my wallet seed with this API?Credentials must be sent only from your backend and never placed in frontend code or posted publicly, including in GitHub issues.
What exactly can I buy through Fragment API?Telegram Stars in amounts from 50 to 1,000,000, or Telegram Premium subscriptions for 3, 6, or 12 months, both payable with GRAM or USDT on TON.
How do I avoid double-charging a customer on retries?Use one idempotency key per logical order and retry with that same key; never automatically replace an order that is stuck in a reconciliation-required state.
Can I use this with Claude or Codex as a coding agent?Yes, there's an installable AI skill (skills/fragment-api-integration) that teaches a coding agent the full flow: availability checks, SDK/REST calls, wallet selection, idempotency, and error handling.
What if I only have a 12-word wallet seed?A 12-word seed alone isn't enough; you also need to supply the wallet address or a known account index alongside it.
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