StaticGramBot API

Оплата статиками

Платежи в StaticGram работают во внутренних валютах: статики (currency = XTR) и коины (см. Счета в коинах). Платёжные провайдеры (provider_token) и фиатные валюты не поддерживаются.

Схема оплаты

  1. Бот выставляет счёт: sendInvoice в чат или createInvoiceLink для ссылки.
  2. Пользователь нажимает «Оплатить», бот получает обновление pre_checkout_query.
  3. Бот в течение 10 секунд отвечает answerPreCheckoutQuery с ok: true (или с ошибкой, чтобы отменить оплату).
  4. Статики списываются, в чат приходит сообщение с полем successful_payment. Сохраните telegram_payment_charge_id: он нужен для возврата.

Выставление счёта

Shell
curl "https://api.staticgram.top/bot$TOKEN/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Премиум-доступ",
    "description": "30 дней без ограничений",
    "payload": "premium-30d-user-123",
    "currency": "XTR",
    "prices": [{"label": "Премиум", "amount": 100}]
  }'

provider_token передавать не нужно (пустая строка допустима). Для XTR в prices должна быть ровно одна позиция. Можно передать свою клавиатуру, но первой кнопкой должна быть кнопка оплаты (pay: true).

Обработка на aiogram 3

Python
from aiogram import F
from aiogram.types import LabeledPrice, Message, PreCheckoutQuery


@dp.message(F.text == "/buy")
async def buy(message: Message):
    await message.answer_invoice(
        title="Премиум-доступ",
        description="30 дней без ограничений",
        payload="premium-30d",
        currency="XTR",
        prices=[LabeledPrice(label="Премиум", amount=100)],
    )


@dp.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
    await query.answer(ok=True)


@dp.message(F.successful_payment)
async def paid(message: Message):
    charge_id = message.successful_payment.telegram_payment_charge_id
    await message.answer(f"Оплата получена: {charge_id}")

Лимиты счетов

Значение
ВалютаXTR (статики) или коины (TON/GRAM, удобнее — sendGramInvoice); другая валюта или непустой provider_token → 400 PAYMENT_PROVIDER_INVALID
Сумма счёта в коинахот 0.01 до 10 000 коинов, не больше 9 знаков после запятой; без подписок
Сумма счёта (sendInvoice, createInvoiceLink)от 1 до 100 000 статиков (сумма всех prices); иначе 400 CURRENCY_TOTAL_AMOUNT_INVALID
Подписка (createInvoiceLink с subscription_period)период ровно 2592000 (30 дней), цена от 1 до 10 000 статиков
Платная подписка на канал (createChatSubscriptionInviteLink)период 2592000, цена 1-10 000 статиков
Платные медиа (sendPaidMedia)star_count от 1 до 25 000
title / description / payload1-32 символа / 1-255 символов / 1-128 байт
Ответ на pre_checkout_query10 секунд

Возвраты, баланс, подписки

  • refundStarPayment возвращает статики пользователю по telegram_payment_charge_id; в чат приходит сервисное сообщение refunded_payment. Повторный возврат: CHARGE_ALREADY_REFUNDED, не хватает статиков на балансе бота: BALANCE_TOO_LOW.
  • getMyStarBalance и getStarTransactions показывают баланс и историю операций бота.
  • Подписки: createInvoiceLink с subscription_period = 2592000 продлевается автоматически; управлять ей можно через editUserStarSubscription.
  • Платный контент: sendPaidMedia работает в личных чатах, каналах, супергруппах и бизнес-чатах.
  • Платные подписки на канал: createChatSubscriptionInviteLink (только каналы), статики поступают на баланс канала.
  • Оплата из Mini App: createInvoiceLink + Telegram.WebApp.openInvoice, см. Mini Apps.

Счета в коинах

Расширение StaticGram

Коины — внутренняя валюта StaticGram (в API обозначается TON/GRAM, баланс TON пользователя). Методов sendGramInvoice и createGramInvoiceLink нет в официальном Bot API, библиотеки их не знают: вызывайте обычным HTTP-запросом или опишите метод в aiogram, как в примере ниже.

sendGramInvoice отправляет счёт в чат, createGramInvoiceLink возвращает ссылку на счёт (например, для Telegram.WebApp.openInvoice). Параметры — как у sendInvoice / createInvoiceLink, но без currency, prices и provider_token: цена передаётся одним полем в коинах.

ПараметрТипОбязателенОписание
amountString или Floatодин из двухЦена в коинах: "1.5", "0,01", 2.5. Точка или запятая, не больше 9 знаков после запятой. Для дробных сумм надёжнее строка.
nanoton_amountIntegerодин из двухЦена в нанотонах: 1 коин = 1 000 000 000.
labelStringнетПодпись позиции, до 64 символов. По умолчанию — title.
chat_id, title, description, payload, photo_url, photo_size, photo_width, photo_height, start_parameter, message_thread_id, disable_notification, protect_content, reply_parameters, reply_markupКак у sendInvoice (chat_id, message_thread_id, reply_* — только для sendGramInvoice). Своя клавиатура — с кнопкой pay: true первой.

Сумма — от 0.01 до 10 000 коинов, как у обычных счетов в коинах. Подписки в коинах не поддерживаются.

Shell
curl "https://api.staticgram.top/bot$TOKEN/sendGramInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Премиум-доступ",
    "description": "30 дней без ограничений",
    "payload": "premium-30d-user-123",
    "amount": "1.5"
  }'

curl "https://api.staticgram.top/bot$TOKEN/createGramInvoiceLink" \
  -H "Content-Type: application/json" \
  -d '{"title": "Пополнение", "description": "Игровой счёт", "payload": "topup-123", "amount": "0,01"}'

aiogram 3: опишите метод как TelegramMethod и вызывайте через bot(...). Обработчики pre_checkout_query и successful_payment — те же, что для статиков.

Python
from aiogram import Bot, F
from aiogram.methods.base import TelegramMethod
from aiogram.types import InlineKeyboardMarkup, Message, PreCheckoutQuery


class SendGramInvoice(TelegramMethod[Message]):
    __returning__ = Message
    __api_method__ = "sendGramInvoice"

    chat_id: int | str
    title: str
    description: str
    payload: str
    amount: str | float | None = None
    nanoton_amount: int | None = None
    label: str | None = None
    reply_markup: InlineKeyboardMarkup | None = None


class CreateGramInvoiceLink(TelegramMethod[str]):
    __returning__ = str
    __api_method__ = "createGramInvoiceLink"

    title: str
    description: str
    payload: str
    amount: str | float | None = None
    nanoton_amount: int | None = None
    label: str | None = None


@router.message(F.text == "/buy")
async def buy(message: Message, bot: Bot):
    await bot(SendGramInvoice(chat_id=message.chat.id, title="Премиум-доступ",
                              description="30 дней без ограничений",
                              payload=f"premium-{message.from_user.id}", amount="1.5"))
    link = await bot(CreateGramInvoiceLink(title="Пополнение", description="Игровой счёт",
                                           payload="topup", amount="0,01"))


@router.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
    await query.answer(ok=True)  # query.currency == "TON", query.total_amount в нанотонах


@router.message(F.successful_payment)
async def paid(message: Message):
    sp = message.successful_payment
    gram = sp.model_extra.get("gram_amount")  # "1.5" — поле StaticGram
    charge_id = sp.telegram_payment_charge_id  # для refundGramPayment

Оплата идёт с баланса коинов пользователя на баланс коинов бота. Обновления — как у обычного счёта в коинах: в invoice, pre_checkout_query, successful_payment и refunded_payment приходят currency = "TON", total_amount в нанотонах и дополнительное поле StaticGram gram_amount — сумма в коинах строкой:

JSON
"successful_payment": {
  "currency": "TON",
  "total_amount": 1500000000,
  "gram_amount": "1.5",
  "invoice_payload": "premium-30d-user-123",
  "telegram_payment_charge_id": "stx...",
  "provider_payment_charge_id": "..."
}

Ошибки (400): AMOUNT_INVALID (нет цены, переданы обе, не число или больше 9 знаков после запятой), AMOUNT_TOO_SMALL (меньше 0.01 коина), AMOUNT_TOO_LARGE (больше 10 000 коинов), CURRENCY_INVALID (передан currency, отличный от GRAM/TON), PRICES_INVALID (передан prices или label длиннее 64 символов), PAYMENT_PROVIDER_INVALID (передан provider_token), а также ошибки sendInvoice (INVOICE_TITLE_INVALID и т. п.). Текст ошибки объясняет, что не так, например Bad Request: AMOUNT_TOO_SMALL: the minimum GRAM invoice is 0.01 GRAM (10000000 nanoton), got 0.001 GRAM.

Деньги бота в коинах: getMyGramBalance — баланс (nanoton_amount и gram_amount), refundGramPayment (user_id, telegram_payment_charge_id) — возврат платежа, withdrawGramBalance (user_id, nanoton_amount, request_id — все необязательные) — вывод владельцу или пользователю. Синонимы: getMyTonBalance, refundTonPayment, withdrawTonBalance. Поле gram_amount описано в типах Invoice, PreCheckoutQuery, SuccessfulPayment и RefundedPayment.

Вывод статиков владельцу бота

Расширение StaticGram

Метода withdrawStarBalance нет в официальном Bot API Telegram. Библиотеки (aiogram, python-telegram-bot и др.) его не знают — вызывайте его обычным HTTP-запросом, как в примере ниже.

Статики, которые бот заработал (счета XTR, платный контент, подписки), владелец бота может вывести на свой аккаунт двумя способами:

  • в @BotFather: команда /bank (или кнопка «⭐ Звёзды» в карточке бота из /mybots) → выбор бота → «Вывести» → сумма или «Вывести всё» → подтверждение. Там же кнопка «Возврат платежа»: пришлите telegram_payment_charge_id, подтвердите — и статики вернутся покупателю, как при refundStarPayment;
  • самим ботом — методом withdrawStarBalance.

Владелец получает статики нативно: от официального аккаунта StaticGram (777000) приходит сервисное сообщение о подарке статиков и текст «Вывод с бота @имя_бота в размере X ⭐️ успешно оформлен!». В истории статиков владельца появляется запись «Вывод с бота», у бота — списание «Вывод владельцу» (в getStarTransactions это транзакция с receiver.type = other).

Выводится весь баланс бота: стартовые статики ботам не начисляются, поэтому на балансе только то, что бот заработал. Минимальная сумма вывода задаётся сервером (по умолчанию 1 статик), как и лимит частоты: не больше N выводов одного бота в минуту (по умолчанию 10; повтор с тем же request_id не считается).

Вывод другому пользователю

Методом withdrawStarBalance бот может отправить статики не владельцу, а любому пользователю — передайте user_id. Получатель должен существовать, не быть удалённым, ботом, системным аккаунтом (777000 и т. п.) или замороженным. Все остальные правила те же: минимум, лимит частоты, запрет вывода администрацией, идемпотентность по request_id (тот же ключ с другим получателем — REQUEST_ID_CONFLICT).

Получатель видит сервисное сообщение о подарке статиков от 777000 и текст «Вывод от бота @имя_бота в размере X ⭐️ зачислен на ваш баланс.», в его истории статиков — запись «Вывод от бота» с именем бота. У бота в истории — «Вывод пользователю» с @username (или id) получателя. Владелец бота получает от 777000 уведомление «Вывод с бота @имя_бота в размере X ⭐️ пользователю @получатель успешно оформлен!». Как и вывод владельцу, такой вывод не влияет на рейтинг аккаунта получателя.

withdrawStarBalance

ПараметрТипОбязателенОписание
user_idInteger или StringнетПолучатель: id пользователя или @username. Не указан (или указан id владельца) — статики получает владелец бота.
star_countIntegerнетСколько статиков вывести. Не указан — выводится всё, что доступно.
request_idStringнетКлюч идемпотентности, 1–40 печатных ASCII-символов. Повторный вызов с тем же ключом вернёт первый результат и ничего не спишет; тот же ключ с другим star_count или user_id — ошибка REQUEST_ID_CONFLICT.

Возвращает StarTransaction списания с бота и дополнительные поля StaticGram: star_count (сколько выведено), remaining_balance (остаток бота), owner_user_id, recipient_user_id (кто получил статики; при выводе владельцу совпадает с owner_user_id).

Shell
curl "https://api.staticgram.top/bot$TOKEN/withdrawStarBalance" \
  -H "Content-Type: application/json" \
  -d '{"star_count": 500, "request_id": "payout-2026-10-01"}'
JSON
{"ok": true, "result": {"id": "1841", "amount": 500, "date": 1790000000,
  "receiver": {"type": "other"}, "star_count": 500, "remaining_balance": 1250,
  "owner_user_id": 1000123, "recipient_user_id": 1000123}}

Вывод другому пользователю:

Shell
curl "https://api.staticgram.top/bot$TOKEN/withdrawStarBalance" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1000456, "star_count": 200, "request_id": "prize-42"}'

Ошибки: BALANCE_TOO_LOW (нечего выводить или запрошено больше доступного), STAR_COUNT_TOO_SMALL (меньше минимума сервера), STAR_COUNT_INVALID, REQUEST_ID_INVALID, REQUEST_ID_CONFLICT, BOT_OWNER_UNAVAILABLE (аккаунт владельца удалён или заморожен), STAR_WITHDRAWAL_DISABLED (вывод для бота отключён администрацией), Too Many Requests: retry after N (превышен лимит частоты, 429 с parameters.retry_after). Для user_id: Bad Request: user not found (USER_ID_INVALID — неверный id, пользователь не найден, удалён или системный), Bad Request: USER_IS_BOT, Bad Request: USER_FROZEN.

Возврат и вывод используют один баланс бота: если вывести всё, refundStarPayment вернёт BALANCE_TOO_LOW. Повторный возврат одного платежа — CHARGE_ALREADY_REFUNDED.

Выплаты пользователям

Как и в Telegram, в Bot API нет метода «перевести статики пользователю». Отдать пользователю ценность за статики бота можно так:

  • sendGift: подарок оплачивается с баланса бота. Получатель может оставить его или обменять на статики (сумма обмена указана в подарке, convert_star_count).
  • giftPremiumSubscription: Premium за статики бота.
  • refundStarPayment: только возврат конкретного платежа.

Бизнес-боты дополнительно могут transferBusinessAccountStars: перевести статики с подключённого бизнес-аккаунта на баланс бота (не пользователю).

Игры за статики

Отдельных правил для игр нет, действуют общие правила оплаты статиками:

  • Вход в игру, попытки, внутриигровые покупки: обычный счёт в статиках. В HTML5-игре, открытой через sendGame, нет JS-моста для оплаты, поэтому платные игры лучше делать как Mini App с openInvoice, либо отправлять счёт sendInvoice в чат.
  • Выигрыш нельзя выплатить статиками напрямую (см. «Выплаты пользователям»): используйте подарки sendGift.
  • Рекорды: setGameScore и getGameHighScores, см. Игры.
Не поддерживается

Платёжные провайдеры и фиатные валюты: только статики (XTR) и коины (TON). Счета с доставкой (shipping_query никогда не приходит, answerShippingQuery отвечает QUERY_ID_INVALID). Счета через inline-результат (InputInvoiceMessageContent → 400 INVOICE_CONTENT_UNSUPPORTED).

Описания методов и типов взяты из официальной документации Telegram Bot API (Bot API 10.3). Адрес API: https://api.staticgram.top