gramdocs.tech
Документация

Вывод заработанных Stars в Gram: ограничения

Разделишь Stars-платежи и on-chain Gram, поймёшь ограничения вывода заработанных Stars через Fragment.

Stars и Gram — разные уровни

Оплата в боте идёт в Telegram Stars (XTR) через Bot Payments API. Gram (GRAM) — нативная монета сети TON. Это не одна операция «Stars-транзакция в Gram»: сначала пользователь платит Stars внутри Telegram, позже владелец бота/канала может вывести заработанные Stars в Gram через официальный маршрут (Fragment) — при выполнении условий платформы.

Статья не про курс и не про «выгоду конвертации». Ниже — технические и продуктовые ограничения, которые нужно закладывать в архитектуру.

Stars не привязаны к Gram фиксированным курсом. Telegram задаёт стоимость Stars и условия выплаты отдельно; не рассчитывай курс Stars→Gram в контракте или пользовательском балансе.

Что проверять в продукте

typescript
// Не API блокчейна — чеклист ограничений продукта (актуально на июль 2026).
// Условия вывода задаёт Telegram/Fragment и могут измениться — сверяй официальные источники перед релизом.

export type StarsBalanceKind = "earned" | "purchased";

export type WithdrawGate = {
  canWithdraw: boolean;
  reasons: string[];
};

/**
 * Грубая модель для внутренней аналитики/админки.
 * Сам вывод выполняется вручную владельцем через Fragment + кошелёк в сети TON,
 * не через произвольный вызов из твоего бота.
 */
export function evaluateWithdrawEligibility(input: {
  kind: StarsBalanceKind;
  earnedStarsAvailable: number; // Stars, прошедшие холд платформы
  totalEarnedStars: number;
  twoFactorEnabled: boolean;
  regionAllowed: boolean;
}): WithdrawGate {
  const reasons: string[] = [];

  if (input.kind !== "earned") {
    reasons.push("Купленные пользователем Stars вывести нельзя — только тратить внутри Telegram");
  }
  // Ориентир платформы: минимум для вывода заработанных Stars
  if (input.earnedStarsAvailable < 1000) {
    reasons.push("Не достигнут минимальный порог вывода (ориентир: 1000 Stars)");
  }
  // Ориентир платформы: холд ~21 день с момента получения партии Stars
  if (input.earnedStarsAvailable < input.totalEarnedStars) {
    reasons.push("Часть Stars ещё на холде (ориентир: 21 день с даты начисления)");
  }
  if (!input.twoFactorEnabled) {
    reasons.push("Для вывода нужна 2FA на аккаунте Telegram");
  }
  if (!input.regionAllowed) {
    reasons.push("Fragment или кошелёк в сети TON могут быть недоступны в регионе");
  }

  return { canWithdraw: reasons.length === 0, reasons };
}

/** Разделение потоков в коде бота — чтобы не смешивать ledger'ы */
export const ledgers = {
  starsPayments: "telegram-bot-payments-xtr", // successful_payment, refundStarPayment
  tonOnchain: "ton-blockchain", // TON Connect, jetton transfer, газ в Gram
} as const;

Практический путь владельца бота (вне твоего backend API):

  1. Накапливаешь earned Stars с продаж цифровых товаров.
  2. В интерфейсе баланса бота/Fragment дожидаешься порога и холда.
  3. Выводишь Gram на подключённый кошелёк в сети TON через Fragment.
  4. Дальше Gram — уже on-chain: перевод, DEX, вывод на биржу — отдельный стек.

Как это работает

  • Пользователь → бот: только Stars (XTR), не «перевод Gram на адрес контракта».
  • Бот → разработчик: баланс Stars у владельца бота; вывод в Gram — выплата награды/заработка, не часть successful_payment.
  • Купленные Stars (пользователь пополнил баланс для трат) не выводятся.
  • Заработанные Stars (пришли от покупателей) — кандидаты на вывод при пороге, холде, 2FA и доступности Fragment в регионе.
  • У Stars нет фиксированного курса к Gram; не хардкодь курс в контракте и не обещай пользователям доходность.
  • Комиссии app store при покупке Stars пользователем и условия вывода для разработчика — разные вещи; не путай их в FAQ продукта.

Частые ошибки

Пишешь в UI «оплати 1 GRAM» для digital goods внутри Telegram → для цифровых товаров в боте/Mini App платформа требует Stars. Иначе рискуешь нарушением правил store / Terms Telegram.

Ждёшь Stars на адресе кошелька в сети TON после successful_payment → в update приходит платёж Stars, не on-chain transfer. On-chain баланс не изменится.

Строишь автоматический «вывод всем пользователям в Gram» из купленных Stars → такого Bot API-метода нет; вывод — для заработанных Stars владельца, через Fragment, с ограничениями платформы.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация