TON API Integration: Payment Processing & Jetton Balances in 1-2 Days

A developer with ten years of Solidity experience tries to send their first TON transaction — and gets an address compatibility error. The 0x... format doesn't work; EVM logic is not applicable: TON is built on an actor architecture, smart contracts are written in FunC or Tact, and addresses come in three formats. Without a clear understanding of these differences, integration becomes a week of debugging. Our engineers, with 5 years of blockchain experience, have developed an approach that reduces typical integration to 1–2 days turnkey. We assume all risks related to API selection, address conversion, webhook configuration, and testnet testing. We guarantee correct payment and balance processing.

How to Choose an API for TON?

TON Center API is a public RPC, free with limits (1 req/sec without key, 10 req/sec with key). Sufficient for prototypes. TON Console (tonconsole.com) is a paid API with higher limits, SDK, and webhooks. It is the production standard for high-load projects. We recommend it for commercial solutions. TonWeb (tonweb npm package) and @ton/ton (official SDK) are the main client libraries. For new projects, @ton/ton is preferred.

Comparison of TON SDKs

@ton/ton is tightly integrated with TON Console and provides typed contracts. For new projects, it is the clear choice.

How to Avoid Errors with Addresses?

TON addresses come 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 point: on the first send of TON to a new wallet, use a non-bounceable address. If the wallet does not exist and you send to a bounceable address, the coins will bounce back. This is a standard integration error that our engineers handle automatically.

How to Get Balance and Monitor Transactions?

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 Jettons (TON tokens), a different approach is needed — 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; } 

TON does not have event logs like Ethereum. For monitoring incoming payments — poll the address transaction list:

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 is analogous to block number for sorting transactions. When polling, we save the last processed lt and request only new ones. This efficiently handles payments without duplication.

How to Send TON with a Comment?

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 attached to transfer }), ], }); } 

The comment (body) is arbitrary text up to 127 bytes. It is used for payment identification (e.g., order number).

How to Set Up Webhooks for Production?

For production, webhooks are preferable to 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); }); 

Webhooks via TON Console are a reliable way to avoid losing transactions. We configure endpoints with retries and duplicate handling to guarantee 99.9% uptime tracking.

Typical Integration Mistakes

What is Included in Turnkey Integration

• Requirements audit and optimal API selection
• TON client setup and address conversion
• Balance retrieval module (TON + Jettons)
• Incoming payment monitoring implementation (polling or webhooks)
• Integration of TON sending with comments
• Testing on testnet and mainnet
• API and integration documentation
• One month of post-launch support

Process

1. Analysis — we study your task and current architecture
2. Design — we choose API, design error handling
3. Implementation — we write code, connect SDK
4. Testing — we run on testnet, check scenarios
5. Deployment — we publish to production, set up monitoring
6. Support — we fix bugs, consult for 30 days

We will evaluate your project for free — contact us for a consultation. TON API integration for basic payment processing and monitoring: from 1 to 2 days, including testnet testing. Save up to 70% development time compared to self-implementation.

For more on TON architecture, see Wikipedia. For SDK usage, refer to the official @ton/ton repository on GitHub.