# How to enable WalletConnect support in TON Connect (https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/how-to/walletconnect-support/content.md)



Adding [WalletConnect](https://walletconnect.network/) 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 [#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](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/get-started/content.md).

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](https://core.telegram.org/bots/blockchain-guidelines#ton-connect). Use TON Connect there.

## Limitations vs native TON Connect [#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.

| Feature                               | Native TON Connect | WalletConnect              |
| ------------------------------------- | ------------------ | -------------------------- |
| `sendTransaction`                     | yes                | yes (capped at 4 messages) |
| `extraCurrency` in messages           | yes                | no                         |
| `signData` (`text`, `binary`, `cell`) | yes                | yes                        |
| Gasless `signMessage`                 | yes                | no                         |
| `ton_proof`                           | yes                | yes                        |
| Embedded requests (`e` parameter)     | yes                | no                         |
| Wallet picker UX                      | TON Connect modal  | Reown WalletConnect modal  |
| Telegram Mini Apps                    | yes                | no                         |

## Setup [#setup]

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

```sh
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.`

```ts
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 initialized, 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.

<Image src="/images/ton-connect/wallet-connect.png" darkSrc="/images/ton-connect/wallet-connect.png" alt="WalletConnect entry at the bottom of the TON Connect All Wallets modal" />

## Sending requests [#sending-requests]

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

* [Send a transaction](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/how-to/send-transaction/content.md) — maps to WalletConnect's `ton_sendMessage` method.
* [Sign data](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/how-to/sign-data/content.md) — maps to WalletConnect's `ton_signData` method.
* [Disconnect](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/how-to/disconnect/content.md).

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

## When to keep WalletConnect disabled [#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](#limitations-vs-native-ton-connect).

## See also [#see-also]

* [Build a dApp with React](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/get-started/content.md)
* [Reown AppKit documentation](https://docs.reown.com/appkit/overview)