Integrating TON Connect into dApps and Telegram Mini Apps

Integrating TON Connect into dApps and Telegram Mini Apps

We integrate TON Connect into your dApp or Telegram Mini App — not just a "wallet for TON", but a full communication protocol between the app and the wallet over a bridge server. Unlike EVM, where window.ethereum is injected into the page, TON wallets (Tonkeeper, MyTonWallet, Telegram Wallet) operate as separate apps and communicate with the dApp through an encrypted channel. This architectural difference is critical for a correct integration. According to TON (The Open Network), TON Connect is used in over 200 dApps, and wallet connection time is reduced by 40% compared to direct RPC.

How TON Connect Differs from EVM Wallets

The main difference is the asynchronous connection. In EVM, the wallet is built into the browser, while in TON, the connection is established via QR code or deeplink (in Telegram — directly). The protocol uses a bridge server for message exchange, enhancing security: the dApp never receives the private key. TON also supports multiple messages in a single transaction — enabling complex smart contract calls in one step.

How to Set Up TON Connect in a React dApp in 15 Minutes

Install the library and initialize:

npm install @tonconnect/ui-react 

Manifest — a JSON file that the wallet shows to the user upon connection. Must be available over HTTPS:

// public/tonconnect-manifest.json { "url": "https://yourapp.com", "name": "Your dApp", "iconUrl": "https://yourapp.com/icon.png" } 

App wrapper and ready-made button:

// main.tsx import { TonConnectUIProvider } from '@tonconnect/ui-react' root.render( <TonConnectUIProvider manifestUrl="https://yourapp.com/tonconnect-manifest.json"> <App /> </TonConnectUIProvider> ) // Component with button and custom UI import { TonConnectButton, useTonConnectUI, useTonAddress, useTonWallet } from '@tonconnect/ui-react' function WalletInfo() { const address = useTonAddress() const rawAddress = useTonAddress(false) const wallet = useTonWallet() const [tonConnectUI] = useTonConnectUI() return ( <div> <TonConnectButton /> <p>Address: {address}</p> <p>Wallet: {wallet?.device.appName}</p> <button onClick={() => tonConnectUI.disconnect()}>Disconnect</button> </div> ) } 

TON addresses come in two formats: user-friendly (EQD... or UQD...) and raw (0:abc...). User-friendly includes bounceable/non-bounceable. For sending to smart contracts, use bounceable (EQ); for wallets, use non-bounceable (UQ).

How to Send a Transaction and Handle Errors

TON Connect sends messages. A single transaction can contain multiple messages:

import { useTonConnectUI } from '@tonconnect/ui-react' import { toNano } from '@ton/ton' import { beginCell } from '@ton/ton' // Sending a transaction function SendTon() { const [tonConnectUI] = useTonConnectUI() async function sendTransaction() { const transaction = { validUntil: Math.floor(Date.now() / 1000) + 360, messages: [ { address: 'EQD...contractAddress', amount: toNano('0.05').toString(), payload: 'te6ccgEBAQEAAgAAAA==', // base64 BOC } ] } const result = await tonConnectUI.sendTransaction(transaction) // result.boc — BOC of signed transaction } } // Building payload for jetton transfer const body = beginCell() .storeUint(0xf8a7ea5, 32) .storeUint(0, 64) .storeCoins(toNano('10')) .storeAddress(destinationAddress) .storeAddress(responseAddress) .storeBit(false) .storeCoins(toNano('0.01')) .storeBit(false) .endCell() 

payload is BOC (Bag of Cells), a serialized structure for contract calls. A typical mistake is using the wrong bounceable flag, leading to Invalid boc. Always verify the address format and use toNano for conversion.

How to Restore a Session and Work with Events

TON Connect automatically restores the session from localStorage. Subscribe to status changes:

import { useTonConnectUI } from '@tonconnect/ui-react' const [tonConnectUI] = useTonConnectUI() useEffect(() => { const unsubscribe = tonConnectUI.onStatusChange((wallet) => { if (wallet) { console.log('Connected:', wallet.account.address) } else { console.log('Disconnected') } }) return unsubscribe }, [tonConnectUI]) 

In Telegram Mini Apps, TON Connect works through Telegram Wallet directly — no QR code. TonConnectUIProvider automatically detects the context and shows the correct UI. Before rendering the provider, call window.Telegram.WebApp.ready().

Why Integrate TON Connect Through Us?

We have completed over 20 successful TON Connect integrations — from simple dApps to complex DeFi protocols. Our experience shows that proper TON Connect setup increases connection conversion by 30-50% thanks to a smooth UX and support for all popular wallets. We guarantee correct operation on Tonkeeper, MyTonWallet, Telegram Wallet, as well as on mobile and desktop devices.

Our TON Integration Process

Timeline — from 5 to 15 days depending on complexity. Pricing is determined individually. Get an accurate estimate after a consultation.

What's Included

The scope includes: integration documentation, manifest file setup, custom connection UI development, testing on all popular wallets (Tonkeeper, MyTonWallet, Telegram Wallet), team training, and post-release support.

Typical Pitfalls in TON Connect Integration

• Wrong bounceable flag: use EQ for contracts and UQ for wallets. Otherwise, the transaction will fail with an error.
• Invalid boc: check payload serialization via beginCell(), especially storeCoins with toNano.
• validUntil expiration: add a 5-10 minute buffer, otherwise the wallet rejects the transaction.
• Missing HTTPS for manifest: the wallet won't connect to a dApp without HTTPS.

How to Order TON Connect Integration

Contact us for a consultation — get a preliminary implementation plan and an accurate cost estimate. Order TON Connect integration today and give your users a safe and convenient entry into the TON ecosystem.

According to the TON Connect Protocol specification, the protocol supports all modern TON wallets and continues to evolve.