Інтеграція з TON API

Інтеграція з TON API

TON (The Open Network) — це не EVM. Перш ніж інтегрувати, важливо зрозуміти кілька речей, які ломають інтуїцію розробника з EVM-бекграундом: смарт-контракти написані на FunC/Tact, адреси мають два формати (raw і user-friendly), і кожен контракт — незалежний actor з власним сховищем.

Вибір API

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 адреси існують у трьох форматах:

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, // текстовий коментар до переводу
      }),
    ],
  });
}

Webhooks через TON Console

Для 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);
});

Інтеграція TON API для базового приймання платежів і мониторингу: 1–2 дні, включаючи тестування на testnet (testnet.toncenter.com).