Документация APIshiba-bank.com · API
API · v1.1

Shiba Bank API

Начисляйте звёзды со своего кошелька в @shiba_bank_app на кошельки людей прямо из своего сервиса: награды за действия, призы, выплаты модераторам. Звёзды не покидают бот — они переходят из кошелька в кошелёк, как по команде +send.

А ИИ-агенты и сервисы покупают звёзды и Telegram Premium на любой @username — за USDT или GRAM в сети TON или за звёзды кошелька. Для агентов есть MCP-сервер: заказы, подключение.

Базовый адрес
URL
https://shiba-bank.com/api/v1

Как это устроено простыми словами — в статье Telegram Stars API.

Содержание
  1. Быстрый старт
  2. Основы
  3. Ключ и авторизация
  4. Безопасность
  5. Лимиты
  6. Идемпотентность и повторы
  7. POST /transfers
  8. GET /transfers/{id}
  9. GET /transfers
  10. GET /balance
  11. GET /me
  12. GET /recipients/{telegram_id}
  13. GET /status
  14. Заказы для ИИ-агентов
  15. POST /orders
  16. GET /orders/{id}
  17. GET /quote · GET /catalog
  18. POST /recipients/check
  19. MCP-сервер
  20. Уведомление и комментарий
  21. Ошибки
  22. Примеры кода
  23. FAQ
  24. История версий

Быстрый старт

  1. Откройте @shiba_bank_app, отправьте /api и нажмите «🔑 Создать ключ». Ключ покажется один раз — сохраните его в переменную окружения SHIBA_API_KEY на своём сервере.
  2. Пополните кошелёк бота: переводы идут только из вашего баланса.
  3. Проверьте ключ и баланс:
    curl
    curl https://shiba-bank.com/api/v1/balance -H "Authorization: Bearer $SHIBA_API_KEY"
  4. Переведите звёзды:
    curl
    curl -X POST https://shiba-bank.com/api/v1/transfers \
      -H "Authorization: Bearer $SHIBA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'
    Ответ:
    JSON
    {
      "success": true,
      "end_balance": 307,
      "replayed": false,
      "transfer": {
        "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
        "status": "completed",
        "telegram_id": 123456789,
        "amount": 5,
        "comment": "за модерацию никнейма",
        "notify": true,
        "idempotency_key": "moderation-8841",
        "error": null,
        "end_balance": 307,
        "created_at": "2026-09-23T14:13:05.120931Z"
      }
    }

Получателю бот сам пришлёт сообщение с суммой, отправителем и вашим комментарием, если notify не false.

Основы

  • Только HTTPS. Запросы и ответы — JSON в UTF-8.
  • В каждом ответе есть success: true или false. При false — объект error с постоянным code (на него и опирайтесь в коде), message для человека и подробностями, а также request_id.
  • Заголовок X-Request-Id есть у каждого ответа — укажите его, если пишете в поддержку.
  • Суммы — целые звёзды. Время — ISO 8601 в UTC, с Z на конце.
  • Числа можно передавать и строкой из цифр ("5"), логические — только true/false.
  • Неизвестные поля отвергаются (unknown_field) — так опечатка не превратится в тихо проигнорированный параметр.
  • Версия в адресе — /api/v1. Внутри v1 поля только добавляются, ничего не удаляется и не меняет смысл.
ЗаголовокКогдаЗначение
AuthorizationвсегдаBearer sbk_…
Content-TypePOSTapplication/json
Idempotency-KeyPOST /transfers, по желанию вместо полятот же, что idempotency_key

Ключ и авторизация

Каждый запрос, кроме /status, несёт ключ в заголовке:

HTTP
Authorization: Bearer sbk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Можно и X-Api-Key: sbk_…. Ключ в адресе (?key=) отвергается и считается раскрытым.

  • Ключ — 256 случайных бит, начинается с sbk_. Бот хранит только его отпечаток SHA-256 и показывает ключ один раз.
  • Ключ у аккаунта один. «♻️ Новый ключ» в /api сразу отключает старый; «🗑 Отозвать» отключает без замены. Лимиты и адреса при этом сохраняются.
  • Ключ действует от имени владельца: платит его кошелёк, и отправителем получатель видит его.

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

Что ключ может: читать ваш баланс, лимиты и свои переводы; проверять, может ли человек получить звёзды; переводить звёзды с вашего кошелька на кошельки людей в боте.

С включёнными в /api заказами ключ ещё может: выставлять вам счета в USDT и GRAM на звёзды и Premium для любого @username (платите вы со своего кошелька TON) и тратить на такие заказы звёзды вашего кошелька — в пределах лимитов. По умолчанию заказы выключены.

Чего ключ не может никогда: продавать звёзды, списывать с чужих кошельков, менять свои лимиты, адреса и включать себе заказы, видеть чужие данные. Настройки меняются только в самом боте.

Как защитить ключ

  • Держите ключ только на сервере: в переменной окружения или хранилище секретов. Не кладите его в репозиторий, в код бота-клиента, в мини-приложение или сайт — всё, что уходит в браузер или телефон, можно прочитать.
  • API отвечает только серверам: заголовков CORS нет, и браузер чужой страницы ваш ключ не использует.
  • Поставьте в /api → «🌐 Адреса» IP своего сервера — ключ перестанет работать откуда-либо ещё.
  • Выставьте лимиты под реальную нагрузку: суточный лимит — это наибольшее, что можно потерять при утечке ключа.
  • Держите на кошельке столько, сколько нужно на ближайшие выплаты, а не всё.
  • Подозреваете утечку — сразу «♻️ Новый ключ» или «🗑 Отозвать». Старый ключ перестаёт работать в ту же секунду.

Что делает сервер

  • Каждый перевод идёт той же дорогой, что +send: антифрод, заморозки и баны действуют так же.
  • Переводы одного ключа выполняются строго по одному, лимиты считаются атомарно — параллельные запросы не проскочат мимо суточного лимита.
  • Адрес, с которого часто приходят неверные ключи, временно получает отказ ещё до проверки ключа.
  • Комментарий очищается от невидимых и управляющих символов и не может содержать ссылки — получатель видит его как ваши слова, а не как сообщение бота.

Лимиты

ЧтоСколькоГде меняется
Один переводпо умолчанию 500 ⭐ максимум 100 000 ⭐/api → 📏
Сутки (UTC)по умолчанию 2000 ⭐ максимум 1 000 000 ⭐/api → 📅
Запросы на аккаунт10 в секунду, всплеск до 30—
Переводы на аккаунт3 в секунду, всплеск до 10; одновременно — один—
Запросы с одного IP10 в секунду, всплеск до 40 (сверх — HTTP 429 от веб-сервера)—
Тело запроса4096 байт—
Разрешённые адресадо 10 IP или подсетей/api → 🌐

Суточный лимит считается по суткам UTC (обнуляется в 00:00 UTC = 03:00 МСК) и включает все переводы ключа, выполненные и начатые. Текущие цифры — в GET /me.

При 429 и 503 смотрите заголовок Retry-After — через столько секунд можно повторить.

Идемпотентность и повторы

Сеть рвётся. Если ответ на перевод не дошёл, вы не знаете, списались ли звёзды. Поэтому у каждого перевода есть ваш ключ идемпотентности — постоянное имя операции: moderation-8841, order-1234-reward, daily-2026-09-23-user-42. Повторяйте запрос с тем же ключом сколько угодно — звёзды спишутся один раз.

СитуацияЧто ответит API
Новый ключВыполнит перевод.
Тот же ключ и те же поля, перевод выполненТот же ответ, replayed: true, ничего не списано повторно.
Тот же ключ и те же поля, перевод «pending»Доведёт тот же перевод до конца.
Тот же ключ, другие поля409 idempotency_conflict.
Тот же ключ после отказа (не хватило звёзд, лимит, заморозка)Пробует заново: отказ ничего не списал и ключ не занял.

Правило простое: ключ — из ваших данных, а не случайный на каждую попытку. Случайный ключ на каждую попытку отключает защиту от двойных выплат.

Повторять безопасно: сетевую ошибку, таймаут, HTTP 429, 500, 503. Не повторять без изменений: остальные 4xx — они не изменятся от повторения.

СтатусЧто значит
completedЗвёзды у получателя. Окончательно.
pendingПеревод начат, итог ещё не записан (обрыв связи или перезапуск). Повторите тот же запрос с тем же ключом — он доведёт перевод.
refusedОтказ, ничего не списано. Код — в error.

POST /transfers — перевод звёзд

Списывает звёзды с вашего кошелька и зачисляет на кошелёк получателя в боте.

ПолеТипОбязательноОписание
telegram_idintegerдаTelegram id получателя. Он должен хотя бы раз запустить @shiba_bank_app.
amountintegerдаСколько звёзд перевести: целое от 1 до 100 000 и не выше лимита ключа.
commentstringнетНазначение платежа, до 255 символов. Одна строка: переносы и повторные пробелы склеиваются. Без ссылок, доменов, @упоминаний и хештегов.
notifybooleanнет, trueПрислать ли получателю сообщение от бота о зачислении.
idempotency_keystringда*Ваш уникальный ключ операции, 1–64 символа A–Z a–z 0–9 _ - . :. Можно передать заголовком Idempotency-Key. *Не нужен при dry_run.
dry_runbooleanнет, falseПроверить всё (ключ, получателя, лимиты, баланс) и ничего не переводить.

Запрос

curl
curl -X POST https://shiba-bank.com/api/v1/transfers \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'

Успешный ответ — 200

JSON
{
  "success": true,
  "end_balance": 307,
  "replayed": false,
  "transfer": {
    "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
    "status": "completed",
    "telegram_id": 123456789,
    "amount": 5,
    "comment": "за модерацию никнейма",
    "notify": true,
    "idempotency_key": "moderation-8841",
    "error": null,
    "end_balance": 307,
    "created_at": "2026-09-23T14:13:05.120931Z"
  }
}
ПолеОписание
successtrue — звёзды зачислены.
end_balanceОстаток на вашем кошельке сразу после этого перевода.
replayedtrue, если это повтор уже выполненного перевода: новых списаний не было.
transfer.idНаш номер перевода, tr_….
transfer.statuscompleted, pending или refused.
transfer.errorКод отказа у refused, иначе null.

Проверка без перевода — dry_run

JSON
{
  "telegram_id": 123456789,
  "amount": 5,
  "dry_run": true
}
JSON
{
  "success": true,
  "dry_run": true,
  "end_balance": 307,
  "balance": 312
}

Ошибка — 422

JSON
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough Stars in the wallet.",
    "balance": 3,
    "required": 5
  },
  "request_id": "req_9b1e04c27d5a6f33"
}

GET /transfers/{id} — один перевод

Состояние перевода по нашему id (tr_…). Видны только переводы вашего аккаунта.

curl
curl https://shiba-bank.com/api/v1/transfers/tr_5f0c2a9e41b7d3c8a6e1f024 -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "transfer": {
    "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
    "status": "completed",
    "telegram_id": 123456789,
    "amount": 5,
    "comment": "за модерацию никнейма",
    "notify": true,
    "idempotency_key": "moderation-8841",
    "error": null,
    "end_balance": 307,
    "created_at": "2026-09-23T14:13:05.120931Z"
  }
}

GET /transfers — история переводов

Переводы через API вашего аккаунта, новые первыми.

ПараметрОписание
limit1–100, по умолчанию 20.
cursornext_cursor из прошлого ответа — следующая страница.
statuspending | completed | refused
idempotency_keyНайти перевод по своему ключу — удобно, если ответ потерялся.
telegram_idТолько переводы этому получателю.
curl
curl "https://shiba-bank.com/api/v1/transfers?limit=50&status=completed" -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "transfers": [
    {
      "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
      "status": "completed",
      "telegram_id": 123456789,
      "amount": 5,
      "comment": "за модерацию никнейма",
      "notify": true,
      "idempotency_key": "moderation-8841",
      "error": null,
      "end_balance": 307,
      "created_at": "2026-09-23T14:13:05.120931Z"
    }
  ],
  "next_cursor": "tr_5f0c2a9e41b7d3c8a6e1f024"
}

next_cursor равен null на последней странице.

GET /balance — баланс

Сколько звёзд на вашем кошельке доступно прямо сейчас.

curl
curl https://shiba-bank.com/api/v1/balance -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "telegram_id": 555000111,
  "balance": 312
}

GET /me — ключ, лимиты, баланс

Всё о ключе одним запросом: чей он, лимиты, сколько потрачено сегодня, разрешённые адреса.

JSON
{
  "success": true,
  "telegram_id": 555000111,
  "username": "my_service_owner",
  "balance": 312,
  "key": {
    "prefix": "sbk_Q2x9aZ1p…",
    "created_at": "2026-09-23T10:00:00Z",
    "last_used_at": "2026-09-23T14:12:44Z"
  },
  "limits": {
    "per_transfer": 500,
    "daily": 2000,
    "used_today": 120,
    "remaining_today": 1880,
    "resets_at": "2026-09-24T00:00:00Z",
    "allowed_ips": [
      "203.0.113.7"
    ]
  },
  "api_version": "1.1"
}

GET /recipients/{telegram_id} — можно ли перевести

Проверка до обещания награды: can_receive — true, если человек запускал @shiba_bank_app и его кошелёк доступен. Имени и других данных API не раскрывает.

JSON
{
  "success": true,
  "telegram_id": 123456789,
  "can_receive": true
}

Если false — попросите человека открыть @shiba_bank_app и нажать «Старт»: звёзды на аккаунт, который бот не знает, не переводятся, иначе они бы потерялись.

Не больше 200 проверок в сутки (UTC) на аккаунт, дальше — 429 rate_limited с retry_after до полуночи. Проверкой считаются и dry_run, и перевод тому, кому этот кошелёк ещё не платил; новый ключ счёт не обнуляет, а выпустить можно не больше 5 ключей в сутки. Проверяйте тех, кому собираетесь платить, а не списки.

GET /status — жив ли API

Без ключа. Для мониторинга.

JSON
{
  "success": true,
  "api_version": "1.1",
  "time": "2026-09-23T14:13:05Z",
  "docs": "/api/docs"
}

Описание OpenAPI 3.1 для Postman, Swagger и генераторов кода: /api/v1/openapi.json

Заказы для ИИ-агентов

Ключ покупает звёзды и Telegram Premium для любого @username. Это обычный заказ бота: та же проверка получателя через Fragment, та же выдача и те же возвраты, а наценка — 3 %, ниже, чем в боте. Заказы со звёзд кошелька идут без комиссии. Платить можно двумя способами:

  • USDT или GRAM в сети TON (pay: usdt | gram). API отвечает счётом: адрес проекта, точная сумма, комментарий и готовая транзакция TON Connect. Платите со своего кошелька; бот сам находит оплату в сети (обычно за 10–40 секунд) и выдаёт заказ.
  • Звёзды кошелька в боте (pay: wallet). Звёзды списываются с вашего кошелька, выдача начинается сразу: звёзды — один к одному, Premium — по цене в звёздах из /quote.

Как включить

  1. @shiba_bank_app → /api → «🛒 Включить заказы». Пока заказы выключены, /orders отвечает 403 orders_disabled.
  2. Лимиты счетов: «💵 За заказ» и «📅 Счета в сутки» — по умолчанию $50 за заказ и $200 в сутки максимум $1000 и $5 000. Заказы с кошелька считаются в лимитах звёзд ключа вместе с переводами.

Порядок работы

  1. GET /quote — цена сейчас во всех способах оплаты.
  2. POST /recipients/check — может ли аккаунт это получить.
  3. POST /orders — счёт или заказ с кошелька, с вашим idempotency_key.
  4. Оплатите payment: точная сумма и точный комментарий.
  5. GET /orders/{id}?wait=25 — ждите delivered.

Статусы заказа

СтатусЧто значит
awaiting_paymentСчёт ждёт оплаты: в payment — адрес, сумма и комментарий.
processingЗаказ с кошелька принят, звёзды или Premium уходят получателю.
payment_reviewПлатёж нашёлся, но не сходится со счётом (например, меньше суммы). Разбирает человек.
paidОплата подтверждена в сети, выдача начинается.
deliveringВыдача идёт через Fragment.
deliveredВыдано. В delivery — хеш транзакции и ссылка на обозреватель. Окончательно.
delivery_reviewВыдачу проверяет человек: доказательство выдачи пока не найдено.
refundedВыдать не удалось, возврат сделан по правилам бота — обычно звёздами на кошелёк владельца ключа. Окончательно.
expiredСчёт истёк без оплаты. Окончательно.
canceledОтменён. Окончательно.
failedЗаказ не создан: код в error. Ничего не списано.

Правила

  • Одновременно — один счёт на звёзды и один вывод с кошелька на аккаунт: следующий после оплаты и выдачи предыдущего или его истечения, иначе 409 order_in_progress. У Premium такого правила нет.
  • Не больше десяти неоплаченных счетов за десять минут.
  • Счёт живёт 30 минут, цена фиксируется при создании. Опоздавший USDT бот принимает ещё сутки; GRAM позже 30 минут после конца счёта бот сам не засчитывает — такой платёж возвращают вручную.
  • Проверка получателя — запрос к Fragment: не чаще раза в 5 секунд после первых пяти. Заказы — не чаще раза в 3 секунды после первых пяти.
  • Квитанции о заказах приходят владельцу ключа в чат бота, как при обычной покупке.

POST /orders — заказ

ПолеТипОбязательноОписание
productstringдаstars | premium
quantityintegerдаЗвёзды (от минимума до максимума из /catalog) или месяцы Premium: 3, 6, 12.
recipientstringдаПубличный @username получателя: @name, name или t.me/name.
paystringдаusdt или gram — счёт на ваш кошелёк TON; wallet — звёздами вашего кошелька в боте.
idempotency_keystringдаВаше имя этого заказа; повторяйте его при повторе запроса — будет один заказ. Или заголовок Idempotency-Key.
max_pricestringнетПотолок цены в том, чем платите: USDT, GRAM или звёзды. Дороже — 409 price_above_max, ничего не создано.
payer_addressstringнетАдрес вашего кошелька TON: тогда и у счёта в USDT будет готовая транзакция TON Connect.
dry_runbooleanнетПроверить всё — цену, лимиты, получателя — и ничего не создавать.

Запрос

curl
curl -X POST https://shiba-bank.com/api/v1/orders \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "stars", "quantity": 1000, "recipient": "@durov_fan", "pay": "usdt", "idempotency_key": "gift-2026-09-30-durov_fan", "max_price": "20"}'

Ответ — 200

JSON
{
  "success": true,
  "replayed": false,
  "order": {
    "id": "ord_3c1f9e0a7b24d58e61c09a4f",
    "object": "order",
    "product": "stars",
    "quantity": 1000,
    "recipient": "durov_fan",
    "pay": "usdt",
    "status": "awaiting_payment",
    "idempotency_key": "gift-2026-09-30-durov_fan",
    "created_at": "2026-09-30T15:02:11Z",
    "price": {
      "currency": "USDT",
      "amount": "16.300000",
      "usd": "16.30"
    },
    "paid_at": null,
    "delivered_at": null,
    "payment": {
      "currency": "USDT",
      "network": "TON",
      "address": "UQ…project",
      "amount": "16.300000",
      "amount_units": "16300000",
      "decimals": 6,
      "comment": "a1B2c3D4e5F6g7H8",
      "expires_at": "2026-09-30T15:32:11Z",
      "link": "https://app.tonkeeper.com/transfer/UQ…?amount=16300000&text=a1B2c3D4e5F6g7H8&jetton=EQCx…",
      "ton_uri": "ton://transfer/UQ…?amount=16300000&text=a1B2c3D4e5F6g7H8&jetton=EQCx…",
      "jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
      "forward_ton_amount": "1",
      "checkout_url": "https://…/payments/direct?token=…",
      "important": "Send exactly this amount with exactly this comment: the comment is what ties the payment to the order."
    }
  }
}

Как оплатить

  • GRAM: перевод amount_units нанотонов на address с текстовым комментарием comment. Или отдайте payment.tonconnect в sendTransaction TON Connect — там ровно этот перевод.
  • USDT: перевод жетона со своего USDT-кошелька: amount_units (6 знаков) на address, forward_ton_amount не меньше 1 нанотона и комментарий comment в forward_payload. С payer_address в запросе готовая транзакция будет в payment.tonconnect.
  • Людям — link (Tonkeeper), ton_uri или страница checkout_url.

Комментарий — единственное, что связывает платёж с заказом. Платёж без него бот не найдёт.

Python

Python
import os

import requests

API = "https://shiba-bank.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SHIBA_API_KEY']}"}
FINAL = {"delivered", "refunded", "expired", "canceled", "failed"}


def buy_stars(username: str, stars: int, key: str) -> dict:
    """An invoice in USDT for `stars` Stars to @username; `key` names this purchase."""
    answer = requests.post(
        f"{API}/orders",
        headers=HEADERS,
        json={
            "product": "stars",
            "quantity": stars,
            "recipient": username,
            "pay": "usdt",
            "idempotency_key": key,  # the same key on every retry: one invoice
            "max_price": "20",  # refuse if it costs more than 20 USDT
        },
        timeout=30,
    ).json()
    if not answer["success"]:
        raise RuntimeError(answer["error"]["code"])
    order = answer["order"]
    pay = order["payment"]
    # Send exactly pay["amount"] USDT to pay["address"] with the comment
    # pay["comment"] from your own TON wallet -- or hand pay["tonconnect"]
    # to TON Connect (ask with "payer_address" to get it for USDT).
    while order["status"] not in FINAL:
        order = requests.get(
            f"{API}/orders/{order['id']}", params={"wait": 25}, headers=HEADERS, timeout=40
        ).json()["order"]
    return order

GET /orders/{id} — заказ

ПараметрОписание
wait0–25 секунд: ответить, как только статус изменится. Удобно вместо частых опросов. Один ключ держит не больше 2 ожиданий одновременно; сверх этого заказ возвращается сразу с waited: false.
payer_addressДля неоплаченного счёта в USDT — собрать транзакцию TON Connect для этого кошелька. Не больше 3 новых кошельков за 10 минут на аккаунт; сверх — счёт без tonconnect.
curl
curl "https://shiba-bank.com/api/v1/orders/ord_3c1f9e0a7b24d58e61c09a4f?wait=25" -H "Authorization: Bearer $SHIBA_API_KEY"

GET /orders?limit=20&before=ord_… — ваши заказы, новые первыми, до 50 за раз; next_before — следующая страница. Реквизиты оплаты в списке не приходят — их отдаёт GET /orders/{id}.

GET /quote · GET /catalog — цены и товары

curl
curl "https://shiba-bank.com/api/v1/quote?product=stars&quantity=1000" -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "product": "stars",
  "quantity": 1000,
  "prices": {
    "usdt": {
      "currency": "USDT",
      "amount": "16.300000",
      "usd": "16.30"
    },
    "gram": {
      "currency": "GRAM",
      "amount": "5.114830000",
      "usd": "16.30"
    },
    "wallet": {
      "currency": "STARS",
      "amount": "1000"
    }
  },
  "valid_seconds": 20
}

Цены считают те же формулы, что кнопки бота, с наценкой API 3 %. /catalog называет товары, пределы количества и доступные способы оплаты.

POST /recipients/check — может ли аккаунт получить

JSON
{
  "recipient": "@durov_fan",
  "product": "stars",
  "quantity": 100
}
JSON
{
  "success": true,
  "recipient": "durov_fan",
  "product": "stars",
  "quantity": 100,
  "can_receive": false,
  "checked": true,
  "reason": "below_recipient_minimum",
  "minimum": 250,
  "message": "The account charges for messages: Telegram will not send it fewer Stars than that."
}

checked: false — Fragment не ответил; это не отказ, заказ всё равно проверит получателя ещё раз. Проверка доступна ключу с включёнными заказами: каждая — запрос к Fragment.

MCP-сервер

Агенты (Claude, Cursor, ChatGPT и любые MCP-клиенты) подключают API как набор инструментов — без своего кода. Транспорт Streamable HTTP, ответы JSON, ключ — тот же заголовок.

Строка подключения · Claude Code
Shell
claude mcp add --transport http shiba-bank https://shiba-bank.com/api/mcp --header "Authorization: Bearer $SHIBA_API_KEY"
Cursor и другие клиенты
JSON
{
  "mcpServers": {
    "shiba-bank": {
      "url": "https://shiba-bank.com/api/mcp",
      "headers": {"Authorization": "Bearer sbk_..."}
    }
  }
}

URL: https://shiba-bank.com/api/mcp

Инструменты

ИнструментЧто делает
get_accountThe key owner's Stars balance in the bot, the key's limits, whether orders are on and how much of today's limits (UTC) is used.
get_pricesWhat Stars or Premium cost now, for every way to pay: USDT, GRAM and wallet Stars.
check_recipientAsk Telegram (through Fragment) whether this account can receive this: not a channel or bot, no paid-message floor above the amount, no Premium already. Rationed: about one per 5 s.
create_orderBuy Stars or Premium for a Telegram @username. pay='usdt' or 'gram' returns an invoice to pay from your TON wallet (address, amount, comment, TON Connect transaction); pay='wallet' spends Stars from the key owner's bot wallet and delivers at once. dry_run=true checks and prices without ordering. max_price refuses the order above that price, in the unit you pay in.
get_orderAn order and its payment details. With wait_seconds (up to 25) it answers as soon as the status changes: awaiting_payment, paid, delivering, delivered, refunded, expired.
list_ordersThe key owner's API orders, newest first.
send_starsMove Stars from the key owner's bot wallet to another person's wallet in the bot, by Telegram id, with an optional comment. The person must have started the bot.

Без ключа сервер только представляется и называет инструменты; вызвать их можно только с ключом. Каждый инструмент — та же дверь REST API с теми же проверками и лимитами.

Уведомление и комментарий

При notify: true получатель получает от бота сообщение на своём языке:

⭐ Вам зачислено 5 ⭐
От: @my_service_owner

💬 «за модерацию никнейма»
👛 Кошелёк · 312 Stars
  • Отправитель — владелец ключа: @username, а без него — имя и id.
  • Сообщения идут через очередь бота: обычно за секунды, при массовых выплатах — дольше, но приходят. Звёзды зачислены в момент ответа API, сообщение их не ждёт и на них не влияет.
  • Если человек заблокировал бота, сообщения не будет, а звёзды всё равно на его кошельке.
  • notify: false — тихое зачисление: звёзды появятся в кошельке без сообщения.

Правила комментария

  • До 255 символов после очистки; эмодзи можно.
  • Одна строка: переносы и лишние пробелы склеиваются в один пробел; невидимые и управляющие символы удаляются.
  • Нельзя: ссылки, домены (site.com), t.me/…, @упоминания, хештеги — ответ comment_not_allowed. Так сообщение бота нельзя превратить в рекламу или фишинг.
  • Комментарий хранится с переводом и возвращается в transfer.comment.

Ошибки

JSON
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough Stars in the wallet.",
    "balance": 3,
    "required": 5
  },
  "request_id": "req_9b1e04c27d5a6f33"
}
КодHTTPЧто значит и что делать
invalid_json400Тело не JSON-объект в UTF-8 или поле повторено дважды.
invalid_request400Поле отсутствует, не того типа или вне диапазона — какое, скажет field.
unknown_field400Поле, которого API не знает (часто опечатка: ammount).
invalid_comment400comment не строка.
comment_too_long400Комментарий длиннее 255 символов.
comment_not_allowed400В комментарии ссылка, домен, @упоминание или хештег.
idempotency_key_required400Перевод без ключа идемпотентности.
invalid_idempotency_key400Ключ не по формату или в заголовке и в теле разные ключи.
key_in_url400Ключ API передан в адресе. Считайте его раскрытым и выпустите новый.
unauthorized401Ключа нет, он неверный или отозван.
key_blocked403Доступ к API у аккаунта заблокирован администрацией.
account_restricted403Аккаунт владельца ключа ограничен в боте.
ip_not_allowed403Адрес запроса не в списке разрешённых. Поле ip — какой адрес видит сервер.
invalid_product400product не stars и не premium.
invalid_pay400pay не usdt, gram или wallet.
invalid_quantity400Количество вне допустимого: звёзды — от minimum до maximum, Premium — 3, 6 или 12 месяцев.
invalid_recipient400Получатель — не публичный @username (4–32 латинские буквы, цифры, _).
invalid_max_price400max_price не положительное число.
invalid_payer_address400payer_address не адрес TON mainnet.
orders_disabled403Заказы для этого ключа выключены: включите их в /api в боте.
product_unavailable403Этот товар сейчас не продаётся.
not_found404Нет такого перевода или заказа (или он чужой).
recipient_not_found404Получатель ни разу не запускал бота или его кошелёк недоступен.
idempotency_conflict409Ключ уже занят другим переводом (другие получатель, сумма, комментарий или notify).
price_above_max409Цена выше вашего max_price; текущая — в price. Ничего не создано.
price_changed409Цена изменилась во время заказа. Спросите цену заново.
order_in_progress409Предыдущий счёт на звёзды или вывод с кошелька ещё не закончен (одновременно — один), либо этот же заказ ещё создаётся. Повторите через Retry-After.
payload_too_large413Тело больше 4096 байт.
unsupported_media_type415Нет заголовка Content-Type: application/json.
recipient_is_self422Перевод самому себе.
per_transfer_limit_exceeded422Сумма выше лимита на один перевод (limit).
daily_limit_exceeded422Перевод превысит суточный лимит: limit, used_today, remaining.
insufficient_balance422Не хватает звёзд: balance и required. Ничего не списано, тот же ключ можно повторить после пополнения.
wallet_frozen422Кошелёк отправителя или получателя заморожен или на проверке. Ничего не списано.
transfer_refused422Кошелёк отказал в переводе. Ничего не списано.
account_too_new422Аккаунт пока не может передавать звёзды (hours_left).
recipient_not_user422Это имя канала, группы или бота, а не человека.
recipient_unknown422Telegram не нашёл аккаунт с таким именем.
recipient_unavailable422Telegram сейчас не принимает подаренные звёзды для этого аккаунта.
recipient_has_premium422У аккаунта уже есть Telegram Premium.
below_recipient_minimum422Аккаунт берёт плату за сообщения: Telegram не отправит ему меньше minimum звёзд.
order_limit_exceeded422Счёт дороже лимита ключа на один заказ (limit_usd).
order_refused422Заказ отклонён, ничего не списано.
rate_limited429Слишком часто. Подождите Retry-After секунд.
too_many_failed_attempts429С вашего адреса много запросов с неверным ключом. Проверьте ключ и подождите.
too_many_unpaid_invoices429Десять неоплаченных счетов за десять минут: оплатите их или дождитесь, пока истекут.
internal_error500Ошибка у нас. Напишите в поддержку с request_id.
api_disabled503API временно выключен.
busy503Очередь переводов занята. Повторите тот же запрос через Retry-After.
outcome_unknown503Итог пока неизвестен. Повторите тот же запрос с тем же ключом — двойного списания не будет.
inventory_unavailable503Бот не может взять столько звёзд прямо сейчас: закажите меньше или позже.
inventory_check_failed503Бот не смог проверить свой запас. Повторите.
pay_unavailable503Этот способ оплаты сейчас недоступен.
prices_unavailable503Бот сейчас не может посчитать цену. Повторите через минуту.
delivery_unavailable503Выдача временно на паузе. Повторите позже.

Любой ответ 4xx означает: этим запросом ничего не списано. При 5xx итог может быть неизвестен — повторите тот же запрос с тем же ключом.

Примеры кода

curl
curl -X POST https://shiba-bank.com/api/v1/transfers \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'
Python
import os
import time

import requests

API = "https://shiba-bank.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SHIBA_API_KEY']}"}


class ShibaApiError(Exception):
    def __init__(self, code: str, message: str, details: dict):
        super().__init__(f"{code}: {message}")
        self.code, self.details = code, details


def give_stars(telegram_id: int, amount: int, comment: str, key: str, notify: bool = True) -> int:
    """Credit Stars and return the balance left. Safe to call again with the same key."""
    payload = {
        "telegram_id": telegram_id,
        "amount": amount,
        "comment": comment,
        "notify": notify,
        "idempotency_key": key,
    }
    for attempt in range(6):
        try:
            response = requests.post(f"{API}/transfers", headers=HEADERS, json=payload, timeout=40)
        except requests.RequestException:
            time.sleep(2 ** attempt)  # the network failed: the same key is safe to repeat
            continue
        if response.status_code in (429, 503) or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
            continue
        data = response.json()
        if data["success"]:
            return data["end_balance"]
        error = data["error"]
        raise ShibaApiError(error["code"], error["message"], error)
    raise RuntimeError("the API did not answer; repeat later with the same key")


balance = give_stars(123456789, 5, "за модерацию никнейма", key="moderation-8841")
print("left:", balance)
JavaScript
// Node.js 18+ (global fetch)
const API = "https://shiba-bank.com/api/v1";

async function giveStars(telegramId, amount, comment, key, notify = true) {
  const body = JSON.stringify({
    telegram_id: telegramId, amount, comment, notify, idempotency_key: key,
  });
  for (let attempt = 0; attempt < 6; attempt++) {
    let res;
    try {
      res = await fetch(`${API}/transfers`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.SHIBA_API_KEY}`,
          "Content-Type": "application/json",
        },
        body,
      });
    } catch (e) {
      await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
      continue;
    }
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After") || 2 ** attempt);
      await new Promise(r => setTimeout(r, 1000 * wait));
      continue;
    }
    const data = await res.json();
    if (data.success) return data.end_balance;
    const err = new Error(`${data.error.code}: ${data.error.message}`);
    err.details = data.error;
    throw err;
  }
  throw new Error("the API did not answer; repeat later with the same key");
}

giveStars(123456789, 5, "за модерацию никнейма", "moderation-8841").then(console.log);
PHP
<?php
function give_stars(int $telegramId, int $amount, string $comment, string $key, bool $notify = true): int {
    $ch = curl_init("https://shiba-bank.com/api/v1/transfers");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 40,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("SHIBA_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            "telegram_id" => $telegramId,
            "amount" => $amount,
            "comment" => $comment,
            "notify" => $notify,
            "idempotency_key" => $key,
        ], JSON_UNESCAPED_UNICODE),
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    if ($raw === false) {
        throw new RuntimeException("network error: repeat with the same key");
    }
    $data = json_decode($raw, true);
    if (!$data["success"]) {
        throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
    }
    return $data["end_balance"];
}

Массовая выплата

Отдельного пакетного метода нет: отправляйте переводы по одному, каждый со своим ключом (например, payout-2026-09-23-<telegram_id>). Если скрипт упал на середине — запустите его заново целиком: уже выполненные переводы вернутся с replayed: true и не спишутся второй раз.

Python
for user_id, stars in winners:
    give_stars(user_id, stars, "приз недели", key=f"weekly-2026-39-{user_id}")

FAQ

Откуда берутся звёзды для переводов?
Только с вашего кошелька в @shiba_bank_app. Пополнить — в боте: «👛 Кошелёк» → «Пополнить».
Что может получатель со звёздами?
Всё, что с любыми звёздами кошелька: вывести на аккаунт Telegram, продать, раздать в чате, отправить чеком.
Можно ли отменить перевод?
Нет. Выполненный перевод окончателен, как +send. Для проверки используйте dry_run.
Как узнать Telegram id человека?
Его присылает Telegram в каждом апдейте вашего бота: message.from.id. По @username API не переводит — username меняется, id нет.
Сколько стоит API?
Ничего: ключ и запросы ничего не стоят, переводы между кошельками без комиссии.
Мне пришёл 503 outcome_unknown — звёзды ушли?
Повторите тот же запрос с тем же ключом: придёт окончательный ответ, двойного списания не будет. Или посмотрите GET /transfers?idempotency_key=….
Нужен вебхук о входящих переводах или приём оплаты звёздами?
Напишите в поддержку бота, что именно нужно: так мы решим, что добавить в следующих версиях.

История версий

1.1 — 30.09.2026. Заказы звёзд и Telegram Premium на любой @username за USDT, GRAM или звёзды кошелька; цены, каталог, проверка получателя через Fragment, ожидание статуса (wait), готовые транзакции TON Connect, MCP-сервер для ИИ-агентов.

1.0 — 23.09.2026. Переводы, баланс, лимиты, история, проверка получателя, OpenAPI.

QR-код ссылки в Telegram

Откройте в Telegram

Наведите камеру телефона на код

Открыть в Telegram Desktop

Откроется окно Shiba Bank в Telegram.Откроется чат с ботом @shiba_bank_app.Telegram предложит выбрать группу и выдать боту права администратора.