Add WalletConnect support

Adding WalletConnect as a secondary connection option lets users on custodial wallets such as Fireblocks reach your TON Connect dApp without leaving their existing WalletConnect flow.

WalletConnect support ships with @tonconnect/sdk. Enabling it adds a WalletConnect entry to the standard TON Connect wallet picker. From the dApp's perspective, the same TonConnect or TonConnectUI instance handles WalletConnect sessions and TON Connect bridge sessions interchangeably.

When to use it

Add WalletConnect support when an integrator already requires WalletConnect and cannot install a TON Connect-native wallet — typically institutional custody and treasury platforms.

For everything else, prefer native TON Connect: see Build a dApp with React.

WalletConnect is not available inside Telegram Mini Apps. The wallet picker hides the WalletConnect entry when the dApp runs in TMA, in line with the Telegram blockchain guidelines. Use TON Connect there.

Limitations vs native TON Connect

WalletConnect exposes a subset of TON Connect's surface — connect, disconnect, sendTransaction, signData, and ton_proof. Newer or wallet-specific features stay on the native bridge.

Setup

WalletConnect support requires a WalletConnect (Reown) project ID. Register one at dashboard.reown.com, then install the universal connector alongside the TON Connect SDK:

npm install @tonconnect/sdk @reown/appkit-universal-connector

Call initializeWalletConnect() once, before any TonConnect or TonConnectUI instance is constructed. A second call throws Wallet Connect already initialized.

import { initializeWalletConnect } from '@tonconnect/ui-react';
import { UniversalConnector } from '@reown/appkit-universal-connector';

initializeWalletConnect(UniversalConnector, {
    projectId: '<your_project_id>',
    metadata: {
        name: 'Demo dApp',
        description: 'Demo TON dApp',
        url: 'https://example.com',
        icons: ['https://example.com/icon.png']
    }
});

Once initialised, a WalletConnect entry appears at the bottom of the All Wallets list in the TON Connect modal. Selecting it hands the connection off to Reown's modal. The connected account is delivered back through the same onStatusChange callback used for native TON Connect wallets.

Sending requests

After connection, the dApp uses the same TonConnect or TonConnectUI API regardless of which transport carries the session:

• Send a transaction — maps to WalletConnect's ton_sendMessage method.
• Sign data — maps to WalletConnect's ton_signData method.
• Disconnect.

Methods outside this set fall through to a Not implemented. response from the WalletConnect provider.

When to keep WalletConnect disabled

Keep TON Connect as the primary connection path. Enable WalletConnect support only when a real integrator needs it. Every call to initializeWalletConnect() adds a wallet entry that fails in Telegram Mini Apps and silently drops the features in Limitations vs native TON Connect.

See also

• Build a dApp with React
• Reown AppKit documentation