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

Расширение StaticGram (в официальном Bot API его нет). Выводит Telegram Stars с баланса бота владельцу бота (как /bank в @BotFather) или любому пользователю по выбору разработчика (параметр user_id). Получателю приходит нативное зачисление звёзд от 777000 и сообщение «Вывод с бота @bot в размере X ⭐️ успешно оформлен!». On success, returns a StarTransaction object.

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

Метод StaticGram, в официальном Bot API его нет. Списание с бота и зачисление получателю проходят одной транзакцией. В ответе, кроме полей StarTransaction, есть star_count, remaining_balance, owner_user_id и recipient_user_id. Ошибки: BALANCE_TOO_LOW (на балансе меньше запрошенного), STAR_COUNT_TOO_SMALL (меньше минимума), STAR_COUNT_INVALID, REQUEST_ID_INVALID, REQUEST_ID_CONFLICT, BOT_OWNER_UNAVAILABLE (у бота нет владельца-пользователя), STAR_WITHDRAWAL_DISABLED (вывод отключён администрацией). Подробнее — раздел «Оплата» → «Вывод звёзд владельцу бота».

Параметры

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

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

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

Сколько звёзд вывести. Не передан — выводится весь баланс бота. Не меньше минимальной суммы вывода (по умолчанию 1).

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

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

Ошибки

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

Ошибка	Когда
`BALANCE_TOO_LOW`	на балансе бота меньше запрошенного
`STAR_COUNT_TOO_SMALL`	меньше минимальной суммы вывода
`STAR_COUNT_INVALID`	star_count не целое число или вне допустимого диапазона
`REQUEST_ID_INVALID`	request_id длиннее 40 символов или содержит не-ASCII
`REQUEST_ID_CONFLICT`	тот же request_id уже использован с другой суммой или другим получателем
`BOT_OWNER_UNAVAILABLE`	у бота нет владельца-пользователя
`STAR_WITHDRAWAL_DISABLED`	вывод отключён администрацией
`Bad Request: user not found`	получатель не найден, удалён или системный аккаунт
`Bad Request: USER_IS_BOT`	получатель — бот
`USER_FROZEN`	аккаунт получателя заморожен
`429 Too Many Requests: retry after N`	превышен лимит выводов в минуту

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

curl

curl "https://api.staticgram.top/bot$TOKEN/withdrawStarBalance"

aiogram 3

from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer

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

result = await bot.withdraw_star_balance()

JavaScript

const res = await fetch(`https://api.staticgram.top/bot${TOKEN}/withdrawStarBalance`);
const data = await res.json();

Ответ (StarTransaction)

JSON

{
  "ok": true,
  "result": {
    "id": "...",
    "amount": 1,
    "date": 1790000000
  }
}