TON Connect WalletConnect Integration

This guide explains how to enable WalletConnect support in your TON Connect application, allowing users to connect with WalletConnect-compatible wallets.

PrerequisitesCopy Anchor Link

Before enabling WalletConnect in your TON Connect application, ensure you have the following:

1. TON Connect ProjectCopy Anchor Link

You should have an existing TON Connect project initialized with the @tonconnect/sdk package. If you haven't set up TON Connect yet, please refer to the TON Connect documentation to get started.

2. WalletConnect Project IDCopy Anchor Link

Create a new project on the WalletConnect Dashboard at https://dashboard.walletconnect.com and obtain a new project ID. You will need this project ID to initialize WalletConnect in your application.

3. Allowlist Your DomainsCopy Anchor Link

To help prevent malicious use of your project ID, you are strongly encouraged to set an allowlist of origins where your project ID is used. You can manage your allowlist in the WalletConnect Dashboard under the project settings.

The allowlist supports a list of origins in the format [scheme://]<hostname[:port]>. Using localhost (or 127.0.0.1) is always permitted, and if the allowlist is empty, all origins are allowed. Updates take 15 minutes to apply.

Examples of possible origins in the allowlist:

• example.com - allows https://example.com or http://example.com but not https://www.example.com
• https://example.com - allows https://example.com but not http://example.com
• https://*.example.com - allows https://www.example.com but not https://example.com

Enable WalletConnectCopy Anchor Link

To enable WalletConnect in your TON Connect application, use the initializeWalletConnect() function from the @tonconnect/sdk package along with the UniversalConnector from @reown/appkit-universal-connector.

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

initializeWalletConnect(UniversalConnector, {
  projectId: 'YOUR_PROJECT_ID',
  metadata: {
    name: 'My DApp',
    description: 'My awesome DApp',
    url: 'https://mydapp.com',
    icons: ['https://mydapp.com/icon.png']
  }
});

Configuration OptionsCopy Anchor Link

The initializeWalletConnect function accepts the following configuration options:

Example ImplementationCopy Anchor Link

Here's a complete example of integrating WalletConnect into a TON Connect application:

import { TonConnect } from '@tonconnect/sdk';
import { initializeWalletConnect } from '@tonconnect/sdk';
import { UniversalConnector } from '@reown/appkit-universal-connector';
import {
  TonConnectUIProvider,
  TonConnectButton,
} from '@tonconnect/ui-react';

// Initialize WalletConnect support
initializeWalletConnect(UniversalConnector, {
  projectId: 'YOUR_PROJECT_ID',
  metadata: {
    name: 'My TON DApp',
    description: 'A decentralized application on TON',
    url: 'https://mytonapp.com',
    icons: ['https://mytonapp.com/icon.png']
  }
});


export function App() {
  // Create TON Connect instance
  const tonConnect = new TonConnect({
    manifestUrl: 'https://mytonapp.com/tonconnect-manifest.json'
  });

  return (
    <div className="pages">
      <h1>WalletConnect + TON React Example</h1>
      <TonConnectUIProvider connector={tonConnect}>
        <TonConnectButton />
      </TonConnectUIProvider>
    </div>
  )
}

Handling ton_proofCopy Anchor Link

When using TON Connect with WalletConnect, ton_proof is requested and returned as part of the connection response using the CAIP-222 authentication flow. The proof payload is passed via the authentication parameter during connect(), and the signed proof is available on session.authentication after the connection is established.

Requesting ton_proof During ConnectionCopy Anchor Link

To request ton_proof during the WalletConnect session establishment, pass the authentication parameter when calling connect() on the underlying UniversalConnector provider:

import { UniversalConnector } from '@reown/appkit-universal-connector';

const connector = await UniversalConnector.init({
  projectId: 'YOUR_PROJECT_ID',
  metadata: {
    name: 'My TON DApp',
    description: 'A decentralized application on TON',
    url: 'https://mytonapp.com',
    icons: ['https://mytonapp.com/icon.png']
  },
  networks: [{
    namespace: 'ton',
    chains: [tonMainnet],
    methods: ['ton_sendMessage', 'ton_signData'],
    events: []
  }]
});

const session = await connector.provider.connect({
  optionalNamespaces: {
    ton: {
      methods: ['ton_sendMessage', 'ton_signData'],
      chains: ['ton:-239'],
      events: []
    }
  },
  authentication: [{
    uri: 'https://mytonapp.com',
    domain: 'mytonapp.com',
    chains: ['ton:-239'],
    nonce: '<random_nonce>',
    ttl: 86400,
    statement: '<ton_proof_payload>'
  }]
});

Reading the Proof ResultCopy Anchor Link

After a successful connection, the proof result is available on session.authentication as an array of CAIP-222 Cacao objects:

const authenticationResults = session?.authentication;

if (authenticationResults && authenticationResults.length > 0) {
  // Each result is a Cacao object containing the signed proof
  const proof = authenticationResults[0];
  console.log('ton_proof result:', proof);
}

Next StepsCopy Anchor Link

After integrating WalletConnect into your TON Connect application, users will be able to connect using any WalletConnect-compatible wallet. For more information about TON-specific RPC methods supported by WalletConnect, see the TON Chain Support documentation.