API · StarsPay

Введение

StarsPay Reseller API позволяет перепродавать Telegram Stars и Premium из вашего собственного приложения, бота или сайта. Все вызовы идут наhttps://stars-pay.shop/api/v1.

Каждый аккаунт StarsPay имеет один общий USD-баланс, с которого списывается стоимость заказа. Пополняйте через /cabinet/deposit (CryptoBot, LOLZ, Rolly, Heleket).

Цены берутся в реальном времени с Fragment.com
Маржа сервиса зашита в стоимость (видна как price_usd)
Доставка: ~30 секунд после оплаты
HTTP-коды как в обычном REST, ошибки как JSON

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

Каждый запрос требует API-ключ в заголовке:

X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

http

Альтернатива — стандартный Authorization: Bearer sk_.... Создавать/отзывать ключи можно в /cabinet/api-keys. Полный ключ показывается только при создании — после этого виден только префикс.

⚠️ Безопасность

Не пушьте ключ в git — используйте переменные окружения
На клиенте (браузер/мобильное) ключ не использовать — только сервер→сервер
При утечке — отзовите ключ и создайте новый

🚀 Quick start

За 4 шага от нуля до первой проданной звезды:

1. Создайте ключ
Зайдите в /cabinet/api-keys, нажмите «Создать», скопируйте sk_....
2. Пополните баланс
/cabinet/deposit — выберите шлюз и сумму.
3. Проверьте подключение
```
curl -H "X-API-Key: $KEY" https://stars-pay.shop/api/v1/reseller/me
```
bash

4. Сделайте первую покупку

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"recipient_username":"durov","amount":100}' \
  https://stars-pay.shop/api/v1/reseller/buy/stars

bash

📚 Эндпойнты

GET/reseller/me

Кому принадлежит ключ + текущий баланс. Используйте для проверки подключения.

Запрос

curl -H "X-API-Key: $KEY" https://stars-pay.shop/api/v1/reseller/me

bash

Ответ

{
  "user_id": 8652199793,
  "username": "shopclaude",
  "label": "prod-bot",
  "perms": "reseller",
  "balance_usd": 90.05
}

json

GET/reseller/balance

Только баланс в USD — лёгкий эндпойнт для быстрых проверок.

Запрос

bash

Ответ

{ "balance_usd": 90.05 }

json

POST/reseller/buy/stars

Купить Telegram Stars любому @username.

Параметры

Поле	Тип	Описание
recipient_username*	string	Telegram username получателя (без @, регекс [A-Za-z0-9_]{4,32})
amount*	integer	Количество звёзд (50–100000)

Запрос

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"recipient_username":"durov","amount":100}' \
  https://stars-pay.shop/api/v1/reseller/buy/stars

bash

Ответ

{
  "ok": true,
  "order_id": 152,
  "status": "pending_processing",
  "price_usd": 1.65,
  "balance_usd": 88.40,
  "note": "Order accepted; poll /v1/reseller/orders/{id}."
}

json

POST/reseller/buy/premium

Подарить Telegram Premium на 3, 6 или 12 месяцев.

Параметры

Поле	Тип	Описание
recipient_username*	string	@username получателя без @
months*	integer	3, 6 или 12

Запрос

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"recipient_username":"durov","months":3}' \
  https://stars-pay.shop/api/v1/reseller/buy/premium

bash

Ответ

{
  "ok": true,
  "order_id": 153,
  "status": "pending_processing",
  "price_usd": 13.15,
  "balance_usd": 75.25
}

json

GET/reseller/orders

Список заказов (новейшие сверху).

Параметры

Поле	Тип	Описание
limit	integer	1–100, default 25
offset	integer	default 0

Запрос

curl -H "X-API-Key: $KEY" "https://stars-pay.shop/api/v1/reseller/orders?limit=10&offset=0"

bash

Ответ

{
  "orders": [
    {
      "id": 152,
      "user_id": 8652199793,
      "order_type": "stars",
      "stars_amount": 100,
      "premium_months": null,
      "recipient_username": "durov",
      "price_usd": 1.65,
      "cost_usd": 1.50,
      "status": "completed",
      "created_at": "2026-05-02T22:40:51Z",
      "completed_at": "2026-05-02T22:41:23Z"
    }
  ]
}

json

GET/reseller/orders/{id}

Текущий статус одного заказа. Полезно для polling после buy.

Параметры

Поле	Тип	Описание
id*	integer	ID заказа из ответа /buy/*

Запрос

curl -H "X-API-Key: $KEY" https://stars-pay.shop/api/v1/reseller/orders/152

bash

Ответ

{
  "id": 152,
  "status": "completed",
  "stars_amount": 100,
  "recipient_username": "durov",
  "price_usd": 1.65,
  "completed_at": "2026-05-02T22:41:23Z",
  "fragment_tx_id": "abc123..."
}

json

⚠️ Коды ошибок

HTTP	error	Что значит и что делать
400	bad_recipient	@username не подходит под Telegram (4–32 символа [A-Za-z0-9_])
400	bad_amount	amount < MIN_STARS (50) или > MAX_STARS (100000)
400	bad_months	months ≠ 3, 6 или 12
400	quote_failed: no_quote	У получателя нет аккаунта Telegram, есть KYC-блок Fragment, или уже Premium
401	invalid_api_key	Ключ не существует или отозван — проверьте X-API-Key
402	insufficient_balance	Не хватает $ — пополните через /cabinet/deposit. Возвращает required_usd и balance_usd
429	rate_limited	Превышен лимит — заголовок Retry-After подскажет таймаут
503	no_rate	Курс TON→USD недоступен (временное)
503	fragment_unavailable	Fragment API недоступен — повторить через минуту

Все ошибки приходят в формате {"error": "key", ...details}.

🧠 Жизненный цикл заказа

1. POST /reseller/buy/* — re-quote (свежая цена) → atomic списание баланса.
2. Создаётся order со статусом pending_processing → processing.
3. Выполняется Fragment-доставка. Branches:

completed

Звёзды/Premium доставлены. fragment_tx_id заполнен.

processing

Tx ушла в TON, но не подтверждена. Деньги списаны, ждём подтверждения.

failed

Auto-refund: списание возвращается на баланс.

Чтобы узнать финальный статус — пуллите GET /reseller/orders/{id} раз в 5–10 секунд (timeout 60с).

🛡️ Лимиты

• 20 запросов/мин на ключ для buy/*

• 60 запросов/мин на uid для quote/* (через web)

• Минимальная покупка: 50 ⭐

• Максимальная: 100 000 ⭐

• Premium: только 3, 6 или 12 месяцев

• Username получателя: [A-Za-z0-9_]{4,32} (формат Telegram)

• Один ключ может выпускаться 10 раз/час

📬 Webhooks (на подходе)

Сейчас статусы заказов нужно опрашивать через GET /reseller/orders/{id}. В следующем релизе появятся webhook-уведомления (order.completed, order.failed) — настраиваются в кабинете на тот же URL что и API-ключ.