Разработчикам · API v1
API для Telegram Stars и Premium
Выдавайте Telegram Stars и Premium по @username прямо из своего магазина, бота или CRM. Один POST-запрос — и клиент получил товар. Оптовые цены, песочница, вебхуки, защита от двойного списания.
POST /v1/orders
Authorization: Bearer sk_live_…
{
"type": "stars",
"qty": 100,
"username": "@john",
"orderId": "order-123"
}{
"ok": true,
"orderId": "order-123",
"status": "completed",
"qty": 100,
"price": 0.121
}- Выдача за 2–3 секунды
- Идемпотентность по orderId
- Песочница без расходов
- Вебхуки с HMAC-подписью
Быстрый старт
curl -X POST https://api.krab.gg/v1/orders \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"type":"stars","qty":100,"username":"@john","orderId":"order-123"}'Имена полей принимаются и в «техническом» виде (recipient, externalId / idempotencyKey, product, quantity) — если копируете пример из чужой доки, переименовывать не нужно.
Для кого
Telegram-магазины и боты
Продаёте Stars и Premium в своём боте или на сайте? Принимайте оплату как удобно, а выдачу делегируйте API — по @username, мгновенно.
Реселлеры
Покупаете оптом с USDT-баланса и перепродаёте со своей наценкой. Цена фиксируется до заказа через /price — маржа предсказуема.
CRM и автоматизация
Встройте выдачу Stars и Premium в воронку: заказ из вашей CRM → POST /orders → клиент получил товар без ручной работы.
Сервисы и SaaS
Добавьте пополнение Telegram-баланса как функцию своего продукта — без склада, без ручной выдачи, по одному HTTP-вызову.
Что умеет API
Stars и Premium
Выдача Telegram Stars (от 50 до 1 000 000 за заказ) и Premium на 3, 6 или 12 месяцев по @username получателя — без пароля и кошелька.
Выдача за 2–3 секунды
Заказ выдаётся синхронно: вызвали POST /orders — клиент получил звёзды. Длинные случаи дотягивает фон, статус — по API или вебхуку.
Идемпотентность по orderId
Свой номер заказа в каждом запросе. Повтор того же orderId не создаёт дубль и не списывает дважды — безопасно при ретраях.
Песочница
Тестовый ключ sk_test_ или dryRun: true — всё считается, но баланс не трогается и выдача не идёт. Отладка без расходов.
Вебхуки с подписью
order.completed / order.failed приходят на ваш URL с подписью HMAC-SHA256 — можно не опрашивать статус.
Единый USDT-баланс
Один баланс в USDT, пополнение криптой (USDT в сети TON). Точную цену заказа возвращает GET /price до списания.
Основные эндпоинты
- GET
/v1/priceРасчёт цены (Stars / Premium) до заказа - GET
/v1/checkПроверка получателя по @username (можно ли слать) - POST
/v1/ordersСоздать и выдать заказ (идемпотентно по orderId) - GET
/v1/orders/:idСтатус заказа: получатель, количество, состояние - GET
/v1/balanceДоступный баланс USDT - GET
/v1/depositРеквизиты пополнения USDT (адрес + memo) - GET
/v1/webhookТекущий вебхук и секрет подписи - POST
/v1/webhookЗадать URL пуш-уведомлений (+ секрет подписи)
Как начать
- 01
Получите ключ
Откройте бота-кабинет @apistarsbot, оформите заявку и выпустите ключ sk_live_ (и sk_test_ для тестов).
- 02
Пополните баланс
Отправьте USDT в сети TON на ваш адрес с указанным memo. Зачисление — за секунды.
- 03
Выдавайте заказы
Дёргайте POST /v1/orders с @username получателя — клиент получает Stars или Premium.
Частые вопросы
Какие товары можно выдавать через API?
+
Telegram Stars (от 50 до 1 000 000 за заказ) и Telegram Premium на 3, 6 или 12 месяцев. Получатель указывается по @username — пароль и кошелёк не нужны.
Сколько стоит и как тарифицируется?
+
Цены оптовые, расчёт — единый USDT-баланс. Точную сумму конкретного заказа возвращает GET /v1/price до его создания, поэтому сюрпризов по курсу нет.
Что защищает от двойного списания?
+
Идемпотентность по вашему orderId: повтор запроса с тем же orderId возвращает уже созданный заказ и не списывает повторно — безопасно при ретраях и обрывах сети.
Есть ли тестовая среда?
+
Да. Тестовый ключ sk_test_ или поле dryRun: true — заказ полностью рассчитывается, но баланс не списывается и выдача не идёт. Можно отладить интеграцию без расходов.
Как узнать, что заказ выполнен?
+
Двумя способами: опрос GET /v1/orders/:id или вебхук — мы пришлём POST на ваш URL с HMAC-подписью при завершении (order.completed / order.failed).
Чем API отличается от покупки на сайте?
+
API — для магазинов, ботов и CRM: оптовые цены, программная выдача по @username, единый баланс и идемпотентность. Розничная покупка на сайте — для конечных клиентов.
Можно ли перепродавать Stars и Premium с наценкой?
+
Да. Вы покупаете по оптовой цене с USDT-баланса и устанавливаете свою розничную цену — маржа ваша. API только выдаёт товар получателю по @username.
Подходит ли API для Telegram-бота или магазина?
+
Да, это основной сценарий: оплату вы принимаете у себя, а выдачу Stars или Premium делаете одним вызовом POST /v1/orders. Идемпотентность по orderId защищает от двойной выдачи.
Как получить доступ к API?
+
Ключ выдаётся в боте-кабинете @apistarsbot: откройте его, оформите заявку и выпустите ключ. По объёмным условиям — напишите в поддержку.
Нужен доступ?
Заведите подключение в боте-кабинете @apistarsbot и выпустите ключ — sk_live_ и sk_test_ для тестов. Нужна помощь с интеграцией или объёмные тарифы — напишите в поддержку @heIIo_stars.