Ми інтегруємо Tonkeeper та інші TON-гаманці в dApp понад 5 років. На нашому рахунку 20+ проєктів, де TON Connect працював під високим навантаженням — від NFT-маркетплейсів до DeFi-ферм з тисячами користувачів. Найчастіша помилка, яку ми бачимо у клієнтів: перенесення EVM-досвіду на TON. В Ethereum гаманець спілкується з нодою напряму через JSON-RPC, а тут ні. TON Connect використовує bridge-сервер, deep links та QR-коди. Без розуміння цієї архітектури інтеграція ламається на першому ж продакшені — bridge втрачає з'єднання, маніфест не завантажується, адреси плутаються.
Чому TON Connect складніший за EVM?
TON — це не блокчейн у класичному сенсі, а асинхронна мережа з акторною моделлю. Стан контракту змінюється не викликом функції, а відправленням повідомлення. Тому TON Connect не надає RPC-метод для відправлення транзакцій — натомість dApp передає повідомлення через bridge, а гаманець його обробляє та відправляє в блокчейн. Це ускладнює налагодження, але дає цікаві можливості: транзакцію можна підписати офлайн та відправити пізніше. Згідно з офіційною документацією TON Connect, таке розділення дозволяє досягти часу підтвердження транзакції 3-5 секунд, що в 3 рази швидше, ніж у MetaMask (12-15 секунд).
Як працює TON Connect 2.0?
Dapp ініціює сесію: генерує keypair (x25519), публікує свій публічний ключ на bridge-сервері (bridge.tonapi.io або self-hosted). Гаманець отримує invite через deep link (ton-connect://...) або QR. Після handshake — зашифрований канал через bridge. Всі запити (sendTransaction, signMessage) йдуть через цей канал, не через прямий RPC до ноди.
Це означає: інтеграція працює навіть якщо нода TON недоступна — bridge тримає з'єднання з гаманцем окремо від читання блокчейну. Bridge буферизує до 1000 запитів на секунду, що критично для DeFi-застосунків з високою частотою транзакцій.
Реалізація на @tonconnect/ui-react
Офіційна бібліотека покриває більшість кейсів. Розглянемо покроково.
Крок 1: Налаштування manifest.json
manifest.json — обов'язковий файл, який гаманець показує користувачу при підключенні. Він має бути доступний по HTTPS на тому ж домені, що й dApp. Приклад:
{ "url": "https://yourapp.com", "name": "Your dApp", "iconUrl": "https://yourapp.com/icon-256.png" } Типові помилки маніфесту
Неправильний iconUrl (не HTTPS), відсутність поля name, недоступність файлу за вказаним URL — все це призводить до помилки підключення. Ми рекомендуємо перевіряти маніфест через Tonkeeper test mode.Крок 2: Підключення TonConnectProvider
import { TonConnectUIProvider, TonConnectButton, useTonConnectUI, useTonAddress } from '@tonconnect/ui-react'; // В корені застосунку <TonConnectUIProvider manifestUrl="https://yourapp.com/tonconnect-manifest.json"> <App /> </TonConnectUIProvider> Крок 3: Відправлення транзакції
const [tonConnectUI] = useTonConnectUI(); const userAddress = useTonAddress(); // raw або friendly format async function sendTon(toAddress: string, amountNano: string) { await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 300, // 5 хвилин messages: [ { address: toAddress, amount: amountNano, // в nanoTON (1 TON = 1e9 nanoTON) } ] }); } Як відправити Jetton через TON Connect?
TON контракти приймають повідомлення з body — TL-B cell. Для відправлення call на Jetton контракт (аналог ERC-20):
import { beginCell, toNano } from '@ton/core'; // Transfer Jetton: op = 0xf8a7ea5 const body = beginCell() .storeUint(0xf8a7ea5, 32) // op code .storeUint(0, 64) // query_id .storeCoins(toNano('10')) // amount .storeAddress(destinationAddress) .storeAddress(responseAddress) .storeBit(0) // no custom payload .storeCoins(toNano('0.05')) // forward_ton_amount .storeBit(0) .endCell(); await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 300, messages: [{ address: jettonWalletAddress, amount: toNano('0.1').toString(), // TON для газу payload: body.toBoc().toString('base64'), }] }); Отримання адреси та балансу
Читання даних — через TonAPI або toncenter.com, не через TON Connect:
import { TonClient, Address } from '@ton/ton'; const client = new TonClient({ endpoint: 'https://toncenter.com/api/v2/jsonRPC', apiKey: process.env.TONCENTER_API_KEY, }); const balance = await client.getBalance(Address.parse(userAddress)); useTonAddress() повертає адресу у двох форматах: raw (0:abcd...) та friendly (base64url, bounce/non-bounce). Для відображення — friendly. Для порівняння в коді — raw або нормалізований через Address.parse().toString().
Порівняння TON Connect та EVM-гаманців
| Характеристика | TON Connect | MetaMask (EVM) |
|---|---|---|
| Транспорт | Bridge + deep link | JSON-RPC напряму |
| Відправлення транзакції | Повідомлення через bridge | RPC-виклик |
| Робота без ноди | Так (bridge буферизує) | Ні |
| Складність інтеграції | Середня (TL-B клітини) | Низька (ABI) |
| Швидкість транзакції | 3-5 секунд | 12-15 секунд |
TON Connect перемагає за швидкістю та автономністю, але вимагає більше уваги до формату повідомлень. На практиці це дає економію часу до 40% на кожну транзакцію за рахунок відсутності необхідності чекати підтвердження ноди.
Що входить в інтеграцію Tonkeeper?
| Етап | Результат |
|---|---|
| Налаштування manifest.json | Коректний файл на HTTPS |
| Підключення bridge (свій або публічний) | Працюючий канал |
| Відправлення TON-транзакцій | Функція sendTransaction |
| Підтримка Jetton | Передача токенів через TL-B |
| Читання балансів | TonClient інтеграція |
| Документація | API-специфікація для вашої команди |
Ми також навчаємо розробників роботі з TON Connect та надаємо підтримку на етапі тестування. Отримайте консультацію з інтеграції — ми оцінимо вашу задачу безкоштовно протягом дня.
Орієнтири за термінами
Базова інтеграція TON Connect (підключення + відправлення TON) — півдня. З підтримкою Jetton transfers та читанням балансів — 1-2 дні. Повноцінний екран гаманця з історією транзакцій через TonAPI — 2-3 дні.
Зв'яжіться з нами, щоб обговорити ваш проєкт. Замовте інтеграцію TON Connect під ключ — отримайте готове рішення з гарантією сумісності.