Інтеграція з TON API: прийом платежів, баланси Jettons за 1-2 дні

Розробник із десятирічним досвідом у Solidity намагається відправити першу транзакцію через TON — і отримує помилку несумісності адрес. Адреса у форматі 0x... не працює, EVM-логіка не застосовна: TON побудований на архітектурі actors, смарт-контракти пишуть на FunC або Tact, адреси мають три формати. Без чіткого розуміння цих відмінностей інтеграція перетворюється на тиждень налагодження. Наші інженери з 5-річним досвідом у блокчейні розробили підхід, який скорочує типову інтеграцію до 1–2 днів під ключ. Ми беремо на себе всі ризики, пов'язані з вибором API, конвертацією адрес, налаштуванням webhooks і тестуванням на testnet. Гарантуємо коректну обробку платежів і балансів.

Як вибрати API для TON?

TON Center API — публічний RPC, безкоштовний з лімітами (1 req/sec без ключа, 10 req/sec з ключем). Достатньо для прототипу. TON Console (tonconsole.com) — платний API з вищими лімітами, SDK, webhooks. Це production стандарт для проектів з високим навантаженням. Ми рекомендуємо його для комерційних рішень. TonWeb (tonweb npm пакет) та @ton/ton (офіційний SDK) — основні клієнтські бібліотеки. Для нових проектів переважніший @ton/ton.

Порівняння SDK для TON

@ton/ton тісно інтегрований з TON Console та надає типізовані контракти. Для нових проектів — однозначний вибір.

Як уникнути помилок при роботі з адресами?

TON адреси існують у трьох форматах:

import { Address } from "@ton/ton"; // Raw формат: workchain:hex const raw = "0:abcdef1234567890..."; // User-friendly: bounceable (для контрактів) const bounceable = "EQCr..."; // починається з EQ // User-friendly: non-bounceable (для гаманців при першому відправленні) const nonBounceable = "UQCr..."; // починається з UQ const addr = Address.parse(bounceable); console.log(addr.toRawString()); // 0:... console.log(addr.toString()); // EQ... console.log(addr.toString({ bounceable: false })); // UQ... 

Критичний момент: при першому відправленні TON на новий гаманець потрібно використовувати non-bounceable адресу. Якщо гаманець не існує і ви відправили на bounceable — монети повернуться. Стандартна помилка при інтеграції, яку наші інженери автоматично обробляють.

Як отримати баланс і моніторити транзакції?

import { TonClient, Address } from "@ton/ton"; const client = new TonClient({ endpoint: "https://toncenter.com/api/v2/jsonRPC", apiKey: process.env.TON_CENTER_API_KEY, }); async function getTonBalance(address: string): Promise<bigint> { const addr = Address.parse(address); return client.getBalance(addr); // Повертає nanotons (1 TON = 1e9 nanotons) } // Для Jetton (TON токени) потрібен інший підхід — через Jetton wallet контракт async function getJettonBalance( ownerAddress: string, jettonMasterAddress: string ): Promise<bigint> { const master = client.open(JettonMaster.create(Address.parse(jettonMasterAddress))); const walletAddress = await master.getWalletAddress(Address.parse(ownerAddress)); const wallet = client.open(JettonWallet.create(walletAddress)); const data = await wallet.getWalletData(); return data.balance; } 

TON не має event logs як у Ethereum. Для моніторингу вхідних платежів — polling списку транзакцій адреси:

async function getTransactions(address: string, limit = 20) { const response = await fetch( `https://toncenter.com/api/v2/getTransactions?` + `address=${address}&limit=${limit}&archival=true`, { headers: { "X-API-Key": process.env.TON_CENTER_API_KEY! } } ); const { result } = await response.json(); return result; } // Новіше — через TON API v3 (tonapi.io) async function getIncomingPayments(address: string, afterLt?: string) { const params = new URLSearchParams({ account: address, limit: "50", ...(afterLt && { after_lt: afterLt }), }); const response = await fetch( `https://tonapi.io/v2/accounts/${address}/transactions?${params}`, { headers: { Authorization: `Bearer ${process.env.TONAPI_KEY}` } } ); return response.json(); } 

Logical Time (lt) в TON — аналог block number для сортування транзакцій. При polling зберігаємо останній оброблений lt і запитуємо тільки нові. Це дозволяє ефективно обробляти платежі без дублювання.

Як відправити TON з коментарем?

import { WalletContractV4, internal } from "@ton/ton"; import { mnemonicToPrivateKey } from "@ton/crypto"; async function sendTon(toAddress: string, amount: bigint, comment?: string) { const keyPair = await mnemonicToPrivateKey(process.env.MNEMONIC!.split(" ")); const wallet = WalletContractV4.create({ publicKey: keyPair.publicKey, workchain: 0, }); const contract = client.open(wallet); const seqno = await contract.getSeqno(); await contract.sendTransfer({ secretKey: keyPair.secretKey, seqno, messages: [ internal({ to: toAddress, value: amount, // в nanotons bounce: false, body: comment, // текстовий коментар до переказу }), ], }); } 

Коментар (body) — довільний текст до 127 байт. Використовується для ідентифікації платежу (наприклад, номер замовлення).

Як налаштувати webhooks для продакшену?

Для production краще webhooks, ніж polling:

// Реєстрація webhook у TON Console Dashboard // POST https://console.tonconsole.com/api/v1/webhook { "url": "https://your-backend.com/webhooks/ton", "accounts": ["EQCr..."], // адреси для моніторингу "event_types": ["transaction"] } // Обробник app.post("/webhooks/ton", (req, res) => { const { account, transactions } = req.body; for (const tx of transactions) { if (tx.in_msg && tx.in_msg.value > 0) { // Вхідний платіж processPayment(account, tx.in_msg.value, tx.hash); } } res.sendStatus(200); }); 

Webhooks через TON Console — це надійний спосіб уникнути втрати транзакцій. Ми налаштовуємо ендпоїнти з ретраями та обробкою дублікатів, щоб гарантувати 99.9% uptime відстеження.

Типові помилки при інтеграції

Що входить в інтеграцію під ключ

• Аудит вимог і вибір оптимального API
• Налаштування TON клієнта і конвертація адрес
• Розробка модуля отримання балансів (TON + Jettons)
• Реалізація моніторингу вхідних платежів (polling або webhooks)
• Інтеграція відправлення TON з коментарями
• Тестування на testnet та mainnet
• Документація по API та інтеграції
• Підтримка протягом місяця після запуску

Процес роботи

1. Аналіз — вивчаємо ваше завдання та поточну архітектуру
2. Проектування — вибираємо API, проектуємо обробку помилок
3. Реалізація — пишемо код, підключаємо SDK
4. Тестування — запускаємо на testnet, перевіряємо сценарії
5. Деплой — публікуємо в production, налаштовуємо моніторинг
6. Підтримка — виправляємо баги, консультуємо 30 днів

Оцінимо ваш проект безкоштовно — зв'яжіться з нами для консультації. Інтеграція TON API для базового прийому платежів і моніторингу: від 1 до 2 днів, включаючи тестування на testnet. Економія часу розробки до 70% порівняно з самостійною реалізацією.

Докладніше про архітектуру TON можна прочитати в Wikipedia. Для роботи з SDK використовуйте офіційний репозиторій @ton/ton на GitHub.