Telegram Stars API: что умеет официальный Bot API и как продавать звёзды через API

Коротко для тех, кто пришёл за ответом: официальный Telegram Stars API умеет принимать Stars от пользователей и дарить на них Premium, но купить Stars за деньги программно нельзя. Ни одного метода для этого в Bot API нет, публичного API у Fragment тоже не существует. Поэтому магазины работают через поставщика: у него берут товар по оптовой цене, а бот или сайт только оформляет заказ.

Ниже — разбор по методам с параметрами из документации, минимальный флоу оплаты, схема продажи и чеклист, по которому стоит выбирать API поставщика.

Что официально умеет Bot API со звёздами

Всё перечисленное есть в справочнике core.telegram.org/bots/api — проверено 11 августа 2026.

Принять оплату. sendInvoice и createInvoiceLink выставляют счёт, где currency равен XTR — это код Telegram Stars. Пользователь платит из своего баланса, Stars приходят на баланс бота. Так монетизируют цифровые товары внутри Telegram: доступ к контенту, подписку на сервис, функции мини-приложения.

Вернуть платёж. refundStarPayment возвращает пользователю успешно оплаченные Stars.

Посмотреть историю. getStarTransactions отдаёт список операций по балансу бота.

Подарить Premium. giftPremiumSubscription оформляет подписку указанному пользователю. Параметры жёсткие, и это стоит запомнить:

Других значений метод не принимает — ни 1 месяца, ни произвольной суммы.

Отправить подарок. sendGift отправляет подарок пользователю или в канал, причём получатель не сможет обменять его на Stars. Рядом живут upgradeGift, transferGift, convertGiftToStars и getAvailableGifts.

Операции бизнес-аккаунта. getBusinessAccountStarBalance и transferBusinessAccountStars работают только с подключённым бизнес-аккаунтом и соответствующими правами — для обычного бота этот путь закрыт.

Как принять оплату звёздами в своём боте

Если вы продаёте цифровой товар внутри мессенджера, использовать Telegram Stars проще, чем подключать эквайринг: касса уже встроена в клиент, и платит пользователь в два тапа. Официальный раздел Telegram Bot Payments описывает флоу целиком; ниже — сжатая версия.

1. Счёт. Бот вызывает sendInvoice (или createInvoiceLink, если нужна ссылка) с currency: "XTR" и ценой в Stars. Никаких provider_token для звёздных счетов не нужно.
2. Подтверждение. Перед списанием прилетает pre_checkout_query — на него надо ответить в течение десяти секунд, иначе платёж отменится.
3. Факт оплаты. Приходит сообщение с successful_payment, где лежит идентификатор платежа. Именно его сохраняют в базу: по нему потом делается возврат.
4. Выдача. Дальше ваш код отдаёт клиенту то, что он купил.

Настройка оплаты через Telegram Stars занимает вечер, и это единственное место, где официальный Stars API пригодится по прямому назначению. Для продажи самих Stars за рубли он не подойдёт — почему, разбираем дальше.

Чего в Bot API нет

Разница между «принять Stars» и «купить Stars» ломает большинство планов, поэтому проговорю прямо.

Нет метода купить Stars за деньги. Ни за рубли, ни за USDT, ни за TON. Баланс бота наполняется единственным способом — платежами пользователей Telegram. Для магазина это замкнутый круг: чтобы продать товар, его сначала надо где-то взять, а взять программно негде.

Нет перевода произвольному пользователю. giftPremiumSubscription дарит подписку, sendGift отправляет подарок, но «отправь 500 Stars на этот username» в Bot API отсутствует.

Нет пополнения баланса бота через API. Ни один метод не принимает деньги на счёт бота.

Отсюда вывод: на официальном Bot API магазин не собирается. Он годится, чтобы принимать оплату у клиентов, но товара не даёт.

Почему «Fragment API» — не продукт Telegram

Fragment — площадка, где Telegram продаёт юзернеймы и номера, и через неё же покупают Stars и Premium. Публичного программного доступа у неё нет: ни ключей, ни описания методов, ни тестового контура. Проверял по актуальным источникам 11 августа 2026 — официальной документации не существует.

Всё, что выдаётся по запросу «fragment api», — сторонние сервисы. Кто-то держит свою инфраструктуру и продаёт доступ к ней под таким названием, кто-то оборачивает чужой кабинет. К мессенджеру эти проекты отношения не имеют, и договор у вас будет не с Telegram.

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

Как на самом деле устроена продажа звёзд

Рабочая схема простая:

1. Пополняете баланс у поставщика. Это предоплата за товар, обычно в USDT.
2. Клиент оформляет заказ у вас — в боте, на сайте, в мини-приложении. Оплату принимаете вы своими средствами: эквайринг, СБП, крипта.
3. Ваш код отправляет заказ в API звёзд Телеграм — username получателя и количество.
4. Поставщик выдаёт товар, вы получаете финальный статус вебхуком и показываете клиенту результат.

Выручка — разница между вашей розничной ценой и закупочной. Склада нет, товар цифровой, вся логистика сводится к одному HTTP-запросу:

POST /api/partner/v1/orders
{
  "type": "stars",
  "params": { "quantity": 500, "recipient": "@username" },
  "idempotency_key": "order-1024"
}

Ответ содержит номер заказа и статус, финальное состояние приходит вебхуком. Именно так устроен любой нормальный поставщик звёзд Телеграм — различия начинаются в деталях, и вот их стоит проверять.

Чеклист: как выбирать API поставщика

Смотрите не на цену в рекламе, а на механику. Семь пунктов, каждый из которых кому-то стоил денег.

Идемпотентность. Обязателен ключ идемпотентности в запросе на заказ. Без него повтор после таймаута создаёт второй заказ и второе списание — а таймауты в мобильных сетях случаются постоянно.

Проверка получателя до оплаты. Отдельный метод, который по username возвращает имя из профиля. Так клиент видит, кому уйдёт покупка, и опечатка в нике не превращается в подарок незнакомцу.

Вебхуки с подписью. Статус должен приходить событием, а тело — подписываться HMAC, чтобы подделку было видно на входе. Опрос в цикле вместо вебхуков — признак сырого сервиса.

Автовозврат при сбое. Не удалось выдать заказ — деньги возвращаются на баланс сами, без переписки с поддержкой.

Понятное поведение при нехватке средств. Правильный ответ — сразу отказать с внятным кодом. Неправильный — подвесить заказ в ожидании пополнения.

Опубликованные лимиты. Сколько запросов в минуту, какой максимум в одном заказе, какие сроки Premium. Если этого нет в документации, лимиты вы узнаете на проде под нагрузкой.

Открытая документация. Методы и коды ошибок видны до подключения. Когда справочник выдают «только после оплаты активации», оценить интеграцию заранее невозможно.

Отдельно про цену: сравнивайте не проценты в рекламе, а итоговую цифру за штуку и то, есть ли комиссии за заказ и за пополнение. Формулировки вида «скидка до 40%» обычно означают индивидуальный торг, а не тариф.

Что писать в боте самому

Если делаете бота для продажи звёзд, ваш код отвечает за четыре вещи: витрину с пакетами, приём оплаты, вызов API поставщика и показ статуса клиенту. Логика выдачи остаётся на стороне поставщика — свой скрипт зачисления писать не нужно, и готовые исходники с форумов для этого не понадобятся. Библиотеки для Telegram Bot есть подо все распространённые языки: aiogram и telebot на Python, Telegram.Bot для .NET, telegraf на Node.

Отдельный telegram-бот под это не обязателен: та же схема работает на сайте или в мини-приложении. Бот для продажи звёзд просто самый короткий путь — интерфейс уже есть, регистрация не нужна, оплату можно принимать привычными для аудитории способами.

Четыре ошибки, на которых теряют деньги

Собрал то, что чаще всего ломается у тех, кто делает первую интеграцию.

Считать цену на своей стороне. Справочные цифры в каталоге — ориентир, а не расчёт. Сумму заказа фиксирует ответ на создание заказа, и опираться нужно на неё, иначе при движении курса вы продадите себе в убыток.

Верить статусу «в процессе». Звёзды Telegram приходят получателю за минуты, но заказ не считается выполненным, пока не пришёл финальный статус. Показывать клиенту «готово» раньше — верный способ получить спор.

Не проверять подпись вебхука. Открытый эндпоинт без сверки HMAC — приглашение подделать статус «выполнено» и получить товар бесплатно.

Хранить один ключ на всё. Ключ с доступом к заказам лучше держать отдельно от тестового и ограничить по IP: утёкший ключ — это ваш баланс в чужих руках.

Проверять всё это удобно на кошках: соберите витрину с одним пакетом и прогоните полный цикл — счёт, оплата, заказ, вебхук. Звёзды Telegram при этом уйдут на ваш же тестовый аккаунт, а вся проверка обойдётся в стоимость одного пакета.

Наш API, если нужен поставщик

Мы отдаём звёзды Телеграм оптом и Premium по REST API: заказ до 50 000 штук, подписка на 3, 6 и 12 месяцев, доставка официальным переводом по username, обычно за пару минут. Есть всё из чеклиста выше — ключ идемпотентности, проверка получателя, вебхуки с подписью X-Signature, автовозврат, 120 запросов в минуту на ключ.

Документация и OpenAPI-спека открыты до подключения: посмотреть методы. Ключ выпускается в кабинете самостоятельно, первое пополнение — от 100 USDT.

Частые вопросы

Можно ли купить Stars через Bot API? Нет. Метода покупки за деньги не существует, баланс бота наполняется только платежами пользователей Telegram.

Есть ли официальный Fragment API? Нет. Публичной документации, ключей и песочницы не существует; сервисы с таким названием — сторонние.

Можно ли подарить Premium через API? Да, giftPremiumSubscription — но списывается со звёздного баланса бота: 1000 за 3 месяца, 1500 за 6, 2500 за 12.

Чем API поставщика отличается от botовского? Bot API принимает платежи внутри мессенджера, API поставщика даёт товар. Для магазина нужны оба звена: первое опционально, второе обязательно.

Нужен ли готовый скрипт магазина? Нет. Достаточно витрины и вызова API. Выдача, статусы и возвраты — на стороне поставщика.