REST 参考

一个公共 API，端到端完整文档。

搜索所有公共操作并查看请求和响应模式。

生产基础 URL

https://api.fragment-api.space

主要 Stars 流程

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

旧版兼容性

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

凭据仅限后端

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

公共端点

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

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

公共错误代码

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.