How to initialize the TON Connect's WalletKit on the Web platform

Before initializing the TON Connect’s WalletKit, install it in your web project:

npm i @ton/walletkit

Alternatively, explore the complete demo wallet with WalletKit integration:

Demo wallet, deployed

Demo wallet, GitHub repository

Initialization

The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments. One needs to pick a TON network to operate on, provide necessary device and wallet manifest configurations.

import {
  TonWalletKit,
  CHAIN,
  createDeviceInfo,
  createWalletManifest,
} from '@ton/walletkit';

// 0. Create a kit object
const kit = new TonWalletKit({
  // 1. Pick a network — prefer CHAIN.TESTNET during development,
  //    and only switch to CHAIN.MAINNET and production deployments
  //    after rigorous testing.
  network: CHAIN.TESTNET,

  // 2. Specify core information and constraints of the given wallet.
  deviceInfo: createDeviceInfo({
    // Version of your wallet
    appVersion: '0.0.1',

    // The rest of the params will have default values set for you,
    // including the features your wallet should support,
    // maximum supported TON Connect protocol version,
    // human-readable name of your wallet,
    // and a current platform ('browser').
  }),

  // 3. Specify the TON Connect's wallet manifest.
  //    The following function provides initial defaults,
  //    but you may want to specify some custom values,
  //    such as the human-readable name of your wallet or its icon image url.
  walletManifest: createWalletManifest(),
});

See also: TON Connect’s wallet manifest.

Web only!

The given example must be invoked in browser environments only. To run it locally with Node.js or other JS runtimes, set storage.allowMemory to true. It enables a built-in storage adapter for non-browser environments which do not have localStorage available.

const kit = new TonWalletKit({
  // ...prior fields...
  storage: { allowMemory: true },
  // ...later fields...
});

Remember to disable this adapter in web environments or provide a dedicated storage adapter wrapper to switch between environments.

TON wallet initialization

The configuration before is enough to outline necessary wallet information and initialize the WalletKit, but it isn’t enough for deeper interactions with the blockchain. For that, you need at least one TON wallet contract to be set up.

You may load or create a new TON wallet using one of these options:

Create a TON wallet from a mnemonic

Create a TON wallet from a private key

Create a TON wallet with a custom signer

Note that you can provide multiple TON wallets to WalletKit and switch between them as needed.

await kit.addWallet(tonWalletConfig1);
await kit.addWallet(tonWalletConfig2);
// ...
await kit.addWallet(tonWalletConfigN);

From mnemonic

To initialize a TON wallet from an existing BIP-39 or TON-specific mnemonic seed phrase, use the createWalletInitConfigMnemonic() function of WalletKit.

Never specify the mnemonic phrase directly in your code. It is a “password” to your wallet and all its funds.

Instead, prefer sourcing the seed phrase from a secure storage, backend environment variables, or a special .env file that is Git-ignored and handled with care.

import {
  CHAIN,
  createWalletInitConfigMnemonic,
} from '@ton/walletkit';

const walletConfig = createWalletInitConfigMnemonic({
  // (REQUIRED)
  // A 12 or 24-word seed phrase obtained with general BIP-39 or TON-specific derivation.
  // The following value assumes a corresponding MNEMONIC environment variable
  // that contains 24 space-separated seed phrase words as a single string:
  mnemonic: process.env.MNEMONIC.split(" "), // list of 24 strings

  // Type of derivation used to produce a mnemonic.
  // If you've used a pure BIP-39 derivation, specify 'bip-39'.
  // Otherwise, specify 'ton'.
  // Defaults to: 'ton'
  mnemonicType: 'ton',

  // Specify an ID for this wallet when you plan
  // on adding more than one wallet to the kit.
  walletId: 0,

  // Wallet contract version
  // Defaults to: v5r1
  version: 'v5r1',

  // TON Blockchain network.
  // Defaults to: CHAIN.MAINNET
  network: CHAIN.TESTNET,
});

// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);

If you don’t yet have a mnemonic for an existing TON wallet or you want to create a new one, you can generate a TON-specific mnemonic with the CreateTonMnemonic() function. However, it’s crucial to use that function only once per wallet and then save it securely.

You must NOT invoke this function amidst the rest of your project code.

The following is an example of a simple one-off standalone script to produce a new mnemonic that then should be saved somewhere private:

import { CreateTonMnemonic } from '@ton/walletkit';

console.log(await CreateTonMnemonic()); // word1, word2, ..., word24

From private key

Private keys are sensitive data!

Handle private keys carefully. Use test keys, keep them in a secure keystore, and avoid logs or commits.

To initialize a TON wallet from an existing private key, use the createWalletInitConfigPrivateKey() function of WalletKit.

If there is a mnemonic, one can convert it to an Ed25519 key pair with public and private key by using the MnemonicToKeyPair().

import {
  CHAIN,
  createWalletInitConfigPrivateKey,
  MnemonicToKeyPair,
} from '@ton/walletkit';

// Pass either a TON-specific ('ton')
// or a general BIP-39 ('bip-39') seed phrase to obtain a key pair.
const keyPair = await MnemonicToKeyPair(
  // The following value assumes a corresponding MNEMONIC environment variable
  // that contains 24 space-separated seed phrase words as a single string:
  process.env.MNEMONIC.split(" "),
  'ton',
);

const walletConfig = createWalletInitConfigPrivateKey({
  // (REQUIRED)
  // Private key as a hex-encoded string or Uint8Array of bytes.
  privateKey: keyPair.secretKey,

  // Specify an ID for this wallet when you plan
  // on adding more than one wallet to the kit.
  walletId: 0,

  // Wallet contract version
  // Defaults to: v5r1
  version: 'v5r1',

  // TON Blockchain network.
  // Defaults to: CHAIN.MAINNET
  network: CHAIN.TESTNET,
});

// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);

From signer

To provide a custom signing mechanism as an alternative to using a mnemonic phrase or a private key, use the createWalletInitConfigSigner() function of WalletKit.

In that case, you would need to pass a public key and your custom signing function of type WalletSigner. It should take the Uint8Array of data bytes and then asynchronously produce an Uint8Array signature.

This approach is useful if you want to maintain full control over the signing process, such as when using a hardware wallet or signing data on the backend.

import {
  CHAIN,
  createWalletInitConfigSigner,
  type Hash,
} from '@ton/walletkit';

const walletConfig = createWalletInitConfigSigner({
  // (REQUIRED)
  // Public key as a hex-encoded string (Hash) or Uint8Array of bytes.
  publicKey: "..." as Hash,

  // (REQUIRED)
  // Custom signing function.
  // The following is a simple demo of such function.
  sign: async (data: Uint8Array): Promise<Uint8Array> => data,

  // Specify an ID for this wallet when you plan
  // on adding more than one wallet to the kit.
  walletId: 0,

  // Wallet contract version
  // Defaults to: v5r1
  version: 'v5r1',

  // TON Blockchain network.
  // Defaults to: CHAIN.MAINNET
  network: CHAIN.TESTNET,
});

// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);

Configuration parameters

Required

network · CHAIN.TESTNET | CHAIN.MAINNET · required

The TON network to use.

import { CHAIN } from '@ton/walletkit';

// Testing network of TON Blockchain. For experiments, beta tests and feature previews.
CHAIN.TESTNET; // "-3"

// Production network of TON Blockchain. All contracts and funds are real.
CHAIN.MAINNET; // "-239"

deviceInfo · DeviceInfo · required

Core information and constraints of the given wallet.

interface DeviceInfo {
  // Name of the wallet.
  appName: string;

  // The platform it works on. Select 'browser' for the web wallets.
  platform: 'iphone' | 'ipad' | 'android' | 'windows' | 'mac' | 'linux' | 'browser';

  // The current wallet version.
  appVersion: string;

  // Latest protocol version to use.
  maxProtocolVersion: number;

  // Which features are supported in the wallet.
  features: Feature[];
}

There, Feature type is defined as:

type Feature =
  // Wallet can send transactions.
  // This is a deprecated definition used in old versions of TON Connect protocol.
  | "SendTransaction"
  | {
      // Wallet can send transactions.
      name: "SendTransaction";

      // Max number of messages that can be sent in a single transaction.
      // Depends on the TON wallet used, because different kinds can handle
      // different number of messages. For example,
      // - ledger wallet would only handle 1 message per transaction
      // - wallet v4r2 handles up to 4 messages
      // - wallet v5r1 handles up to 255 messages
      maxMessages: number;

      // Are messages sending extra-currencies supported?
      extraCurrencySupported?: boolean;
    }
  | {
      // Wallet can sign data.
      name: "SignData";

      // A type of data to sign.
      // Either of: "text", "binary", "cell".
      types: SignDataType[];
    }

The maxMessages number depends on the TON wallet used, because different kinds can handle different number of messages.

For example,

• Ledger wallet would only handle 1 message per transaction
• Wallet v4r2 handles up to 4 messages
• Wallet v5r1 handles up to 255 messages

walletManifest · WalletInfo · required

How your wallet interacts with the TON Connect. This field is closely related to the corresponding JSON manifest file.

interface WalletInfo {
  /**
   * Human-readable name of the wallet.
   */
  name: string;

  /**
   * ID of the wallet, equals to the `appName` property of the `deviceInfo`.
   */
  appName: string;

  /**
   * Url to the icon of the wallet. Resolution 288×288px. On non-transparent background, without rounded corners. PNG format.
   */
  imageUrl: string;

  /**
   * Will be used in the protocol later.
   */
  tondns?: string;

  /**
   * Info or landing page of your wallet. May be useful for TON newcomers.
   */
  aboutUrl: string;

  /**
   * List of features supported by the wallet.
   */
  features?: Feature[];

  /**
   * OS and browsers where the wallet could be installed
   */
  platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];

  /**
   * Base part of the wallet universal url. The link should support TON Connect parameters: https://github.com/ton-connect/docs/blob/main/bridge.md#universal-link.
   */
  universalLink: string;

  /**
   * Native wallet app deep link. The link should support TON Connect parameters: https://github.com/ton-connect/docs/blob/main/bridge.md#universal-link.
   */
  deepLink?: string;

  /**
   * Url of the wallet's implementation of the HTTP bridge: https://github.com/ton-connect/docs/blob/main/bridge.md#http-bridge.
   */
  bridgeUrl: string;

  // JS-injectable wallet information

  /**
   * If the wallet handles JS Bridge connection, specifies the binding for the bridge object accessible through window. Example: the key "tonkeeper" means the bridge can be accessed as window.tonkeeper.
   */
  jsBridgeKey: string;

  /**
   * Indicates if the wallet currently is injected to the webpage.
   */
  injected: boolean;

  /**
   * Indicates if the dapp is opened inside this wallet's browser.
   */
  embedded: boolean;
}

Optional

apiClient · object | ApiClient

Which API or RPC provider to use to interact with TON Blockchain.

// Either a small object:
const _: {
  // Defaults to "https://toncenter.com".
  url?: string;

  // A key to access higher RPS limits.
  key?: string;
}
// Or a complete ApiClient interface implementation.

bridge · BridgeConfig

Connectivity options: either an HTTP or JavaScript bridge setup. The former’s bridgeUrl points to the publicly exposed bridge URL, while the latter’s jsBridgeKey points to the property name within the window object on the same web page.

interface BridgeConfig {
  // Defaults to `walletInfo`'s `bridgeUrl`, if it exists
  bridgeUrl?: string;

  // Defaults to true if `walletInfo`'s `jsBridgeKey` exists
  enableJsBridge?: boolean;

  // Defaults to `walletInfo`'s `jsBridgeKey`, if it exists
  jsBridgeKey?: string;

  // Settings for bridge-sdk
  heartbeatInterval?: number;
  reconnectInterval?: number;
  maxReconnectAttempts?: number;
}

storage · object | StorageAdapter

How to store intermediate events.

// Either a small object:
const _: {
  prefix?: string;
  cacheTimeout?: number;
  maxCacheSize?: number;
  allowMemory?: boolean;
}
// Or a complete StorageAdapter interface implementation.

validation · object

Strictness and wallet checks.

{
  strictMode?: boolean,
  allowUnknownWalletVersions?: boolean,
}

eventProcessor · EventProcessorConfig

How TON Connect events are processed.

interface EventProcessorConfig {
  disableEvents?: boolean;
}

analytics · AnalyticsConfig

Collect and gather analytical data.

interface AnalyticsConfig {
  enabled?: boolean;

  // A web URL to send analytics data to.
  endpoint?: string;
}

Next steps

Handle connection requests

See also

WalletKit overview

TON Connect's wallet manifest

TON Connect overview