Справочник REST

Единый публичный API — от запроса до ответа.

Ищите по всем публичным операциям из OpenAPI, изучайте схемы запросов и ответов и отличайте актуальные маршруты от legacy-совместимости.

Production base URL

https://api.fragment-api.space

Основной сценарий Stars

Для новых интеграций Stars используйте POST /api/v1/stars/buy. Endpoint ставит покупку в очередь и возвращает request ID для проверки статуса.

Legacy-совместимость

Legacy помечены только /api/v1/stars/create, /api/v1/stars/pay и /api/v1/orders/{order_id}. Они видимы для существующих интеграций.

Данные доступа остаются на бэкенде

Никогда не отправляйте seed кошелька или cookies Fragment из браузерного кода. В документации используются только очевидные заглушки.

YOUR_BASE64_ENCODED_SEED · YOUR_BASE64_ENCODED_COOKIES

Выберите точный TON-аккаунт кошелька.

Для 12-словных BIP39 seed используются V5R1 accounts по пути m/44'/607'/{account_index}'. Для существующих форматов seed прежнее поведение выбора кошелька сохраняется.

seed
Для 12-словного seed используется account index 0.
seed + account_index
Сразу выбирает указанный V5R1 account.
seed + wallet_address
Находит стандартный account index, соответствующий адресу.
seed + wallet_address + account_index
Проверяет, что адрес и индекс указывают на один кошелёк.

Нужно определить индекс?

Вызывайте POST /api/v1/wallet/resolve только с бэкенда и передавайте seed вместе с wallet_address. Используется POST, поэтому seed не попадает в URL и access logs. Для индексов выше стандартного диапазона передавайте account_index явно.

POST /api/v1/wallet/resolve

Публичные эндпоинты

GET

/health

Health check

POST

/api/v1/stars/buy

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

POST

/api/v1/stars/createУстаревший

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

POST

/api/v1/stars/payУстаревший

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

GET

/api/v1/orders/{order_id}Устаревший

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

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

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

Публичные коды ошибок

Обрабатывайте машиночитаемый код ошибки и HTTP-статус. Сообщение сервера может содержать дополнительный контекст.

Код ошибки	HTTP-статус	Сообщение	Описание
`VALIDATION_ERROR`	422	Ошибка валидации	Параметры запроса не прошли проверку. Минимальная покупка — 50 Stars; точное поле указано в деталях.
`INVALID_USERNAME_FORMAT`	400	Неверный формат username	Имя пользователя должно начинаться с @ и содержать только латинские буквы, цифры и подчёркивания.
`INVALID_SEED`	401	Неверный seed	Seed не является корректной Base64-строкой или не может быть декодирован.
`INVALID_COOKIES`	400	Неверные cookies	fragment_cookies не являются корректной Base64-строкой или не могут быть декодированы.
`INVALID_FRAGMENT_COOKIES`	422	Неверные cookies Fragment	fragment_cookies должны декодироваться из Base64 в полный JSON-объект или массив.
`INVALID_FRAGMENT_LOCAL_STORAGE`	422	Неверный localStorage Fragment	fragment_local_storage должен декодироваться из Base64 в JSON-объект.
`INVALID_WALLET_ADDRESS`	422	Неверный адрес кошелька	wallet_address должен быть корректным TON-адресом в raw или user-friendly формате.
`WALLET_ADDRESS_MISMATCH`	422	Адрес кошелька не совпадает	wallet_address не принадлежит переданным seed и account_index. Исправьте параметры вместо повтора того же запроса.
`ACCOUNT_INDEX_NOT_FOUND`	422	Индекс аккаунта не найден	Адрес не найден среди стандартных BIP39 accounts. Передайте точный account_index, используемый кошельком.
`INSUFFICIENT_BALANCE`	400	Недостаточно средств	На кошельке недостаточно TON для завершения покупки.
`USER_NOT_FOUND`	404	Пользователь не найден	Указанного пользователя Telegram не существует.
`ORDER_NOT_FOUND`	404	Заказ не найден	Заказ с указанным ID не существует.
`REQUEST_NOT_FOUND`	404	Запрос не найден	Запрос с указанным ID отсутствует в очереди.
`QUEUE_TIMEOUT`	408	Истекло время ожидания	Запрос слишком долго ожидал обработки в очереди.
`PREMIUM_ALREADY_ACTIVE`	400	Premium уже активен	У пользователя уже есть активная подписка Telegram Premium.
`ORDER_EXPIRED`	400	Срок заказа истёк	Срок действия заказа истёк, его больше нельзя оплатить.
`RATE_LIMIT_EXCEEDED`	429	Превышен лимит запросов	Слишком много запросов. Подождите перед следующей попыткой.
`API_BUSY`	429	Сервис занят	Уже выполняется другой запрос. Соблюдайте Retry-After перед отправкой нового запроса и не запускайте автоматический цикл повторов.
`INTERNAL_ERROR`	500	Внутренняя ошибка сервера	На сервере произошла непредвиденная ошибка.
`FRAGMENT_ERROR`	502	Ошибка сервиса Fragment	Ошибка при обращении к fragment.com.
`SERVICE_UNAVAILABLE`	503	Сервис недоступен	Сервис временно недоступен. Повторите попытку позже.