Other Chain·Multi-chain
TON Connect
TON Connect is the wallet onboarding standard for TON dApps and Telegram Mini Apps. This protocol reference helps builders evaluate manifest setup, wallet flow design, transaction signing, and the runtime edge cases that affect real user activation.
- 01TON dapps and Telegram Mini Apps
- 02TON wallet auth (Tonkeeper, Telegram Wallet)
- 03transaction signing on TON
- 04TON jetton and NFT transfers
- 05in-Telegram payments via TON
- pnpm add @tonconnect/ui-react @tonconnect/sdk @ton/ton @ton/core
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_TONCONNECT_MANIFEST_URL | Client | Public HTTPS URL to your `tonconnect-manifest.json` (name, url, iconUrl). Required by TonConnectUIProvider. |
| TON_API_ENDPOINT | Client | TON HTTP API endpoint, e.g. https://toncenter.com/api/v2/jsonRPC (mainnet) or https://testnet.toncenter.com/api/v2/jsonRPC. |
| TONCENTER_API_KEY | Server | Optional Toncenter API key for higher rate limits when querying chain state. |
Use TON Connect for wallet auth and signing on TON. Wrap the React app in `<TonConnectUIProvider manifestUrl={NEXT_PUBLIC_TONCONNECT_MANIFEST_URL}>` and read state via `useTonAddress()`, `useTonWallet()`, and `useTonConnectUI()`. Build transactions as `{ validUntil, messages: [{ address, amount, payload }] }` (amount in nanoTON, payload is a base64 BoC) and call `tonConnectUI.sendTransaction(tx)` — the wallet returns a BoC of the signed external message. For chain reads use `@ton/ton`'s `TonClient({ endpoint: TON_API_ENDPOINT })` and helpers like `client.getBalance(address)` or `client.runMethod(addr, 'get_jetton_data')`. Inside Telegram, `@tonconnect/ui-react` auto-detects the in-app Telegram Wallet via the embedded provider.
- ⚑TON uses an actor/account model where every account is a smart contract — there are no EOAs; sending TON to an uninitialized address requires `state_init` or the wallet contract is deployed lazily on first outgoing tx.
- ⚑Fees are paid in TON but the protocol supports native fee abstraction via jetton wallets and gasless relays — never assume the sender pays in the asset they are transferring.
- ⚑Finality is fast (~5s masterchain blocks) but cross-shard messages are asynchronous; a transfer may settle on the destination shard one or more blocks later, so poll by message hash, not just sender tx.
- ⚑Amounts and payloads use TON's BoC (Bag of Cells) serialization — strings, numbers, and addresses must be packed into `Cell`/`Slice` via `@ton/core`'s `beginCell()` builder, not JSON.
- ⚑The `manifestUrl` must be served over HTTPS with permissive CORS; wallets reject http://, localhost (without tunneling), or self-signed certs and the connect modal silently fails.
- ⚑Telegram Mini Apps run inside an iframe with strict CSP — set `allow="clipboard-write"` and use the `@telegram-apps/sdk` to detect the embedded Telegram Wallet provider.