TON Connect Wallet Onboarding Guide

TON Connect depends on a public tonconnect-manifest.json served over HTTPS. The required environment variable is NEXT_PUBLIC_TONCONNECT_MANIFEST_URL, and it is used by TonConnectUIProvider to identify the app.

This step is easy to underestimate. It is also one of the fastest ways to break onboarding.

Why it matters:

• wallets use the manifest to identify your application
• wallets can reject non-HTTPS, localhost-only, or self-signed setups
• misconfigured CORS can make the connect experience fail silently

If the manifest is unstable, the rest of the onboarding flow is unstable too.

The integration flow works best when the React app is wrapped in a single provider layer built around TonConnectUIProvider.

<TonConnectUIProvider manifestUrl={NEXT_PUBLIC_TONCONNECT_MANIFEST_URL}>

That provider choice is more than setup boilerplate. It determines whether wallet state is centralized and predictable or spread across disconnected components.

A clean onboarding implementation usually starts with one provider layer, then reads connection state through hooks such as useTonAddress(), useTonWallet(), and useTonConnectUI().

Users connect more readily when the app explains what they are about to unlock. In practice, wallet onboarding performs better when the prompt is attached to a concrete next action such as:

• continue with TON wallet sign-in
• approve a payment inside Telegram
• mint, claim, transfer, or swap
• verify balance before interacting with a contract

A connect button without context tends to create hesitation. A connect action tied to a clear task tends to move users forward.

Once a wallet connects, the UI should make the new state obvious right away.

Useful post-connect behavior usually includes:

• showing the active address and wallet identity
• revealing the next useful action immediately
• making disconnect and reconnect easy to find
• avoiding unnecessary reconnect prompts between routine actions

The first successful connection should reduce uncertainty. It should not create another blank waiting state.

The recommended transaction shape is:

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

Key implementation details matter here:

• amount is in nanoTON
• payload is a base64 BoC
• the wallet returns a BoC of the signed external message

If your onboarding flow leads directly into a payment, transfer, or contract interaction, the app should explain what the signature is for and what the user should expect after approval.

TON does not follow the usual EVM expectation of externally owned accounts. Sending to an uninitialized address may require state_init, or a wallet contract may be deployed lazily on the first outgoing transaction.

That changes how builders think about ready addresses. If your product assumes every visible address is already fully initialized and contract-ready, onboarding problems can appear as soon as users try to receive or interact.

TON finality is fast, but cross-shard settlement is not always immediate from the user’s perspective. Builders should poll by message hash rather than relying only on sender transaction state.

For onboarding, that means a signed transaction is not the end of the UX. You still need status messaging that explains whether the app is waiting for a downstream result.

TON payloads are not loose text or generic JSON blobs. They are packed into cells and slices with helpers such as beginCell() from @ton/core.

If the app treats payload creation like a generic web3 form-post problem, wallet connection may appear to work while the real contract interaction still fails.

TON Connect is especially relevant for Telegram Mini Apps, but Telegram introduces its own runtime constraints. Embedded wallet detection, iframe behavior, and CSP rules all need to be tested in the real environment rather than assumed from a normal browser tab.

Use this when the app primarily needs identity, session continuity, or wallet-aware personalization before the user makes a transaction.

Use this when users are connecting because they need to approve a payment, transfer, mint, or other action immediately.

Use this when the app lives inside Telegram and the wallet flow should feel embedded rather than redirect-heavy.

Use this when wallet connect is only the first stage in a longer flow that may include balance reads, contract interaction, guided actions, or post-sign status tracking.