The #1 Fragment API Provider

Telegram Stars API Provider · Documentation

REST API for buying Telegram Stars and Premium via Fragment. Pay from your merchant balance in TON or USDT TON. REST API для покупки Telegram Stars и Premium через Fragment. Оплата с баланса мерчанта в TON или USDT TON.

AuthenticationАвторизация

Every protected request requires a merchant API key in the request headers.Каждый защищённый запрос требует API-ключ мерчанта в заголовках.

Primary — header X-API-Key

X-API-Key: YOUR_API_KEY

Legacy — Bearer token

Authorization: Bearer YOUR_API_KEY

How to get a keyКак получить ключ

1. Open @fapiproviderbotОткройте @fapiproviderbot
2. Send /startОтправьте /start
3. Tap API key — you'll see the prefix (abc12345...)Нажмите API key — показывается prefix (abc12345...)
4. Full key is shown once at registration or rotationПолный ключ показывается один раз при регистрации или перевыпуске

Deposits — TON & USDT TONДепозиты — TON & USDT TON

Top up your unique deposit_address on TON mainnet. Minimum deposit: 5 TON or 5 USDT. Deposit fee: 0.5%.Пополните уникальный deposit_address мерчанта в сети TON mainnet. Минимальный депозит: 5 TON или 5 USDT. Комиссия депозита: 0.5%.

USDT jetton contract (only accepted)USDT jetton контракт (только он принимается)

EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Wallet verification suffix: …Id_sDs. Other jettons are not credited.Суффикс для проверки в кошельке: …Id_sDs. Другие jetton не зачисляются.

payment_method for purchasespayment_method при покупке

Error codesКоды ошибок

Errors are returned as JSON: {"detail": "message"}Ошибки возвращаются как JSON: {"detail": "message"}

Order statusesСтатусы заказа

pending → processing → paying → completed | failed

On failed, funds are automatically refunded to merchant balance.При failed средства автоматически возвращаются на баланс мерчанта.

Integration guideРуководство по интеграции

1. Get API key from Telegram botПолучите API key в Telegram-боте
2. GET /api/balance — saveсохраните deposit_address
3. Top up TON or USDT (contract …Id_sDs)Пополните TON или USDT (контракт …Id_sDs)
4. POST /api/search — verify recipientпроверьте получателя
5. GET /api/prices — get live quoteполучите live quote
6. POST /api/purchase withс idempotency_key
7. PollPoll GET /api/purchase/transaction/{id} untilдо completed

Endpoints

{
  "ton_balance": 1.25,
  "usdt_balance": 9.14,
  "deposit_address": "UQDVv_pPqr8U...",
  "usdt_jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "usdt_jetton_master_suffix": "Id_sDs",
  "mainnet_balance": 1.25,
  "testnet_balance": 0.0
}

{ "detail": "Invalid API key" }

curl "https://api.fragment-api.io/api/balance" \
  -H "X-API-Key: YOUR_API_KEY"

const balance = await fetch("https://api.fragment-api.io/api/balance", {
  headers: { "X-API-Key": process.env.FRAGMENT_API_KEY }
}).then(r => r.json());

import requests

balance = requests.get(
    "https://api.fragment-api.io/api/balance",
    headers={"X-API-Key": "YOUR_API_KEY"},
).json()

{
  "product_type": "stars",
  "item_name": "50 Telegram Stars",
  "price": 0.7875,
  "gas_fee": 0.07,
  "total": 0.8575,
  "currency": "USDT",
  "payment_method": "usdt_ton"
}

{ "detail": "quantity must be one of premium months: 3, 6, 12" }

curl "https://api.fragment-api.io/api/prices?product_type=stars&quantity=50&recipient=durov&payment_method=usdt_ton" \
  -H "X-API-Key: YOUR_API_KEY"

[ { "product_type": "stars", "item_name": "50 Telegram Stars", "total": 0.575, "...": "..." } ]

curl "https://api.fragment-api.io/api/prices/list" -H "X-API-Key: YOUR_API_KEY"

{ "ok": true, "found": { "recipient": "durov", "name": "Pavel Durov", "myself": false } }

{ "ok": false, "found": null }

curl -X POST "https://api.fragment-api.io/api/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_type":"stars","query":"durov","quantity":"50"}'

{
  "transaction_id": "ord_a1b2c3d4e5f6...",
  "status": "pending",
  "recipient": "durov",
  "item_name": "50 Telegram Stars",
  "item_price": 0.8575,
  "payment_method": "usdt_ton"
}

{ "detail": "Insufficient usdt balance. Need 0.8575, have 0.5" }

curl -X POST "https://api.fragment-api.io/api/purchase" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_type":"stars","recipient":"durov","quantity":"50","payment_method":"usdt_ton","idempotency_key":"order-1001"}'

{ "transaction_id": "ord_...", "status": "completed", "ton_tx_id": "live:...", "...": "..." }

{ "detail": "Transaction not found" }

{ "detail": "Transaction not found" }

{ "transactions": [ { "...": "..." } ], "limit": 50, "offset": 0 }

{
  "wallet_address": "UQDVv_pPqr8U...",
  "currency": "usdt",
  "usdt_jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "usdt_jetton_master_suffix": "Id_sDs",
  "note": "Send TON to this address. For USDT TON use jetton contract …Id_sDs only."
}

Legacy v1

Deprecated endpoints for backward compatibility. Use /api/* for new integrations.Deprecated endpoints для обратной совместимости. Для новых интеграций используйте /api/*.

AI integrationAI интеграция

System prompt

You integrate fragment-api.io — provider API for Telegram Stars.

Base URL: https://api.fragment-api.io
Auth: X-API-Key: <merchant_api_key>

USDT deposits: jetton EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs (suffix …Id_sDs)

Payment methods: "ton" | "usdt_ton"

Workflow:
1. GET /api/balance
2. POST /api/search
3. GET /api/prices?product_type=stars&quantity=50&recipient=durov&payment_method=usdt_ton
4. POST /api/purchase with idempotency_key
5. Poll GET /api/purchase/transaction/{transaction_id} until completed

Errors: 401 auth, 402 insufficient balance, 404 not found
Min quantity: 50 stars (quantity is string)
OpenAPI: https://api.fragment-api.io/openapi.json

Agent checklistЧеклист для агентов

• Always use idempotency_key for purchasesВсегда используйте idempotency_key при покупках
• Check balance for the correct currency before purchaseПроверяйте баланс нужной валюты перед purchase
• USDT — only contract suffix Id_sDsUSDT — только контракт с суффиксом Id_sDs
• On 402 — top up deposit_addressПри 402 — пополните deposit_address
• Poll every 2–5 sec until terminal statusPoll interval: 2–5 сек до terminal status

OpenAPI

• Swagger UI
• ReDoc
• openapi.json