Integrating TON Connect into a mobile wallet presents several key challenges: establishing a secure channel between the dApp and the wallet, correctly serializing cryptographic data, and choosing the optimal transport. On one project, the bridge server disconnected every 30 minutes due to SSE timeout, forcing us to implement automatic reconnection with exponential backoff. TON Connect is a communication protocol over HTTP bridge with push notifications via SSE. Unlike WalletConnect (EVM world), it uses its own protocol, requiring deep understanding of the transport layer and cryptography. We have successfully integrated TON Connect into wallets with over 100,000 users, tested compatibility with 30+ dApps, and ensure connection stability at 99.9%. Such integration reduces maintenance costs and accelerates time to market, paying off within an average of half a year.
How TON Connect Transport Works
The protocol operates through a bridge server (bridge.tonapi.io or a self-hosted one). The wallet and dApp exchange encrypted messages via this bridge — no direct connection. Encryption uses NaCl box (X25519 + XSalsa20-Poly1305).
The mobile wallet app connects to the bridge via SSE (Server-Sent Events): GET /bridge/{clientId}/events. This is a long-lived HTTP request that keeps the connection open. On iOS, this is problematic: URLSession does not natively support SSE, requiring an EventSource library or a custom implementation via URLSessionDataDelegate. On Android with OkHttp, there is no built-in SSE support either, but the EventSource from the OkHttp team (com.squareup.okhttp3:okhttp-sse) solves the problem.
An alternative transport is deeplink. The dApp encodes a tc:// or https://ton.app/... link; the user clicks it, the wallet opens and receives a connect request from URL parameters. This is a synchronous flow without a bridge — simpler, but requires the dApp and wallet to be on the same device.
| Transport | Advantages | Disadvantages |
|---|---|---|
| SSE (HTTP bridge) | Persistent connection, push notifications, supports background events | More complex to implement, requires SSE support on the client |
| Deeplink | Simple implementation, no bridge server needed, instant sync | Single device only, no push notifications, doesn't work with background updates |
Why ton_proof is Critical for Security
ton_proof is a cryptographic proof of wallet ownership without signing a transaction. Format: ton-proof-item-v2/<wc>:<addr_bytes>/<app_domain>/<timestamp>/<payload>. It is signed with the wallet's private key via Ed25519. The dApp verifies the signature via TON API, not trusting the wallet blindly. The TON Connect specification mandates using the raw address for addr_bytes; otherwise the signature will be invalid.
A typical mistake in implementing ton_proof: incorrect serialization of addr_bytes — the raw format is needed (workchain + 32-byte hash), not the user-friendly bounce/non-bounce address. Check the specification. ton_proof allows the dApp to confirm that the user actually owns the wallet without signing a full transaction. The mechanism prevents replay attacks by including the domain and timestamp.
Handling Connect Request in the Wallet
When receiving a connection request, the wallet must:
- Decode the ConnectRequest from the encrypted payload (or from the deeplink
rparameter). - Show the user: which dApp is requesting connection, which items are needed (
ton_addr,ton_proof). - Obtain user approval.
- Form a ConnectResponse with the wallet address, network (
mainnet/testnet), public key, and ton_proof if requested.
Transaction Signing and BOC Decoding
After connection, the dApp sends a SendTransactionRequest with a BOC (Bag of Cells) — the binary representation of a TON transaction. The wallet:
- Decodes the BOC using
ton-coreor@ton/ton. - Shows transaction details to the user: recipient, amount, comment.
- Signs the transaction with the private key.
- Sends the signed BOC to the TON network via
tonapi.ioortoncenter.com. - Returns a SendTransactionResponse with the transaction hash to the dApp.
How to Decode BOC?
Decoding a BOC for UI display is non-trivial. The BOC may contain smart contract calls with arbitrary payloads. For standard jetton transfers, there is an OP code parser (0xf8a7ea5 — jetton transfer); for the rest, we show raw hex with a warning. Use ton-core libraries for parsing.
What's Included in TON Connect Integration
The scope of work includes:
- Audit of the current wallet architecture and integration recommendations.
- Documentation of the protocol and bridge server configuration.
- Implementation of the chosen transport (SSE, deeplink, or both).
- Codebase for the TON Connect module in Swift/Kotlin/Dart/TypeScript.
- Testing with 5+ real dApps (Tonkeeper, Getgems, etc.).
- Writing unit and integration tests.
- Training the client's team.
- Support for one month after release.
TON Connect Integration Stages
- Analysis — study your wallet architecture, select transport, agree on specifics.
- Design — develop connection schema, define ton_proof and BOC processing.
- Implementation — code in Swift/Kotlin/Flutter with App Store and Google Play requirements. Implement push support (APNs/FCM).
- Testing — verify with real dApps, validate transaction signatures.
- Deployment — publish the update in stores, configure bridge (if needed).
| Stage | Duration | Result |
|---|---|---|
| Analysis | 1–3 days | Technical spec, tech stack selection |
| Design | 3–5 days | Architecture documentation |
| Implementation | 2–4 weeks | Working TON Connect module |
| Testing | 1 week | Test report, bug fixes |
| Deployment | 3–5 days | Release in stores, monitoring |
TON Connect vs WalletConnect
TON Connect is better than WalletConnect in the TON ecosystem due to native integration with TON Blockchain: no data type conversion needed, and ton_proof is more secure than message signing. Also, SSE support allows the wallet to receive balance update events without additional requests. If you need integration with dApps in TON, TON Connect is the only corporate standard. Implementation is available on iOS (Swift), Android (Kotlin), and cross-platform frameworks. For native platforms, the SDK is developed in-house per specification, and a good reference is the Tonkeeper open-source repository.
Timeline and Cost
Integration of TON Connect into an existing wallet (connection and transaction signing only) — 3–5 weeks. A full TON wallet from scratch (seed management, key derivation, jetton support, NFT, staking) — from 4 to 6 months. Cost is calculated individually after analyzing your project.
Estimate your project: contact us for a consultation. Order TON Connect integration for your wallet — get a stable solution with a guarantee.