Integration

TON Connect, and the difference between connected and proven

TON Connect is the standard protocol for connecting a user wallet to a Telegram Mini App or bot and requesting transactions. A connection alone proves nothing about wallet ownership — you must request and verify a signed proof, and a great many integrations skip that step.

TON Connect integration: auth, limits and availability

Auth model: HMAC-signed
Sessions: Per app, restorable, but not permanent
GCC availability: A protocol, not a licensed service; no jurisdictional onboarding
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

TON Connect solves a genuinely awkward problem well. A user inside Telegram taps once, their wallet opens, they approve, and they are back — no address copying, no network selection, no browser extension. For Telegram-native crypto products that flow is the difference between a working product and a demo, and the protocol handles the hard parts of session establishment and transaction requests.

The mistake that recurs is treating a connection as an authentication. A wallet address arriving from the client is a claim: the client says this address is connected. Nothing about receiving it proves the user controls the corresponding key, and a backend that grants entitlements based on a claimed address can be given any address at all — including one holding the tokens your allowlist requires.

The protocol provides the answer. A connection request can include a proof item, which the wallet signs, and the server verifies that signature against the address and a payload it generated. That single step is the difference between "the client told us an address" and "this user controls this wallet". Everything that grants access, computes voting weight or attributes a payment must sit behind it.

How the data actually moves

The nonce is generated server-side per connection attempt, so a proof captured from one session cannot be replayed into another.

Two independent verifications run server-side and both are required. The Mini App's `initData` is HMAC-verified against the bot token to establish which Telegram user is present, and the TON Connect proof is signature-verified against a server-generated payload to establish which wallet they control. Either alone is insufficient: `initData` says who is in the chat, the proof says who owns the wallet, and the binding between them is what you actually need.

Auth model: HMAC-signed requests

Their limits, and what they mean for you

A TON Connect session is established per app and can be restored, but is not permanent.

Users are reconnected periodically. A design assuming an indefinite session produces a bot that silently stops working for returning users with no error anyone sees.

The connect proof payload is generated by the application and echoed back signed.

It must be a server-generated nonce with a short lifetime, stored and consumed once. A constant payload turns the proof into a replayable token, which is strictly worse than no proof because it looks like security.

A transaction request returns when the wallet has sent it, not when the chain has confirmed it.

Fulfilment waits for on-chain confirmation, not for the wallet's response. The wallet telling you it sent something is not the network agreeing it happened.

Wallet support for optional protocol features varies between wallet apps.

Test against the wallets your audience actually uses rather than one. Behaviour that works in the most popular wallet is not a guarantee for the second and third.

How it fails, and what happens when it does

The user approves in their wallet app and never returns to Telegram.

On mobile the return journey is the weakest link in the whole flow. State lives server-side keyed by the connection, so reopening the Mini App resumes rather than restarts.

A proof is submitted for an address the user does not control.

Signature verification rejects it. This is exactly the attack the proof exists to prevent, and it is trivially successful against any integration that accepts a claimed address.

A transaction is sent but the app never learns about it.

Reconciliation watches the chain for expected transactions rather than relying on the wallet reporting back. The chain is the source of truth and is also the only party that cannot lose the message.

The same proof is replayed against a second session.

Nonces are single-use and short-lived, so replay fails. Without that, one captured proof authenticates indefinitely.

Availability in the UAE and the wider GCC

Global

TON Connect is a protocol rather than a licensed service, so there is no jurisdictional onboarding. Whatever you build on it may still be regulated.

United Arab Emirates

Widely used by Dubai-based projects. Note that holding or transmitting user funds is a VARA-regulated activity regardless of which protocol moves them.

Wallet coverage

Supported by the major TON wallets including the one built into Telegram. Confirm the specific wallets your audience uses during scoping, since feature support is not uniform.

Non-custodial only

TON Connect connects a wallet the user controls. It is not a custody solution and does not reduce the obligations that come with holding funds yourself.

When not to use this integration

Your users do not have TON wallets. The connection flow is excellent and reaches nobody who is not already there.
You need custody of user funds. TON Connect connects a wallet the user controls, which is a different product and a smaller obligation.
You are selling digital goods to a general Telegram audience. Stars are simpler for both sides and need no wallet at all.
You intend to skip proof verification. Then you have not built authentication, and it is better to know that before launch than after.

What it runs on

Component	Version	Why
@tonconnect/sdk	3.x	Connection establishment and transaction requests in the Mini App.
Cloudflare Workers	current	Nonce issuance, proof verification and chain watching.
Cloudflare D1	current	Verified wallet bindings, nonces and expected transactions.
Telegram Mini Apps	Bot API 9.x	The surface the connection happens in, with initData verified alongside.

Questions that come up during scoping

Is a connected wallet the same as a verified one?

No, and conflating them is the most consequential mistake in TON Connect integrations. A connection means the client reported an address. Verification means the wallet signed a payload you generated and you checked the signature. Only the second one proves anything.

Why must the proof payload come from the server?

So it cannot be replayed. A server-generated single-use nonce with a short lifetime means a captured proof is worthless a moment later. A constant payload turns the proof into a bearer token that never expires.

Do we still need to verify initData if we verify the wallet proof?

Yes. They establish different facts — initData says which Telegram user is present, the proof says which wallet they control. The binding between the two is the thing you actually want, and it needs both halves.

When can we treat a payment as complete?

On chain confirmation, not on the wallet returning success. The wallet is telling you it sent something; only the network can tell you it happened, and that gap is where double-spend losses live.

What happens if the user does not come back from their wallet app?

Connection state is held server-side, so reopening the Mini App resumes rather than restarts. On mobile this return journey is the least reliable step in the flow and is worth designing for explicitly.

Does using TON Connect avoid regulation?

No. It changes who holds the keys, which genuinely reduces your obligations, but whatever you are doing with those transactions may still be regulated. In Dubai, virtual asset activity sits under VARA regardless of protocol.