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:

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.
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.
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

The API supports two purchase modes. KYC mode is permanently free; non-KYC mode uses the API owner's cookies and has a commission.

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 (Standard Commission)

Don't provide fragment_cookies. The API uses the server owner's cookies.

1.0%commission

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

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

GET

/api/v1/wallet/balance

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

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 Code	HTTP Status	Message	Description
`VALIDATION_ERROR`	400	Validation failed	Request parameters failed validation. Check the details field for specific validation errors.
`INVALID_USERNAME_FORMAT`	400	Invalid username format	Username must start with @ and contain only alphanumeric characters and underscores (1-32 characters).
`UNAUTHORIZED`	401	Unauthorized	Admin-only endpoint was called without a valid X-Admin-Key.
`INVALID_SEED`	400	Invalid seed phrase	The provided seed phrase is not valid base64 or cannot be decoded.
`INVALID_COOKIES`	400	Invalid cookies	The provided fragment_cookies are not valid base64 or cannot be decoded.
`INSUFFICIENT_BALANCE`	400	Insufficient balance	Wallet does not have enough TON to complete the purchase.
`DEBT_LIMIT_EXCEEDED`	400	Debt limit exceeded	User has exceeded the maximum allowed debt limit.
`USER_NOT_FOUND`	404	User not found	The specified Telegram username does not exist.
`ORDER_NOT_FOUND`	404	Order not found	The specified order ID does not exist.
`REQUEST_NOT_FOUND`	404	Request not found	The specified request ID does not exist in the queue.
`QUEUE_TIMEOUT`	408	Queue timeout	Request timed out while waiting in the queue.
`PREMIUM_ALREADY_ACTIVE`	400	Premium already active	User already has an active Telegram Premium subscription.
`ORDER_EXPIRED`	400	Order expired	The order has expired and can no longer be paid.
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded	Too many requests. Please wait before making another request.
`INTERNAL_ERROR`	500	Internal server error	An unexpected error occurred on the server.
`FRAGMENT_ERROR`	502	Fragment service error	Error communicating with fragment.com service.
`SERVICE_UNAVAILABLE`	503	Service unavailable	The service is temporarily unavailable. Please try again later.
`OWNER_COOKIES_NOT_CONFIGURED`	500	Owner cookies not configured	Server is not configured with owner cookies for no_kyc mode.
`OWNER_COOKIES_EXPIRED`	500	Owner cookies expired	Server owner cookies have expired and need to be refreshed.

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://fragment-api.ydns.eu:8443

Use this URL as the base for direct HTTP requests.

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?

For purchases, the API derives the TON wallet address from the provided seed and uses that wallet address for queue status, transaction history, and commission/debt accounting.

What data is still required?

Purchase endpoints still need the wallet seed to sign the TON transaction. KYC mode also needs your Fragment cookies/localStorage so the purchase is made through your Fragment account.

Admin API is separate

Only /admin endpoints are protected, and they use X-Admin-Key. This key is for server administration, not for API clients.

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://fragment-api.ydns.eu:8443/api/v1/stars/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@username",
    "amount": 50,
    "seed": "BASE64_WALLET_SEED",
    "fragment_cookies": "BASE64_FRAGMENT_COOKIES"
  }'