Other Chain·Multi-chain
TON Connect
TON Connect is the standard wallet-connection protocol for The Open Network (TON, the Telegram-aligned L1). It links a dapp to user wallets (Tonkeeper, MyTonWallet, Telegram Wallet, OpenMask, etc.) over a bridge and lets the dapp request transaction signing without ever holding the user's keys.
- 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.