Документация API

Всё, что нужно для прямых HTTP запросов или работы через SDK.

Двухэтапный процесс заказа

API использует двухэтапный процесс заказа для обеспечения безопасных и надежных покупок:

  1. Создание заказа: Используйте POST /api/v1/orders/stars или POST /api/v1/orders/premium для создания заказа. Это резервирует покупку и рассчитывает общую стоимость с учетом комиссии.
  2. Оплата заказа: Используйте POST /api/v1/orders/:order_id/pay с вашим seed кошелька для завершения оплаты. Заказ будет поставлен в очередь на обработку.
  3. Проверка статуса: Опрашивайте GET /api/v1/queue/:request_id для мониторинга статуса обработки и получения финального результата.

Важно: Заказы истекают через 10 минут, если не оплачены.

Режимы KYC и без KYC

API поддерживает два режима покупки. KYC режим бесплатный навсегда; режим без KYC использует cookies владельца API и имеет комиссию.

KYC режим (бесплатно навсегда)

Предоставьте свои fragment_cookies с fragment.com и платите 0% комиссии API. Этот режим бесплатный навсегда.

0%комиссия

Режим без KYC (Стандартная комиссия)

Не предоставляйте fragment_cookies. API использует cookies владельца сервера.

1.0%комиссия

Совет: Если хотите перепроверить ставки перед использованием, вызовите GET /api/v1/commission/rates.

Эндпоинты API

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 CodeHTTP StatusMessageDescription
VALIDATION_ERROR400Validation failed

Request parameters failed validation. Check the details field for specific validation errors.

INVALID_USERNAME_FORMAT400Invalid username format

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

UNAUTHORIZED401Unauthorized

Admin-only endpoint was called without a valid X-Admin-Key.

INVALID_SEED400Invalid seed phrase

The provided seed phrase is not valid base64 or cannot be decoded.

INVALID_COOKIES400Invalid cookies

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

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.

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.

OWNER_COOKIES_NOT_CONFIGURED500Owner cookies not configured

Server is not configured with owner cookies for no_kyc mode.

OWNER_COOKIES_EXPIRED500Owner cookies expired

Server owner cookies have expired and need to be refreshed.

Клиентские токены не нужны

Клиентские endpoints API работают без выданных токенов. Для обычной покупки Stars и Premium не нужно ничего запрашивать у владельца сервиса.

Базовый API endpoint

https://fragment-api.ydns.eu:8443

Используйте этот URL как base URL для прямых HTTP запросов.

Аутентификация клиента

Заголовок авторизации не требуется

Отправляйте только параметры endpoint. Клиентское API открыто; лимиты применяются по IP.

Как API понимает, чей заказ?

Для покупок API получает TON адрес из переданного seed и использует этот wallet address для очереди, истории транзакций и учёта комиссии/долга.

Какие данные всё ещё нужны?

Для покупки endpoint всё равно требует seed кошелька, чтобы подписать TON транзакцию. В KYC режиме также нужны Fragment cookies/localStorage, чтобы покупка шла через ваш Fragment аккаунт.

Admin API отдельно

Только /admin endpoints защищены и используют X-Admin-Key. Это ключ администрирования сервера, не токен для клиентов API.

Пример прямого запроса

Если вы не используете Python SDK, вызывайте endpoint напрямую. Дополнительный auth заголовок не нужен:

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"
  }'