TON API integration

TON API Integration

TON (The Open Network) — this is not EVM. Before integrating, important to understand several things that break intuition for developer with EVM background: smart contracts are written in FunC/Tact, addresses have two formats (raw and user-friendly), and each contract — independent actor with own storage.

API Choice

TON Center API — public RPC, free with limits (1 req/sec without key, 10 req/sec with key). Sufficient for prototype.

TON Console (tonconsole.com) — paid API with higher limits, SDK, webhooks. Production standard.

TonWeb (tonweb npm package) and @ton/ton (official SDK) — main client libraries.

Working with Addresses

TON addresses exist in three formats:

import { Address } from "@ton/ton";

// Raw format: workchain:hex
const raw = "0:abcdef1234567890...";

// User-friendly: bounceable (for contracts)
const bounceable = "EQCr..."; // starts with EQ

// User-friendly: non-bounceable (for wallets on first send)
const nonBounceable = "UQCr..."; // starts with UQ

const addr = Address.parse(bounceable);
console.log(addr.toRawString());     // 0:...
console.log(addr.toString());        // EQ...
console.log(addr.toString({ bounceable: false })); // UQ...

Critical moment: on first TON send to new wallet must use non-bounceable address. If wallet doesn't exist and you sent to bounceable — coins bounce back. Standard integration error.

Getting Balance

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);
  // Returns nanotons (1 TON = 1e9 nanotons)
}

// For Jetton (TON tokens) need different approach — via Jetton wallet contract
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;
}

Transaction Monitoring

TON doesn't have event logs like Ethereum. For monitoring incoming payments — polling list of address transactions:

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;
}

// Newer — via 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) in TON — analog of block number for sorting transactions. When polling save last processed lt and request only new ones.

Sending 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, // in nanotons
        bounce: false,
        body: comment, // text comment to transfer
      }),
    ],
  });
}

Webhooks via TON Console

For production webhooks better than polling:

// Register webhook in TON Console Dashboard
// POST https://console.tonconsole.com/api/v1/webhook
{
  "url": "https://your-backend.com/webhooks/ton",
  "accounts": ["EQCr..."],  // addresses to monitor
  "event_types": ["transaction"]
}

// Handler
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) {
      // Incoming payment
      processPayment(account, tx.in_msg.value, tx.hash);
    }
  }
  res.sendStatus(200);
});

TON API integration for basic payment reception and monitoring: 1–2 days, including testing on testnet (testnet.toncenter.com).