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.

Prerequisites

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

1. TON Connect Project

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 ID

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.

Don’t have a project ID?Head over to WalletConnect Dashboard and create a new project now!

Get started

3. Allowlist Your Domains

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

Requests from origins not in the allowlist will be denied. Make sure to add all domains where your app will be deployed.

Enable WalletConnect

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 Options

The initializeWalletConnect function accepts the following configuration options:

Option	Type	Required	Description
`projectId`	`string`	Yes	Your WalletConnect project ID from the Dashboard
`metadata.name`	`string`	Yes	The name of your application
`metadata.description`	`string`	Yes	A brief description of your application
`metadata.url`	`string`	Yes	The URL of your application
`metadata.icons`	`string[]`	Yes	An array of icon URLs for your application

Example Implementation

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_proof`

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 Connection

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 Result

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);
}

The ton_proof result is not available in onStatusChange when using WalletConnect. You must read it from session.authentication directly after the connection is established.

Next Steps

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.

Getting Started

Installation

Guides

TON Connect WalletConnect Integration

Prerequisites

1. TON Connect Project

2. WalletConnect Project ID

Get started

3. Allowlist Your Domains

Enable WalletConnect

Configuration Options

Example Implementation

Handling `ton_proof`

Requesting `ton_proof` During Connection

Reading the Proof Result

Next Steps

​Prerequisites

​1. TON Connect Project

​2. WalletConnect Project ID

Get started

​3. Allowlist Your Domains

​Enable WalletConnect

​Configuration Options

​Example Implementation

​Handling ton_proof

​Requesting ton_proof During Connection

​Reading the Proof Result

​Next Steps

Prerequisites

1. TON Connect Project

2. WalletConnect Project ID

3. Allowlist Your Domains

Enable WalletConnect

Configuration Options

Example Implementation

Handling `ton_proof`

Requesting `ton_proof` During Connection

Reading the Proof Result

Next Steps