Интеграция с 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) — arbitrary текст до 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.