TON API и TON Connect: как подключить кошелек к Mini App

Быстрый ответ: TON Connect отвечает за аутентификацию и подпись транзакций на стороне пользователя через манифест приложения и протокол связи с кошельком. TON API — это интерфейс для взаимодействия с блокчейном TON, который вы используете на бэкенде или фронтенде для чтения балансов, парсинга Jetton-токенов, отслеживания NFT и отправки подготовленных транзакций в сеть. TON Connect подключает пользователя и запрашивает согласие, а TON API обрабатывает данные блокчейна, проверяет результаты и отслеживает состояние смарт-контрактов.

---

Разработка Web3-сервисов, Mini Apps и NFT-механик в Telegram требует не только технической точности, но и понимания рынка. Если вы ищете готовые идеи, примеры пользовательского опыта или площадки для продвижения своего Web3-продукта, изучите каталог NFT-чатов на CommyX. В нем собраны тематические Telegram-сообщества, где можно найти Web3-разработчиков, обсудить интеграции TON API и провести первые посевы приложения. Также найти целевую аудиторию и профильные группы помогает раздел все чаты с тегом NFT.

Архитектура взаимодействия: где кончается Connect и начинается API

Разработчики Telegram Mini Apps часто путают роли этих двух инструментов. TON Connect не читает историю транзакций и не проверяет баланс счета. Его задача — установить безопасно подтвержденную связь между Mini App и кошельком пользователя (Tonkeeper, Telegram Wallet, MyTonWallet, OpenMask).

В свою очередь, TON API не умеет запрашивать подпись пользователя. Это уровень инфраструктуры блокчейна, предоставляющий доступ к индексированным данным сети, состоянию смарт-контрактов и отправке сырых транзакций (boc).

Связка работает следующим образом:

• Пользователь взаимодействует с интерфейсом Mini App.
• Mini App отправляет запрос в кошелек через TON Connect для получения подписи или подключения.
• Кошелек подписывает данные и отправляет готовую транзакцию в сеть TON.
• Mini App или его бэкенд обращается к TON API, чтобы прочитать обновленное состояние сети, проверить баланс или подтвердить факт проведения платежа.

Главный архитектурный сбой: подделка ton_proof

Главная точка отказа в большинстве Mini Apps — отсутствие бэкенд-проверки криптографического доказательства владения кошельком (ton_proof).

Клиентская часть приложения может запросить авторизацию через TON Connect, но верить данным, полученным прямо с фронтенда, нельзя. Злоумышленник может подменить адрес кошелька в ответе клиентского SDK и выдать себя за владельца любого публичного адреса (например, крупного держателя NFT или администратора).

Чтобы гарантировать, что пользователь действительно владеет указанным публичным ключом, бэкенд должен генерировать одноразовый маркер (nonce) с коротким временем жизни и валидировать подпись через криптографические библиотеки или TON API до выдачи JWT-токена доступа.

Пошаговый алгоритм авторизации пользователя (Session Lifecycle)

Для полного понимания того, как выстроить безопасную работу с кошельком, рассмотрим жизненный цикл сессии пользователя от открытия Mini App до подтверждения действий на сервере:

1. Запрос одноразового токена (Nonce/Payload): Front-end обращается к вашему бэкенду и запрашивает уникальную строку (nonce) с ограниченным временем жизни (например, 5 минут).
2. Инициализация TON Connect: Front-end передает полученный nonce в параметры запроса ton_proof при вызове окна подключения кошелька.
3. Подпись в кошельке: Пользователь подтверждает подключение в приложении кошелька (Tonkeeper, Telegram Wallet). Кошелек подписывает ваш nonce приватным ключом пользователя и возвращает объект ton_proof.
4. Передача данных на бэкенд: Front-end отправляет полученную подпись, публичный ключ и адрес кошелька на ваш бэкенд-сервер.
5. Серверная верификация: Бэкенд проверяет подпись с помощью Ed25519 криптографии и проверяет через TON API, соответствует ли публичный ключ указанному адресу.
6. Выдача авторизации: После успешной проверки бэкенд выдает пользователю авторизационную сессию (Session Cookie или JWT).

Сравнение ключевых методов: TON Connect vs TON API

Для проектирования системы важно чётко разделить ответственность между клиентом и сервером.

Сценарий использования	Инструмент	Выполняющая сторона	Описание процесса
Подключение кошелька	TON Connect	Фронтенд (Mini App)	Запрос сессии, чтение манифеста, получение публичного адреса
Проверка владения (Proof)	TON Connect + API	Бэкенд приложения	Генерация payload, проверка Ed25519 подписи через TON API или SDK
Запрос на оплату	TON Connect	Фронтенд / Кошелек	Передача SendTransactionRequest в кошелек для подписи пользователем
Проверка баланса Jetton/NFT	TON API	Бэкенд / Фронтенд	Вызов методов /v2/accounts/{account_id}/jettons без участия кошелька
Мониторинг оплаты	TON API / Webhooks	Бэкенд	Отслеживание хэша транзакции в блокчейне через индексатор
Эмуляция транзакций	TON API	Бэкенд / Фронтенд	Расчет комиссии и проверка успеха выполнения до отправки пользователю

Настройка манифеста и подключение через TON Connect

Каждый Mini App обязан отдавать публичный JSON-файл манифеста. Кошелек запрашивает этот файл, чтобы показать пользователю иконку, название и домен приложения при подписи операций.

Пример tonconnect-manifest.json:

JSON

{
  "url": "https://your-miniapp.com",
  "name": "My Telegram Store",
  "iconUrl": "https://your-miniapp.com/icon.png",
  "termsOfServiceUrl": "https://your-miniapp.com/terms.txt",
  "privacyPolicyUrl": "https://your-miniapp.com/privacy.txt"
}

Согласно официальной документации TON Connect:

Манифест должен размещаться по строго доступному SSL-адресу, а указанный в нем URL обязан полностью совпадать с доменным именем, где запущен Mini App, иначе кошелек отклонит подключение из соображений безопасности.

TON Connect

Инициализация SDK на фронтенде

Для работы с кошельком в Telegram Mini App используется библиотека @tonconnect/ui.

JavaScript

import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://your-miniapp.com/tonconnect-manifest.json',
  buttonRootId: 'ton-connect-button'
});

// Запрос криптографического доказательства (ton_proof)
tonConnectUI.setConnectRequestParameters({
  state: 'ready',
  value: { tonProof: 'SERVER_GENERATED_NONCE' }
});

Отправка транзакций, Jetton-токенов и NFT

Для проведения транзакции Mini App формирует структуру SendTransactionRequest и отправляет её в TON Connect. Кошелек открывает всплывающее окно для пользователя.

Отправка TON

JavaScript

const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 600, // 10 минут
  messages: [
    {
      address: "EQD...destination_address...",
      amount: "100000000", // 0.1 TON в nanoTON
    }
  ]
};

try {
  const result = await tonConnectUI.sendTransaction(transaction);
  // result.boc содержит подписанный Cell в формате Base64
} catch (e) {
  console.error("Пользователь отклонил транзакцию или вышел таймаут", e);
}

Перевод Jetton (USDT и других токенов)

При работе с Jetton вы отправляете транзакцию не напрямую получателю, а на адрес кошелька Jetton-мастера самого пользователя. Внутри сообщения передается Payload с инструкцией transfer.

Для сборки Payload рекомендуется использовать TON SDK для разработчиков (@ton/ton или @ton/core).

TypeScript

import { beginCell, Address } from '@ton/core';

// Формирование Payload для перевода Jetton
const jettonTransferBody = beginCell()
  .storeUint(0x0f888001, 32) // op::transfer
  .storeUint(0, 64)          // query_id
  .storeCoins(1000000)       // Количество токенов (с учетом decimals)
  .storeAddress(Address.parse("EQD...destination..."))
  .storeAddress(Address.parse("EQD...response_destination..."))
  .storeBit(0)               // custom_payload (null)
  .storeCoins(1)             // forward_ton_amount (1 nanoTON)
  .storeBit(0)               // forward_payload (null)
  .endCell();

const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 600,
  messages: [
    {
      address: "EQB...user_jetton_wallet_address...", // Jetton-кошелек отправителя
      amount: "50000000", // Commission TON на газ (0.05 TON)
      payload: jettonTransferBody.toBoc().toString('base64')
    }
  ]
};

Использование TON API на бэкенде: проверка и вебхуки

После того как TON Connect вернул успешный boc (Bag of Cells), клиентская часть не должна считать сделку завершенной. Сообщение могло не дойти до валидаторов или остаться в мемпуле.

Бэкенд должен проверить факт исполнения транзакции через публичный провайдер TON API (например, TonAPI.io, TON Center или собственный индексатор).

Выбор провайдера TON API

1. TonAPI.io — предоставляет удобный REST API и WebSocket-потоки для отслеживания событий по адресам.
2. TON Center — стандартный HTTP API интерфейс, работающий поверх JSON-RPC.
3. Собственная нода (Lite Server / Indexer) — подходит для крупных проектов с высокими требованиями к приватности и отсутствию лимитов.

Проверка баланса и транзакций через TonAPI

Пример запроса к REST-эндопоинту TON API для проверки аккаунта:

Bash

curl -X GET "https://tonapi.io/v2/accounts/EQD...address..." \
     -H "accept: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY"

При интеграции онлайн-оплаты в Telegram Mini App настройте Webhooks от API-провайдера на ваш сервер. Когда статус транзакции с нужным comment или hash изменится на success, сервер автоматически активирует услугу пользователя.

Матрица диагностики ошибок: проблемы и решения

В таблице ниже собраны наиболее частые сбои, возникающие при разработке и эксплуатации Telegram Mini Apps с интеграцией TON.

Ошибка / Симптом	Частая причина	Решение
Manifest URL validation failed	Несовпадение домена приложения с url в манифесте или отсутствие HTTPS.	Разместить манифест на том же домене, включить SSL-сертификат.
429 Too Many Requests	Превышение лимита запросов к публичному TON API.	Кэшировать запросы в Redis, добавить API Key, использовать запасные узлы.
Транзакция отправлена, но статус в Mini App не меняется	Отсутствие проверки статуса на бэкенде или зависание транзакции в мемпуле.	Внедрить отслеживание сообщений через Webhook или polling по hash/boc.
Wallet rejected transaction	Недостаточно TON на балансе для покрытия комиссий сети (газа).	Информировать пользователя о необходимости иметь 0.05–0.1 TON на балансе.
Session restore failed	Потеря локального хранилища при перезапуске Telegram Webview.	Реализовать серверную авторизацию через JWT на базе ton_proof.

Пограничные случаи, ошибки и точки отказа

В реальной эксплуатации Web3-приложений в Telegram вы столкнетесь со следующими проблемами:

1. Rate Limits на публичных API: Бесплатные ключи TON Center или TonAPI имеют строгие ограничения (например, 1–10 запросов в секунду). При резком притоке пользователей приложения перестанут получать данные. Всегда используйте кэширование на стороне бэкенда (Redis) и имейте резервных провайдеров.
2. Сброс WebSocket-сессий в Telegram: Мобильный клиент Telegram часто усыпляет фоновые процессы Mini App. Если пользователь переключился в кошелек для подтверждения оплаты, связь по TON Connect может разорваться. При возвращении в Mini App необходимо восстанавливать состояние сессии (tonConnectUI.connectionRestored).
3. Комиссии за газ (Gas Fees): На балансе пользователя может быть достаточно USDT, но не быть TON для оплаты газа блокчейна. Ваша система должна предупреждать пользователя об этом или использовать механизмы Gasless-транзакций (например, через W5 Wallet или релей-серверы).
4. Неустойчивые сети и задержки blocktime: Время генерации блока в TON составляет около 5 секунд, но при высокой нагрузке сети подтверждение может занять больше времени. Не блокируйте UI приложения неопределенным ожиданием без понятного статус-бара.
5. Масштабирование бэкенда и ретраи: Не полагайтесь на то, что информация о транзакции появится в TON API мгновенно. Реализуйте механизмы фоновой очереди (например, BullMQ / Celery), чтобы делать повторные запросы о состоянии транзакции с экспоненциальной задержкой (Exponential Backoff).

Практический сценарий: запуск подписки в Telegram Mini App

Представим реальную ситуацию: вы запускаете сервис платной аналитики или доступа к боту по подписке за 5 USDT в месяц.

1. Шаг 1: Пользователь открывает Mini App и нажимает «Оформить подписку».
2. Шаг 2: Бэкенд генерирует nonce, отправляет его в Mini App, где вызвана функция tonConnectUI.connect().
3. Шаг 3: Пользователь привязывает кошелек. Сервер валидирует ton_proof и создает аккаунт пользователя.
4. Шаг 4: Пользователь нажимает «Оплатить». Приложение вызывает метод sendTransaction с Payload для перевода 5 USDT на ваш корпоративный кошелек.
5. Шаг 5: Кошелек запрашивает подтверждение. Пользователь одобряет операцию.
6. Шаг 6: Mini App показывает статус «Обработка платежа» и посылает boc на сервер. Бэкенд начинает прослушивать вебхук от TON API.
7. Шаг 7: Как только блокчейн фиксирует перевод, TON API отправляет Webhook на ваш сервер. Подписка автоматически активируется в базе данных, а Telegram-бот отправляет пользователю инвайт-ссылку в закрытый чат.

Детальные выводы и рекомендации по архитектуре

Разработка надежного Telegram Mini App на базе протокола TON требует четкого разделения зон ответственности между клиентской частью и серверной инфраструктурой. Главная ошибка начинающих команд — пытаться возложить задачи проверки состояния блокчейна на TON Connect или, наоборот, доверять проверку подписи клиентскому коду.

Для построения отказоустойчивого сервиса придерживайтесь следующих принципов:

1. Используйте TON Connect только для действий пользователя. Этот протокол спроектирован исключительно для взаимодействия с кошельком: запроса авторизации, получения адреса и отправки транзакций на подпись.
2. Перенесите всю бизнес-логику и проверку на бэкенд. Использование TON API на сервере позволяет валидировать подлинность сессии через ton_proof, отслеживать статус платежей через вебхуки и проверять наличие токенов/NFT без риска подмены данных на клиенте.
3. Заложите задержки и ограничения сети в UX. Реализуйте информативные экраны ожидания, обрабатывайте случайные отмены транзакций пользователем и настраивайте кэширование запросов к TON API, чтобы избежать блокировок по IP при пиковых нагрузках.
4. Дублируйте провайдеров данных. В продакшн-среде всегда имейте резервный канал связи с сетью TON (например, комбинируйте TonAPI.io и собственную ноду), чтобы сбои на стороне стороннего сервиса не останавливали работу вашего Mini App.

После завершения технической части интеграции TON API и TON Connect ключевым этапом становится привлечение пользователей и тестирование Mini App на реальной аудитории. Вы можете найти профильные сообщества разработчиков, инвесторов и криптоэнтузиастов в каталоге NFT-чатов на CommyX. Каталог позволяет быстро подобрать релевантные площадки для рекламы, поиска партнеров и анонса новых функций вашего Telegram-приложения, а расширенный раздел все чаты с тегом NFT поможет отфильтровать активные группы по узким тематикам.