TON Connect Wallet Auth Quickstart

A TON Connect implementation starts with tonconnect-manifest.json, not with the wallet button.

Wallets use the manifest to identify the application. That means the manifest has to be reachable from the real environment where users connect, not only from a local development setup.

The current repo context points to the common React pattern:

<TonConnectUIProvider manifestUrl={NEXT_PUBLIC_TONCONNECT_MANIFEST_URL}>

This is more than setup boilerplate. It creates one predictable wallet state layer for the application.

Teams usually move faster when they keep connection state centralized instead of scattering wallet logic across modal triggers, page components, and custom event handlers.

The current repo integration data points to hooks such as:

• useTonAddress()
• useTonWallet()
• useTonConnectUI()

Those hooks should drive more than a connected badge. They should drive product decisions such as:

• whether the user can continue to the next task
• which wallet-dependent screens can render safely
• whether the app should show a payment, signature, or account-specific flow
• whether reconnect and disconnect controls are easy to find

TON signing is one of the places where builders coming from EVM patterns lose time.

The repo context describes the transaction shape as:

{
  validUntil,
  messages: [{ address, amount, payload }]
}

• amount is denominated in nanoTON
• payload is a base64 BoC when the action requires one
• the wallet returns a BoC of the signed external message

Many products are not connecting a wallet only to show an address. They are connecting because the user is about to sign for a payment, jetton transfer, NFT action, or contract call.

Connection alone is not enough. Most real apps need to read chain state right after connect.

The current repo context points to @ton/ton with a TonClientpattern for reads such as balances or contract methods. In practice, that means the wallet-auth quickstart should also account for what happens right after the session is established.

• balance checks before the user pays or sends
• account-state checks before a contract interaction
• post-sign polling when the product needs to reflect final status
• method calls needed to show token or app-specific state

TON does not follow the familiar EVM assumption that a visible address is a simple externally owned account. In TON, accounts are smart contracts.

Sending to an uninitialized address or assuming every address is already fully ready for interaction can create unexpected failure states.

TON payload construction is not generic JSON. When the app needs a payload, it usually has to be packed into TON’s Bag of Cells format.

That matters because a wallet UI can connect successfully even while the real contract interaction fails later.

TON finality is fast, but downstream effects can still land later than the wallet-approval moment suggests. A signed request is not always the same thing as a completed user outcome.

TON Connect is especially relevant for Telegram Mini Apps, and Telegram can change the behavior of wallet detection, embedded flows, and runtime assumptions.