Fragment API: звёзды, Premium, GRAM и Steam 1:1 в 2026

Собрать Telegram-бота с витриной звёзд несложно. Трудности начинаются позже: заказ пришёл в три часа ночи, и выдать его нужно без человека у экрана, без опечатки в нике и без двойного списания. В этот момент разработчики и начинают искать fragment api.

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

Ниже сравниваем три способа по главному для бизнеса признаку: что приходится хранить у себя и кто разбирает сбой. Затем подробно разбираем партнёрское API KRAB.GG: товары, цену, надёжность, подключение и ошибки интеграции. Сразу оговоримся: наше API — не Fragment API. Мы не представляем ни Fragment, ни Telegram. Для нас Fragment — площадка Telegram и основа цены.

Коротко о программной покупке Stars

• У Fragment нет официального публичного API. Библиотеки на GitHub и PyPI сами называют себя неофициальными.
• Библиотеке нужны ваши секреты: cookies аккаунта Fragment или seed-фраза кошелька и GRAM на нём. Сбои тоже разбираете вы.
• У API поставщика вы храните только ключ. Заказы оплачиваются с единого USDT-баланса. Stars, Premium и GRAM стоят по оптовой цене Fragment плюс 1%, Steam зачисляется 1:1 без комиссии.
• Надёжность можно проверить до первого платежа: песочница без списаний, идемпотентность по orderId, подписанные вебхуки.
• Условия в статье действуют на сентябрь 2026 года. Актуальная редакция всегда в условиях работы по API.

Что называют Fragment API и есть ли он официально

Fragment API — собирательное название неофициальных библиотек и скриптов, которые повторяют действия пользователя на fragment.com: покупку Stars и Premium, пополнение рекламы в GRAM. Публичной документации API для таких покупок Fragment не публикует, и авторы библиотек пишут об этом прямо.

• Автор Python-библиотеки Ton-Fragment на GitHub объясняет в README, что пытался получать данные с Fragment.com и не нашёл официального API.
• Клиент fragment-api-py в описании называет себя неофициальным: non-official python client for Fragment API.
• В подборке репозиториев fragment-stars видно несколько проектов, и требования к аккаунту и кошельку у каждого свои.

Официальные способы получить звёзды Telegram описывает в документации для ботов о платежах в Stars на core.telegram.org. Там пользователи покупают звёзды через встроенные покупки Apple и Google или через @PremiumBot. Отдельного API Fragment для перепродавцов там нет.

Запрос «fragment telegram api» иногда путают с Bot API. В Bot API действительно есть метод giftPremiumSubscription: бот дарит пользователю Premium и расплачивается собственными Stars. Купить сами звёзды по цене Fragment этим методом нельзя, поэтому задачу оптовой выдачи он не решает.

Практический вывод: любой «Fragment API» работает поверх интерфейса сайта, а не по публичному контракту. Обязательств перед интеграторами у площадки нет. Если поменялась страница, авторизация или формат запроса, обёртка перестаёт работать, пока автор её не обновит.

Три способа покупать Stars программно

Купить Telegram Stars программно можно через открытую библиотеку, собственный скрипт или API поставщика. Кто ищет «telegram stars api» или «api для покупки тг звёзд», выбирает как раз между этими вариантами. Различаются они не скоростью первого запуска, а тем, что хранится на вашем сервере и кто отвечает за зависший заказ.

Для магазина цифровых товаров выбор часто решает последняя строка. Steam на Fragment не продаётся, поэтому обёртки Fragment этот товар не закроют.

Что требуют открытые библиотеки

По запросу «fragment api stars» выдача почти целиком состоит из репозиториев GitHub и PyPI. README fragment-api-py описывает два режима работы:

• с верифицированным аккаунтом Fragment: библиотеке нужны cookies аккаунта и кошелёк, а cookies предлагается хранить в файлах или Redis;
• без верификации, через API стороннего сервиса: нужны токен этого сервиса, seed-фраза кошелька из 12, 18 или 24 слов и ключ API провайдера блокчейна.

В обоих режимах на вашем сервере лежат секреты с доступом к деньгам, а заказы оплачиваются GRAM с вашего кошелька. Пополнять кошелёк, следить за остатком и сверять транзакции тоже придётся вам.

Отдельный класс — пакеты, которые выглядят как библиотека, а на деле работают тонким SDK к чужому серверу. Вы передаёте туда мнемонику кошелька, и сервер покупает от вашего имени. В одном из README прямо предлагают закодировать всю фразу в Base64 перед отправкой. Формально это пакет на PyPI, по сути — посредник с полным доступом к вашему кошельку.

Ещё одна деталь 2026 года: в июне Toncoin переименовали в GRAM, а сеть осталась прежней — The Open Network. Часть обёрток уже перешла на новое название: в README fragment-api-py значится «GRAM Ads top-up». В старых версиях и примерах ещё встречаются TON и ton в параметрах. Проверьте, какую версию подключаете, и заложите время на обновление зависимости после каждого релиза.

Почему свой скрипт ломается первым

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

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

Как устроено партнёрское API KRAB.GG

Партнёрское API KRAB.GG — REST-API с базой https://api.krab.gg/v1. Бот, магазин или CRM создаёт заказ одним запросом, а товар приходит указанному получателю. Ключ передаётся в заголовке Authorization: Bearer sk_live_…. Пароль, код входа и доступ к аккаунту получателя не нужны ни для одного товара. Stars и Premium приходят через встроенный механизм оплаты Telegram — тем же официальным потоком, что и при покупке внутри приложения.

Так на практике выглядит пополнение тг звёзд по API, и в той же интеграции доступны ещё шесть типов цифровых товаров.

Какие товары и получатели доступны

Если вы ищете API для продажи Telegram Premium, обратите внимание на поле qty: у Premium оно означает срок, а не количество.

• stars — Telegram Stars, от 50 до 10 000 000 за заказ. Получатель — @username.
• premium — Telegram Premium на 3, 6 или 12 месяцев, qty — срок в месяцах. Тарифа на месяц нет. Получатель — @username.
• gram — GRAM на баланс Telegram-аккаунта. Получатель — @username, адрес внешнего кошелька не подходит.
• steam — пополнение баланса Steam в долларах. Получатель — логин аккаунта Steam без @.
• stars_giveaway — розыгрыш Stars в канале. qty — весь пул звёзд из фиксированных пакетов Fragment (от 500 до 1 000 000), winners — не больше qty ÷ 100. Получатель — @handle канала.
• premium_giveaway — розыгрыш Premium в канале. qty — срок каждой подписки (3, 6 или 12 месяцев), winners — число подписок, до 24 000. Получатель — @handle канала.
• ads_recharge — пополнение рекламного кабинета Telegram Ads, qty — целые GRAM. Получатель — токен из ссылки «Add Funds on Fragment» вида fragment.com/ads/pay?account=…, ссылку можно прислать целиком.

У розыгрышей есть нюанс, который лучше объяснить клиенту заранее. После оплаты розыгрыш появляется у админов канала в разделе «Бусты» (Статистика → Бусты). Дату итогов и условия участия назначает сам админ, а победителей выбирает и награждает Telegram. Личный аккаунт или бот в качестве получателя не подходят.

Telegram-подарки через API не выдаются: POST /v1/orders отбивает такой заказ ошибкой, подарки остаются только на сайте и в боте. Пределы суммы для steam, gram и ads_recharge меняются, поэтому в код их не зашивают. При выходе за границу API отвечает min_quantity или max_quantity.

Эндпоинты и тело заказа

• POST /v1/orders — создать заказ и сразу выдать;
• GET /v1/orders/{id} — статус заказа;
• GET /v1/price — расчёт цены без списания;
• GET /v1/check — проверка, примет ли получатель товар;
• GET /v1/balance — остаток на балансе;
• GET /v1/deposit — реквизиты пополнения;
• GET и POST /v1/webhook — настройки вебхука.

Тело заказа состоит из четырёх полей: type, qty, username и orderId, плюс необязательный dryRun. У розыгрышей обязательно пятое поле winners, у остальных товаров оно запрещено. Минимальный заказ — POST /v1/orders с телом {"type":"stars","qty":100,"username":"@johnsmith","orderId":"order-123"}.

Полные примеры запросов и ответов собраны в документации партнёрского API. Параметры и коды ответов каждого метода — в справочнике эндпоинтов.

Пополнение Steam по API: 1:1 в долларах

API пополнения Steam зачисляет ровно заказанную сумму: заказали $10 — на баланс Steam пришло $10, с баланса партнёра списано 10 USDT. Комиссии на тип steam нет, скрытых наценок тоже. Деньги зачисляются в валюте аккаунта по официальному курсу Steam.

• Получатель — логин аккаунта Steam без @. Пароль и код входа не нужны.
• Регионы — подходят аккаунты всех регионов СНГ.
• Скорость — выдача асинхронная, в среднем заказ выполняется около 4 секунд. Итог приходит вебхуком или в GET /v1/orders/{id}, поэтому processing в ответе на POST — нормальное состояние, а не ошибка.
• Пределы суммы API отдаёт через min_quantity и max_quantity. В коде их не фиксируйте.

Для магазина цифровых товаров это значит, что Steam и Telegram-товары живут на одном балансе и в одной логике статусов. Второй поставщик, второй баланс и вторая схема сверки не нужны. Себестоимость пополнения равна его сумме, так что наценку на Steam посчитать проще, чем на любой другой товар.

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

Сколько стоит: оптовая цена Fragment + 1%

Stars, Premium и GRAM в партнёрском API стоят по оптовой цене Fragment плюс 1% комиссии. Пополнение Steam идёт без комиссии. Цену розыгрышей и пополнения Telegram Ads отдаёт только GET /v1/price. Если вы ищете поставщика звёзд Telegram оптом с API, формула такая: база — цена площадки, сверху процент, дальше ваша наценка.

• Единый баланс в USDT на все товары, отдельный GRAM-кошелёк не нужен.
• Точную цену заказа отдаёт GET /v1/price, расчёт идёт без списания. Оптовая цена Fragment плавает, поэтому цифры из статей и кэш суточной давности для витрины не годятся.
• Наценку ставите сами, ограничений сверху нет.
• Пополнение — USDT в сети TON на адрес с обязательным memo из GET /v1/deposit. Минимум 100 USDT, зачисление обычно в течение минуты. Без memo деньги не зачислятся.
• Возврат остатка: неиспользованный баланс возвращается по письму на hello@krab.gg в срок до 10 рабочих дней (оферта, редакция 2.2 от 28.09.2026).
• Индивидуальные условия на объём обсуждаются через поддержку @heIIo_stars.

Пример расчёта

Цифры ниже условные и показывают только формулу. Допустим, оптовая цена Fragment за пакет звёзд — 20,00 USDT. С комиссией 1% заказ обойдётся в 20,20 USDT. Если клиент платит вам сумму, эквивалентную 23 USDT, валовая разница составит 2,80 USDT. Из неё ещё предстоит вычесть расходы на приём платежей, налоги и поддержку. Со Steam арифметика проще: пополнение на $10 стоит вам 10 USDT, всё сверху — ваша наценка.

В реальной интеграции итоговую цену заказа не считайте сами, а берите из GET /v1/price. Эти запросы расходуют тот же лимит 60 запросов в минуту, что и заказы. Если витрина показывает цену каждому посетителю, кэшируйте ответ на короткий срок и запрашивайте свежую цену перед оформлением. Так вы не упрётесь в 429 в пиковый час.

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

Надёжность: как не выдать дважды и не потерять заказ

Надёжность партнёрского API держится на пяти механизмах: идемпотентности по orderId, проверке получателя через GET /v1/check, явных статусах с полем settlement, подписанных вебхуках и заголовке X-Request-Id для разбора.

Идемпотентность по orderId

orderId — ваш идентификатор заказа длиной до 128 символов из набора A-Za-z0-9._:-. Повтор запроса с тем же orderId возвращает уже созданный заказ и не списывает деньги второй раз. Таймаут, обрыв сети или падение воркера решаются простым повтором того же запроса.

Если отправить тот же orderId с другим type, qty или username, API вернёт 409 order_id_conflict. Это защита от бага, при котором один идентификатор случайно достался другому товару или получателю. Удобнее всего собирать orderId из номера заказа в вашей базе, например shop:48213, а не генерировать его случайно при каждой попытке.

Библиотеки Fragment такой защиты не дают. В README одной из популярных обёрток прямо сказано: нельзя вслепую повторять запрос, если транзакция уже могла быть подписана или отправлена.

Проверка получателя и нормализация ника

Прежде чем брать деньги с клиента, вызовите GET /v1/check: он ответит, примет ли получатель товар. До этого приведите ввод клиента к единому виду, чтобы поймать ошибки формата ещё до запроса:

1. Обрежьте пробелы и невидимые символы по краям.
2. Если клиент прислал ссылку вида t.me/имя или https://t.me/имя, оставьте только имя.
3. Уберите все @ в начале и поставьте ровно один.
4. Для Steam сделайте наоборот: логин без @. Нужен именно логин, а не ник профиля.
5. Для ads_recharge ник не нужен: принимайте токен из ссылки «Add Funds on Fragment» или ссылку целиком.
6. Только после этого вызывайте GET /v1/check и показывайте клиенту результат до оплаты.

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

Статусы и settlement

У заказа пять статусов: completed, processing, failed, refunded и cancelled. Stars, Premium и GRAM обычно выдаются синхронно за несколько секунд и приходят со status: completed в том же ответе. Steam выдаётся асинхронно. Для розыгрышей и ads_recharge срок выдачи не фиксирован, итог определяет статус или вебхук.

При failed в ответе есть reason и retryable. Если retryable: true, деньги уже вернулись на баланс и повтор с новым orderId оправдан. Если выдача не подтверждена, заказ получает settlement: fail_hold. При under_review средства удержаны и идёт ручная сверка. В обоих случаях дубль создавать нельзя.

Вебхуки, лимиты и X-Request-Id

• Вебхуки order.completed, order.failed и order.updated несут settlement и растущий sequence. Применяйте событие, только если его sequence больше сохранённого. Так запоздавший order.updated не перезапишет финальный статус.
• Подпись HMAC-SHA256 приходит в заголовке X-Webhook-Signature, и проверять её обязательно. Без проверки поддельный order.completed сможет прислать любой, кто узнал адрес. Порядок проверки описан в документации.
• X-Request-Id из ответа записывайте в лог рядом с orderId: по нему поддержка найдёт конкретный запрос.
• Лимит — 60 запросов в минуту на весь аккаунт, общий для боевого и тестового ключей. При превышении приходит 429 с заголовком Retry-After: ждите указанное время, а не повторяйте сразу.
• Ключ показывается один раз, в базе хранится только его хэш, отзыв срабатывает мгновенно. Если ключ утёк, отзовите его и выпустите новый.

Как подключить партнёрское API

Подключение идёт в пять шагов. Первые два не требуют ни денег, ни одобрения заявки.

1. Выпустите тестовый ключ. sk_test_ выдаётся сразу в бот-кабинете @apistarsbot. Ключ показывается один раз, поэтому сохраните его в секретах сервера, а не в коде.
2. Пройдите сценарий в песочнице: GET /v1/price → GET /v1/check → POST /v1/orders → GET /v1/orders/{id} → приём вебхука с проверкой подписи. Отдельно проверьте повтор с тем же orderId и ответ 409 при подмене qty. Тестовые запросы тратят тот же лимит 60 в минуту, что и боевые, так что нагрузочные тесты не запускайте в часы продаж.
3. Пополните баланс. Возьмите адрес и memo из GET /v1/deposit и отправьте USDT в сети TON, минимум 100 USDT. Зачисление проверьте через GET /v1/balance.
4. Подайте заявку на боевой ключ. sk_live_ выдаётся после одобрения заявки. Индивидуальные условия на объём можно обсудить с поддержкой.
5. Сделайте первый заказ на себя. Закажите минимальный пакет Stars (50) на собственный @username. Сверьте списание в GET /v1/balance, статус в ответе и пришедший вебхук. Только после этого открывайте выдачу клиентам.

Ошибки интеграции и как их избежать

Большинство проблем при интеграции — не сбои API, а ошибки в теле запроса и в обработке ответа. Ниже собраны частые промахи и их последствия.

Ошибки в теле запроса

• Новый orderId на каждую попытку. Повтор после таймаута превращается во второй заказ и второе списание. Решение — брать orderId из номера заказа в базе.
• Чужие имена полей и лишний префикс пути. API принимает только type, qty, username, orderId, dryRun и winners у розыгрышей, а путь начинается с /v1. Заказ с другими полями не пройдёт.
• qty у Premium как количество. qty: 3 означает три месяца, а не три подписки. Число подписок в розыгрыше Premium задаёт winners.
• winners не там, где нужно. У розыгрышей поле обязательно, а у розыгрыша Stars оно не может быть больше qty ÷ 100. У остальных товаров поле запрещено.
• Розыгрыш на личный аккаунт или бота. Получателем может быть только @handle канала.
• Ник вместо токена для Telegram Ads. Кабинет пополняется по токену из ссылки «Add Funds on Fragment», а не по @username или числовому id.
• Логин Steam с @ или ник профиля вместо логина. Деньги уйдут не туда, или заказ не пройдёт проверку.
• Подарки через API. Такой заказ POST /v1/orders отбивает ошибкой.

Ошибки в обработке ответа

• Зашитые в код цены и пределы. Цену берите из GET /v1/price, пределы — из min_quantity и max_quantity.
• Ожидание синхронного ответа от Steam, розыгрышей и Ads. processing — не ошибка. Итог придёт вебхуком или в GET /v1/orders/{id}.
• Дубль при fail_hold или under_review. Новый заказ в этот момент грозит двойной выдачей. Дождитесь итога и повторяйте только при retryable: true.
• Непроверенная подпись вебхука. Поддельное событие отметит заказ выполненным, хотя клиент ничего не получил.
• Игнор sequence. Старое событие перезапишет свежий статус.
• Повтор сразу после 429. Счётчик общий на аккаунт, поэтому шквал повторов держит в лимите и боевые заказы. Ждите столько, сколько указано в Retry-After.
• Ключ во фронтенде или в репозитории. Отзовите его в бот-кабинете и выпустите новый, отзыв срабатывает мгновенно.

Если остаётесь на библиотеке

Часть ошибок характерна именно для обёрток Fragment, и авторы сами описывают их в README. Это ник без @ и повтор после транзакции с неопределённым статусом. Сюда же относятся seed-фраза или cookies во фронтенде и почасовые лимиты режима без верификации. Выдача встаёт и тогда, когда Fragment просит дополнительно подтвердить аккаунт. Под эти случаи заранее заложите ручной разбор и дежурство.

Библиотека или поставщик звёзд Telegram: что выбрать

Библиотеки хватит, если у вас свой аккаунт Fragment с пройденной проверкой, кошелёк с GRAM и небольшой объём заказов. Товаров при этом только два — Stars и Premium, а сбои и обновления зависимости вы готовы разбирать сами. Для небольшого проекта на старте это честный вариант.

API поставщика оправдан в таких случаях:

• бот или магазин продаёт Stars, Premium и GRAM, а держать seed-фразу и cookies на сервере вы не хотите;
• магазину цифровых товаров нужен Steam в той же интеграции и на том же балансе;
• агентство или админ продаёт клиентам розыгрыши в каналах и пополнение Telegram Ads;
• CRM или сервису нужны статусы, подписанные вебхуки и единый USDT-баланс вместо GRAM-кошелька;
• заказы идут ночью и в выходные, и при ручной выдаче появляются задержки и опечатки в никах.

Если программиста в команде нет, в @apistarsbot есть готовый бот-франшиза: оплату принимает и товар выдаёт платформа, а цены ставите вы. Практику продавца — свой бот, автовыдачу, работу с площадками — мы разбирали в отдельной статье блога про бота для продажи звёзд.

Если программист есть, начните с тестового ключа. Выпустите sk_test_, пройдите сценарий из документации в песочнице и решайте по результатам тестов, а не по обещаниям. Песочница партнёрского API KRAB.GG доступна до первого пополнения, поэтому контракт можно проверить ещё до того, как вы вложите деньги.