API Documentation

Everything you need to call the API directly or through SDKs.

Two-Step Order Flow

The API uses a two-step order flow to ensure secure and reliable purchases:

  1. Create Order: Use POST /api/v1/orders/stars or POST /api/v1/orders/premium to create an order. This reserves the purchase and calculates the total cost including commission.
  2. Pay Order: Use POST /api/v1/orders/:order_id/pay with your wallet seed to complete the payment. The order will be queued for processing.
  3. Check Status: Poll GET /api/v1/queue/:request_id to monitor the processing status and get the final result.

Important: Orders expire after 10 minutes if not paid.

KYC vs Non-KYC Modes

KYC is permanently free. No-KYC uses the managed purchase flow and costs only 0.25%.

KYC Mode (Free Forever)

Provide your own fragment_cookies from fragment.com and pay 0% API commission. This mode is permanently free.

0%commission

Non-KYC Mode (0.25%)

Don't provide fragment_cookies. The managed no-KYC purchase flow charges a 0.25% API commission.

0.25%commission

Tip: If you want to verify rates before use, call GET /api/v1/commission/rates.

12-word wallets and account_index

A 12-word BIP39 seed can derive multiple V5R1 wallet accounts. Existing 24-word TON mnemonics and raw keys keep their current behavior.

Choose the wallet for a purchase

Send seed alone for the default account, or add account_index, wallet_address, or both. When both are supplied, the API verifies that they match before any payment work starts.

"seed": "TWELVE_WORD_WALLET_SEED", "account_index": 3

Find an account index by address

Call POST /api/v1/wallet/resolve from your backend with seed plus wallet_address. It returns the matching account_index and resolved wallet metadata. You may also resolve by seed plus account_index.

POST /api/v1/wallet/resolve

Never put a seed in browser code or a URL. The resolver is POST-only and must be called from your backend or the Python SDK.

API Endpoints

Health

GET
/health

Health check

Stars

POST
/api/v1/stars/buy

Купить Telegram Stars (через очередь)

Orders

POST
/api/v1/stars/create

Создать заказ на Stars (шаг 1)

POST
/api/v1/stars/pay

Оплатить заказ (шаг 2)

GET
/api/v1/orders/{order_id}

Получить статус заказа

Queue

GET
/api/v1/queue/status

Получить общий статус очереди

GET
/api/v1/queue/{request_id}

Получить статус запроса в очереди

GET
/api/v1/queue

Получить длину очереди

Premium

POST
/api/v1/premium/check-eligibility

Проверить возможность получения Premium подарка

POST
/api/v1/premium/buy

Купить Telegram Premium

Wallet

POST
/api/v1/wallet/resolve

Resolve or verify a wallet account

Commission

GET
/api/v1/commission/balance

Получить баланс комиссии

GET
/api/v1/commission/rates

Получить ставки комиссий

Transactions

GET
/api/v1/transactions

Получить историю транзакций

Prices

GET
/api/v1/prices

Получить текущие цены

Error Codes

All error responses follow a consistent format with a machine-readable error code. Use these codes to handle errors programmatically.

Error CodeHTTP StatusMessageDescription
VALIDATION_ERROR422Validation failed

Request parameters failed validation. Stars amount must be at least 50; check details for the exact field.

INVALID_USERNAME_FORMAT400Invalid username format

Username must start with @ and contain only alphanumeric characters and underscores (1-32 characters).

INVALID_SEED401Invalid seed phrase

Seed must be a supported 12-word, 24-word, or Base64 wallet seed.

INVALID_WALLET_ADDRESS422Invalid wallet address

wallet_address is not a valid TON address. Pass the address of the wallet derived from this seed.

WALLET_ADDRESS_MISMATCH422Wallet address mismatch

The supplied account_index does not derive the supplied wallet_address from this seed.

ACCOUNT_INDEX_NOT_FOUND422Account index not found

No matching 12-word wallet account was found in the supported discovery range. Pass account_index explicitly.

INVALID_COOKIES400Invalid cookies

The provided fragment_cookies are not valid base64 or cannot be decoded.

INVALID_FRAGMENT_COOKIES422Invalid Fragment cookies

fragment_cookies must decode from Base64 to a complete JSON object or array. Fix the session export before retrying.

INVALID_FRAGMENT_LOCAL_STORAGE422Invalid Fragment localStorage

fragment_local_storage must decode from Base64 to a JSON object. Fix the session export before retrying.

INSUFFICIENT_BALANCE400Insufficient balance

Wallet does not have enough TON to complete the purchase.

DEBT_LIMIT_EXCEEDED400Debt limit exceeded

User has exceeded the maximum allowed debt limit.

USER_NOT_FOUND404User not found

The specified Telegram username does not exist.

ORDER_NOT_FOUND404Order not found

The specified order ID does not exist.

REQUEST_NOT_FOUND404Request not found

The specified request ID does not exist in the queue.

QUEUE_TIMEOUT408Queue timeout

Request timed out while waiting in the queue.

PREMIUM_ALREADY_ACTIVE400Premium already active

User already has an active Telegram Premium subscription.

ORDER_EXPIRED400Order expired

The order has expired and can no longer be paid.

RATE_LIMIT_EXCEEDED429Rate limit exceeded

Too many requests. Please wait before making another request.

API_BUSY429Purchase browser is busy

Another Premium purchase is active. Respect Retry-After and submit a new request manually; do not loop automatically.

INTERNAL_ERROR500Internal server error

An unexpected error occurred on the server.

FRAGMENT_ERROR502Fragment service error

Error communicating with fragment.com service.

SERVICE_UNAVAILABLE503Service unavailable

The service is temporarily unavailable. Please try again later.

No Client Tokens Required

Client API endpoints work without issued tokens. You do not need to request anything from the service owner for normal Stars and Premium purchases.

Base API endpoint

https://api.fragment-api.space

Use this URL as the base for direct HTTP requests.

Existing integrations using api-fragment.duckdns.org or fragment-api.ydns.eu remain supported.

Client authentication

No authorization header required

Send only the endpoint parameters. The client API is open; rate limits are applied by IP.

How are orders identified?

The API resolves the exact TON wallet from seed plus optional wallet_address/account_index. That resolved address identifies queue status, transaction history, and commission/debt accounting.

What data is still required?

Purchase endpoints need the wallet seed to sign the TON transaction. A 12-word multi-account wallet can also include account_index or wallet_address. KYC mode additionally needs your Fragment cookies/localStorage.

Direct request example

If you do not use the Python SDK, call the endpoint directly. No extra auth header is needed:

curl -X POST https://api.fragment-api.space/api/v1/stars/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@telegram_user",
    "amount": 50,
    "seed": "WALLET_SEED",
    "account_index": 0,
    "fragment_cookies": "BASE64_FRAGMENT_SESSION"
  }'