How to Connect Tonkeeper to a TON dApp

Wallet Preparation and Network Verification

1. Install the official Tonkeeper application from tonkeeper.com or verified app stores for iOS, Android, or desktop platforms.

2. Launch Tonkeeper and confirm it is operating on the TON mainnet—verify this by checking the network indicator in the top bar; if it displays “Testnet”, access Settings, tap the Tonkeeper logo five times to open Developer Menu, then toggle to mainnet.

3. Ensure the wallet contains at least 0.1 TON to cover initial transaction fees and contract deployment costs required by most dApps.

4. Back up the 24-word recovery phrase in a secure offline location—this step is irreversible and mandatory before any on-chain interaction.

5. Confirm that no third-party extensions or overlays are interfering with the wallet’s UI rendering or signature prompts.

Connection Initiation via dApp Interface

1. Navigate to the target TON-based dApp using a supported browser such as Chrome, Edge, or Safari with JavaScript enabled.

2. Locate and click the “Connect Wallet” button—typically positioned in the top-right corner of the dApp interface.

3. Select “Tonkeeper” from the displayed wallet list; avoid scanning QR codes unless explicitly instructed by the dApp’s connection flow.

4. A pop-up modal will appear inside Tonkeeper requesting permission to share your public address and sign a session request—tap “Approve”.

5. The dApp will display your connected address and may trigger an automatic balance sync; no private key or seed phrase is ever transmitted.

Address Format and Compatibility Handling

1. Tonkeeper generates addresses in bounceable format by default (e.g., EQB4c1b2ede12aa76f4a44353944258bcc8f99e9c7c474711a152c78b43218e296), which supports automatic error correction and is preferred for user-facing interactions.

2. Some dApps require non-bounceable addresses for smart contract calls—Tonkeeper provides both variants under “Account Info” > “Copy Address” > toggle option.

3. Verify that the dApp correctly parses workchain ID (0 for base chain) and account ID components; mismatched workchain handling causes silent connection failures.

4. If the dApp uses TonConnect protocol v2, ensure Tonkeeper version is ≥4.12.0—older versions lack support for multi-signature session handshakes.

5. Do not manually edit or truncate address strings—the checksum and prefix encoding are cryptographically bound to the underlying public key.

Signature and Transaction Authorization Flow

1. When initiating a transaction or data signing request, the dApp sends a structured payload containing method name, parameters, and expiration timestamp.

2. Tonkeeper displays a native confirmation screen showing the exact operation type (sendMessage or signData), destination address, amount, and attached memo.

3. Users must explicitly approve each action—no batch approvals or auto-signing policies are permitted by design.

4. Upon approval, Tonkeeper computes the Ed25519 signature over the canonicalized payload and returns it alongside the signed message hash to the dApp.

5. Failed signatures always result in immediate rejection at the blockchain level; no partial or fallback execution occurs.

Troubleshooting Common Connection Failures

1. If the wallet fails to appear in the connector list, clear browser cache and disable ad-blockers or privacy extensions that filter WebSockets or injected scripts.

2. Persistent “Invalid Session” errors indicate expired TonConnect pairing—reconnect by clicking “Disconnect Wallet” in the dApp, then reinitiate connection.

3. Blank or frozen confirmation modals usually stem from outdated Tonkeeper versions—update via official app store or tonkeeper.com/download.

4. Address mismatches between dApp display and Tonkeeper’s “Account Info” suggest incorrect network context—double-check that both dApp backend and wallet operate on identical TON network endpoints.

5. Repeated timeout messages during signature requests point to unstable local internet or ISP-level WebSocket blocking—switch to mobile data or enable Tor mode in Tonkeeper settings.

Frequently Asked Questions

Q: Can I connect Tonkeeper to multiple dApps simultaneously without re-approval?A: Yes—Tonkeeper maintains persistent session keys per dApp domain; each new origin requires one-time pairing but subsequent interactions skip re-authentication unless manually revoked.

Q: Does connecting to a dApp grant it access to my transaction history or balance details?A: No—only the public address is shared; all balance and history queries must be performed via TON API endpoints controlled by the user’s consent and explicit RPC calls.

Q: Why does some dApp show “Unsupported Wallet” even when Tonkeeper is selected?A: This occurs when the dApp enforces legacy TonConnect v1 or custom RPC wrappers incompatible with Tonkeeper’s current adapter layer—check the dApp’s documentation for minimum supported SDK versions.

Q: Is it safe to connect Tonkeeper to dApps hosted on non-HTTPS domains?A: No—Tonkeeper blocks connections to HTTP origins entirely; only TLS-secured domains with valid certificates are permitted to initiate wallet sessions.