An EVM developer, first encountering TON, stumbles at every step: a transaction is sent but never arrives, addresses look strange (0:abc...), and data is packed into some Cells. We've seen this dozens of times—and we've developed an approach that removes the headache. Our team has embedded TON into frontends since the network launch: from simple exchanges to complex DeFi protocols. During this time, we've integrated over 30 wallets, processed thousands of external messages, and guarantee stable operation in production.
How to Integrate TON SDK into Frontend
Problems We Solve
The first and main problem is misunderstanding the Cell model. In TON, any message is a Cell, serialized into Bag of Cells (BOC). Without correct assembly, you'll get a stuck transaction and an empty wallet. The second problem is the TonConnect manifest: if it is not accessible via a public URL, the wallet won't respond. The third is asynchrony: a transaction is not finalized instantly, and chains of inter-contract messages unfold over 2-3 seconds. Clients often panic when they don't see a receipt. We solve these problems with a clear Cell assembly scheme and manifest configuration.
Setting Up TonConnect: Step-by-Step Guide
TonConnect is the de facto standard. It is supported by Tonkeeper, MyTonWallet, Telegram Wallet, and dozens of others. Don't invent your own connection protocol.
How to Connect a Wallet?
import { TonConnectUI } from '@tonconnect/ui-react'; const tonConnectUI = new TonConnectUI({ manifestUrl: 'https://yourdomain.com/tonconnect-manifest.json', }); await tonConnectUI.connectWallet(); const wallet = tonConnectUI.wallet; const userAddress = wallet?.account.address; // raw form: 0:abc... The file tonconnect-manifest.json describes the app—name, icon, URL. The wallet shows it to the user upon connection request. Without a correct manifest at a public URL, the connection won't work. We always place the manifest on a CDN with high availability—this reduces delays by 30%.
How to Send an External Message?
In TON, the frontend sends an external message to the wallet contract. The wallet signs it and broadcasts to the network.
import { toNano } from '@ton/ton'; await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 600, messages: [ { address: '0:contractAddress', amount: toNano('0.05').toString(), payload: buildPayload().toBoc().toString('base64'), }, ], }); payload is a Cell, serialized into BOC. To interact with a specific contract, you need to know its TL-B schema and build the Cell manually via beginCell()...endCell(). One error in serialization—and the transaction will stall.
Reading Data from a Contract
import { TonClient, Address } from '@ton/ton'; const client = new TonClient({ endpoint: 'https://toncenter.com/api/v2/jsonRPC', apiKey: 'YOUR_KEY', }); const address = Address.parse('EQD...'); const result = await client.runMethod(address, 'get_wallet_data', []); const balance = result.stack.readBigNumber(); For production, use your own toncenter or TON API from tonapi.io—the public endpoint has rate limiting and is unstable under load.
How TON Differs from EVM for Frontend
| Characteristic | TON | EVM |
|---|---|---|
| Addressing | raw: 0:abc... | 0x... |
| Data serialization | Cell / BOC | ABI |
| Finalization time | several seconds | 12-15 seconds |
| Wallet connection | TonConnect | WalletConnect |
| Transaction sending | External messages | Signed transactions |
In TON, transactions are processed 2-3 times faster due to the asynchronous model and sharding.
Why Transactions in TON Work Differently
A transaction in TON is not finalized instantly—between sending and contract execution, several seconds pass, and chains of inter-contract messages unfold asynchronously. To confirm execution, you need to poll the account's transaction history, not just wait for a receipt as in Ethereum. This reduces RPC load and provides a smoother user experience.
Work Process and Timelines
Integration Stages
| Stage | Duration (working days) |
|---|---|
| Requirements audit | 2-3 |
| Design | 3-5 |
| Frontend development | 5-10 |
| Integration and testing | 3-5 |
| Deployment | 1-2 |
- Requirements audit—we analyze your stack and contract API.
- Design—we define the message structure and Cell schema.
- Frontend development—we write components with TonConnect, sending and reading.
- Integration—we connect to the test network and debug.
- Testing—we verify on Tonkeeper, MyTonWallet, Telegram Wallet.
- Deployment—we configure production endpoint, publish the manifest.
Estimated Timelines
Basic integration (wallet + one transaction) takes 2 to 3 weeks. A full dApp with bridges and multiple contracts takes 4 to 6 weeks. The cost is calculated individually.
What's Included in the Work
- Preparation of documentation on used contracts and Cells.
- Frontend code in React/TypeScript using @ton/ton and TonConnect.
- Configuration of TonConnect manifest and its deployment on CDN.
- Instructions for deployment and wallet connection.
- One month of technical support after delivery.
Common Mistakes in TON Integration
Many developers forget about timeout: the standard validUntil is 10 minutes, but without handling expiration, the user hangs waiting. Check the manifest first: if it's not accessible via HTTPS or returns CORS, the wallet stays silent. Incorrect Cell assembly is a frequent cause of stuck transactions. Use beginCell() and endCell() with the correct type. Ignoring asynchrony—poll the account history via getTransactions instead of waiting for a receipt.
How to Avoid Common Mistakes in TON Integration?
Remember three rules: the manifest must be accessible and return valid JSON, always handle timeout, and don't build Cells blindly—use the Ton Console debugger or test contracts. Our experience shows that following these rules cuts integration time by half. Contact us for a project assessment—we'll provide a turnkey solution. Get an engineer consultation within 2 days.