`withdrawTonBalance`Поддерживается

Синоним метода withdrawGramBalance в StaticGram: тот же обработчик, параметры и ответ. Расширение StaticGram (в официальном Bot API его нет). Выводит GRAM с баланса бота владельцу бота или любому пользователю по выбору разработчика (параметр user_id) — GRAM-аналог withdrawStarBalance. Списание с бота и зачисление получателю проходят одной транзакцией; получатель видит пополнение баланса GRAM и сообщение от 777000 «Вывод с бота @bot в размере X GRAM успешно оформлен!». Синоним — withdrawTonBalance. On success, returns the withdrawal receipt.

Особенности StaticGram

Метод StaticGram. Ключ request_id привязан к боту (другие боты и @BotFather его не видят). Повтор с тем же ключом возвращает тот же чек и не учитывается в лимите 20 выводов в минуту. Если вывод звёзд для бота отключён администрацией, отключён и вывод GRAM. Вывод звёзд — withdrawStarBalance, баланс — getMyGramBalance.

Параметры

user_idInteger or Stringнеобязательный

Кому зачислить GRAM: ID пользователя или @username. Не передан (или равен ID владельца) — владельцу бота. Получатель должен существовать и не быть удалённым, замороженным, ботом или системным аккаунтом (777000 и т. п.).

nanoton_amountIntegerнеобязательный

Сколько вывести, в нанотонах (1 GRAM = 1000000000). Не передан — выводится весь баланс бота. Минимум 10000000 (0.01 GRAM), максимум 1000000000000000 (1 000 000 GRAM) за один вывод.

request_idStringнеобязательный

Ключ идемпотентности, 1–40 печатных ASCII-символов. Повторный вызов с тем же ключом не спишет GRAM второй раз и вернёт тот же чек; тот же ключ с другой суммой или другим получателем — REQUEST_ID_CONFLICT. Не передан — сервер создаёт случайный ключ (повтор запроса выведет ещё раз).

Что возвращает

Поле	Тип	Описание
`id`	String	ID транзакции списания с бота.
`currency`	String	Всегда "TON".
`amount`	Integer	Выведенная сумма в нанотонах.
`nanoton_amount`	Integer	То же, что amount.
`gram_amount`	String	Выведенная сумма в GRAM строкой: "1.5".
`date`	Integer	Unix-время вывода.
`receiver`	Object	{"type": "other"}, как у TransactionPartnerOther.
`remaining_balance`	Integer	Остаток на балансе бота в нанотонах после вывода.
`owner_user_id`	Integer	ID владельца бота.
`recipient_user_id`	Integer	ID пользователя, которому зачислены GRAM.

Ошибки

Ошибка приходит как {"ok": false, "error_code": 400, "description": "Bad Request: КОД: пояснение"}, если не указано иное.

Ошибка	Когда
`BALANCE_TOO_LOW`	на балансе бота меньше запрошенной суммы (или баланс пуст при выводе всего)
`AMOUNT_TOO_SMALL`	сумма меньше 0.01 GRAM (10000000 нанотонов)
`AMOUNT_INVALID`	nanoton_amount не целое число, меньше 1 или больше 1 000 000 GRAM
`REQUEST_ID_INVALID`	request_id длиннее 40 символов или содержит не-ASCII
`REQUEST_ID_CONFLICT`	тот же request_id уже использован с другой суммой или другим получателем
`BOT_OWNER_UNAVAILABLE`	у бота нет владельца-пользователя
`WITHDRAWAL_DISABLED`	вывод для бота отключён администрацией
`Bad Request: user not found`	user_id не найден, удалён, системный аккаунт или сам бот (USER_ID_INVALID)
`Bad Request: USER_IS_BOT`	получатель — бот
`USER_FROZEN`	аккаунт получателя заморожен
`429 Too Many Requests: retry after N`	больше 20 новых выводов за минуту на бота (повторы с тем же request_id не считаются)

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

curl

curl "https://api.staticgram.top/bot$TOKEN/withdrawTonBalance" \
  -H "Content-Type: application/json" \
  -d '{
    "nanoton_amount": 1500000000,
    "request_id": "payout-2026-10-09"
  }'

aiogram 3

from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
from aiogram.methods.base import TelegramMethod

# Метода StaticGram нет в aiogram: описываем его сами, bot(...) отправит запрос как обычно.
class WithdrawTonBalance(TelegramMethod[dict]):
    __returning__ = dict
    __api_method__ = "withdrawTonBalance"

    user_id: int | str | None = None      # не передан — владельцу бота
    nanoton_amount: int | None = None     # не передан — весь баланс
    request_id: str | None = None

session = AiohttpSession(api=TelegramAPIServer.from_base("https://api.staticgram.top"))
bot = Bot(TOKEN, session=session)

receipt = await bot(WithdrawTonBalance(
    user_id=123456789, nanoton_amount=1_500_000_000, request_id="payout-2026-10-09",
))
print(receipt["gram_amount"], receipt["remaining_balance"])

JavaScript

const res = await fetch(`https://api.staticgram.top/bot${TOKEN}/withdrawTonBalance`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    nanoton_amount: 1500000000, // 1.5 GRAM; без поля — весь баланс
    request_id: "payout-2026-10-09",
  }),
});
const { ok, result, description } = await res.json();

Ответ (Object)

JSON

{
  "ok": true,
  "result": {
    "id": "90211",
    "currency": "TON",
    "amount": 1500000000,
    "nanoton_amount": 1500000000,
    "gram_amount": "1.5",
    "date": 1790000000,
    "receiver": {
      "type": "other"
    },
    "remaining_balance": 500000000,
    "owner_user_id": 1780243200,
    "recipient_user_id": 1780243200
  }
}