REST reference

One public API, documented end to end.

Search every public operation parsed from the OpenAPI specification, inspect request and response schemas, and distinguish current routes from legacy compatibility paths.

Production base URL

https://api.fragment-api.space

Primary Stars flow

Use POST /api/v1/stars/buy for new Stars integrations. It queues the purchase and returns a request ID for status checks.

Legacy compatibility

Only /api/v1/stars/create, /api/v1/stars/pay, and /api/v1/orders/{order_id} are marked legacy. They remain visible for existing integrations.

Credentials stay on the backend

Never send wallet seed or Fragment cookies from browser code. Documentation examples use obvious placeholders only.

YOUR_BASE64_ENCODED_SEED · YOUR_BASE64_ENCODED_COOKIES

Select the exact TON wallet account.

Twelve-word BIP39 seeds use V5R1 accounts derived from m/44'/607'/{account_index}'. Existing seed formats keep their current wallet selection behavior.

seed
Uses account index 0 for a 12-word seed.
seed + account_index
Selects the specified V5R1 account directly.
seed + wallet_address
Finds the matching common account index for the address.
seed + wallet_address + account_index
Verifies that the address and index resolve to the same wallet.

Need to find the index?

Call POST /api/v1/wallet/resolve from your backend with seed plus wallet_address. Use POST so the seed never appears in a URL or access log. Pass account_index explicitly for indexes above the common lookup range.

POST /api/v1/wallet/resolve

Public endpoints

GET

/health

Health check

POST

/api/v1/stars/buy

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

POST

/api/v1/stars/createLegacy

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

POST

/api/v1/stars/payLegacy

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

GET

/api/v1/orders/{order_id}Legacy

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

GET

/api/v1/queue/status

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

GET

/api/v1/queue/{request_id}

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

GET

/api/v1/queue

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

POST

/api/v1/premium/check-eligibility

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

POST

/api/v1/premium/buy

Купить Telegram Premium

GET

/api/v1/wallet/balance

Get wallet balance

POST

/api/v1/wallet/resolve

Resolve or verify a wallet account

GET

/api/v1/commission/balance

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

GET

/api/v1/transactions

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

GET

/api/v1/prices

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

GET

/api/v1/commission/rates

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

Public error codes

Handle the machine-readable error code and HTTP status. Server messages may contain additional context.

Error Code	HTTP Status	Message	Description
`VALIDATION_ERROR`	422	Validation failed	Request parameters failed validation. Stars amount must be at least 50; check details for the exact field.
`INVALID_USERNAME_FORMAT`	400	Invalid username format	Username must start with @ and contain only alphanumeric characters and underscores (1-32 characters).
`INVALID_SEED`	401	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.
`INVALID_FRAGMENT_COOKIES`	422	Invalid Fragment cookies	fragment_cookies must decode from Base64 to a complete JSON object or array. Fix the session export before retrying.
`INVALID_FRAGMENT_LOCAL_STORAGE`	422	Invalid Fragment localStorage	fragment_local_storage must decode from Base64 to a JSON object. Fix the session export before retrying.
`INVALID_WALLET_ADDRESS`	422	Invalid wallet address	wallet_address must be a valid TON raw or user-friendly address.
`WALLET_ADDRESS_MISMATCH`	422	Wallet address mismatch	wallet_address does not belong to the supplied seed and account_index. Correct the selector instead of retrying unchanged input.
`ACCOUNT_INDEX_NOT_FOUND`	422	Account index not found	The address was not found in the common BIP39 account range. Pass the exact account_index used by the wallet.
`INSUFFICIENT_BALANCE`	400	Insufficient balance	Wallet does not have enough TON to complete the purchase.
`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.
`API_BUSY`	429	Service is busy	Another request is active. Respect Retry-After before submitting a new request; do not loop automatically.
`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.