Интеграция
Блокчейн — единственная сторона, которая не может потерять сообщение
TON API даёт Telegram-боту доступ на чтение состояния сети — балансов счетов, остатков жетонов и истории транзакций, — чтобы платежи и списки допуска сверялись с сетью, а не с тем, что сообщил клиент. Всё, что клиент говорит о транзакции, остаётся утверждением, пока с ним не согласится блокчейн.
TON API — интеграция: доступ, лимиты и доступность
- Модель авторизации
- Ключ API
- Лимит частоты
- На ключ API, на платных тарифах существенно выше
- Доступность в Заливе
- Подключаться в юрисдикции не нужно — чтение сети не регулируется
- Поток данных
- 5 переходов, через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
Любому криптопродукту в Telegram рано или поздно нужно одно и то же: достоверный ответ на вопрос, произошло ли что-то в сети. Пришёл ли этот платёж. Лежит ли на этом кошельке токен, которого требует список допуска. Подтвердился ли отправленный нами вывод. Ни на один из этих вопросов нельзя ответить, спросив кошелёк пользователя, потому что кошелёк — это программа под контролем пользователя, и её отчёт есть утверждение.
Соблазнительный короткий путь — выдавать товар по успешному ответу клиента. Кошелёк говорит, что отправил транзакцию, Mini App сообщает об этом бэкенду, бэкенд выдаёт покупку. На тестах работает, на честных пользователях работает, и за этим механизмом стоит большая доля потерь в криптопродуктах внутри Telegram. Клиент, который можно изменить, — это клиент, который сообщит о платеже, которого не было.
Поэтому рабочая схема — опрос и наблюдение вместо доверия. Бэкенд знает, чего он ждёт: сумму, адрес получателя, комментарий или метку, опознающую заказ, — и следит за сетью, пока не увидит это на достаточной глубине. Это медленнее доверия клиенту на несколько секунд и ровно на столько же отличает продукт от пожертвования.
Как на самом деле движутся данные
Ключ API хранится как секрет воркера и используется ради более высоких лимитов частоты. Ключ даёт доступ на чтение публичных данных блокчейна, а не полномочия двигать средства, поэтому его утечка — это проблема доступности сервиса, а не потеря денег; полезное различие, когда решаешь, насколько сильно тревожиться из-за ротации ключа.
Модель доступа: API-ключ
Их лимиты и что они означают для вас
Лимиты частоты действуют на ключ API, причём на платных тарифах разрешено существенно больше.
Опрос на каждого пользователя не масштабируется. Один наблюдатель на отслеживаемый адрес, общий для всех заказов, ждущих этот адрес, — вот что удерживает объём запросов пропорциональным числу счетов, а не числу клиентов.
Транзакция видна раньше, чем становится окончательной, а окончательность зависит от глубины подтверждений.
Глубину подтверждений задают под сумму, а не одной константой. Глубина, уместная для чаевых в два доллара, не годится для вывода в пять знаков.
Балансы жетонов лежат в отдельных жетон-контрактах каждого кошелька, а не на основном счёте.
Чтобы проверить баланс USDT, сначала нужно вычислить адрес жетон-кошелька этого владельца. Прочитать основной счёт и ничего там не найти — частый и сбивающий с толку первый результат.
Комментарий к транзакции — принятый способ приложить ссылку на заказ, и его редактирует сам отправитель.
Комментарий опознаёт платёж, но не подтверждает его подлинность. Для сверки нужны ещё сумма и адрес получателя, потому что комментарий может скопировать любой, кто смотрит на публичный блокчейн.
Как это ломается и что происходит потом
API недоступен, пока клиент ждёт подтверждения платежа.
Заказ остаётся в ожидании, и клиенту сообщают, что платёж всё ещё подтверждается, а не что он не прошёл. Наблюдение возобновляется, когда API вернётся, потому что транзакция лежит в блокчейне независимо от того, видели мы её или нет.
Платёж пришёл с неверным комментарием или вовсе без него.
Сумма и адрес получателя сужают выбор до небольшого набора, а всё неоднозначное уходит человеку. Автоматически зачислить неопознаваемый платёж ближайшему ожидающему заказу — способ отдать чужой товар не тому клиенту.
Реорганизация блоков отменяет транзакцию, которую уже сочли подтверждённой.
Глубина подтверждений существует именно ради этого, и её масштабируют по сумме. Выдача на глубине один быстра и изредка ошибочна в самую дорогую сторону.
Два заказа ждут одну и ту же сумму на один адрес в одно и то же время.
Под каждый заказ выдаётся уникальный комментарий или уникальный подадрес, чтобы сверка была однозначной. Опора на одну лишь сумму ломается ровно тогда, когда двое клиентов ведут себя одинаково, а это не редкость.
Доступность в ОАЭ и остальных странах Залива
Глобально
Публичный поставщик данных блокчейна, подключаться в юрисдикции не нужно. То, что вы на нём построите, при этом может регулироваться.
Объединённые Арабские Эмираты
Широко используется криптопроектами Дубая. Чтение состояния сети не регулируется; хранение или перевод средств пользователей — вопрос к VARA независимо от того, как именно вы читаете блокчейн.
Бесплатный тариф
Достаточен для разработки и небольших объёмов. Боевому наблюдению за загруженной витриной нужен платный тариф, и это отдельная строка сметы, а не мелочь напоследок.
Свой узел вместо сервиса
Собственный узел снимает зависимость и добавляет эксплуатационную нагрузку. На масштабе оправдан, на старте — почти никогда.
Когда эту интеграцию делать не нужно
- Вы выдаёте товар по успеху, о котором сообщил клиент. Тогда доступ к блокчейну вам не нужен — он понадобится вскоре после первой потери.
- В вашем продукте нет ничего, что происходит в блокчейне. Читать сеть, от которой ничего не зависит, — механика без назначения.
- Вам нужно подтверждение быстрее секунды. У окончательности в сети есть нижний предел, и никакой API его не убирает.
- Вы продаёте цифровые товары аудитории Telegram. Stars рассчитываются мгновенно и вовсе без участия блокчейна.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Наблюдение за блокчейном по расписанию и сверка подтверждений. |
| Cloudflare D1 | current | Ожидаемые платежи, состояние подтверждений и очередь спорных случаев. |
| Cloudflare KV | current | Курсоры последней виденной транзакции по каждому отслеживаемому счёту. |
| Zod | 4.4 | Проверка ответов API, которые внешние и версионируются независимо от нас. |
Вопросы, которые возникают при оценке
Почему нельзя просто поверить успешному ответу кошелька?
Потому что кошелёк — это программа под контролем пользователя, и его отчёт есть утверждение, а не доказательство. На тестах и с честными пользователями это работает, и за этим стоит большая доля потерь в криптопродуктах внутри Telegram. Блокчейн — единственная сторона, которую нельзя уговорить солгать.
Сколько подтверждений ждать перед выдачей товара?
Зависит от суммы, и ошибка — считать это одной глобальной константой. Глубина, разумная для мелких чаевых, неразумна для крупного вывода, потому что реорганизация на глубине один стоит ровно столько, сколько было на кону.
Почему баланс USDT не виден на адресе кошелька?
Балансы жетонов живут в отдельных жетон-контрактах каждого кошелька, а не на основном счёте, поэтому сначала нужно вычислить адрес жетон-кошелька для этого владельца. Прочитать основной счёт и ничего не найти — обычный первый результат, и это не ошибка.
Достаточно ли комментария к транзакции, чтобы опознать платёж?
Он опознаёт, но не подтверждает подлинность. Комментарии видны в публичном блокчейне и копируются, поэтому сверка использует ещё сумму и адрес получателя, а всё неоднозначное уходит человеку, а не ближайшему ожидающему заказу.
Что будет, если API недоступен, пока клиент платит?
Заказ остаётся в ожидании, и клиенту говорят, что платёж всё ещё подтверждается, — и это правда: транзакция лежит в блокчейне независимо от того, видим мы её сейчас или нет. Наблюдение возобновляется, когда API вернётся.
Масштабируется ли опрос на тысячи клиентов?
Да, потому что наблюдатели заводятся на отслеживаемый адрес, а не на клиента. Тысяча заказов, ждущих оплату на один адрес, — это один наблюдатель, и именно так объём запросов остаётся пропорционален числу счетов, а не трафику.
Что почитать дальше
Само подключение кошелька — отдельная тема, ею занимается интеграция с TON Connect.
У платежей в стейблкоине своя механика жетонов, её описывает интеграция USDT на TON.
Сверку взносов с состоянием блокчейна во время продажи описывает сборка бота для запуска токена.
Глубина подтверждений и обработка реорганизаций важнее всего в сборке криптокошелька.