Skip to main content
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

​
Initialization

The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments: TON networks to operate on. Yet, it’s often useful to configure optional parameters right away — the following example also specifies core wallet information, TON Connect manifest, and bridge settings. 
import {
  // Main class
  TonWalletKit,
  // Network object
  Network,
  // Helper functions
  createDeviceInfo,
  createWalletManifest,
} from '@ton/walletkit';

// 0. Create a kit object.
const kit = new TonWalletKit({
  // 1. Configure networks.
  networks: {
    // Production network. All contracts and funds are real.
    [Network.mainnet().chainId]: {
      apiClient: {
        // Most commonly used, official API provider.
        url: 'https://toncenter.com',

        // A key to access higher RPS limits.
        // Get it from https://t.me/toncenter
        key: '<MAINNET_API_KEY>',
      },
    },
    // Testing network. For experiments, beta tests, and feature previews.
    [Network.testnet().chainId]: {
      apiClient: {
        url: 'https://testnet.toncenter.com',
        key: '<TESTNET_API_KEY>',
      },
    },
  },

  // 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(),

  // 4. Specify the TON Connect's bridge settings
  bridge: {
    // The main TON Connect bridge for dApp communication.
    // It is capable to withstand significant load.
    //
    // To self-host, see https://github.com/ton-connect/bridge
    bridgeUrl: 'https://connect.ton.org/bridge',
  },
});

// 5. Finally, wait for the initialization to complete
await kit.waitForReady();
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 that 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.

​
Configuration parameters

​
Required

​
networks
Record<CHAIN, NetworkConfig>
required
For one or more TON networks, configure their respective API or RPC providers to interact with.
import { Network } from '@ton/walletkit';

new TonWalletKit({
  networks: {
    // Production network. All contracts and funds are real.
    [Network.mainnet().chainId]: { // "-239"
      apiClient: {
        // Most commonly used, official API provider.
        //
        // To self-host, see:
        // * Real-time API: https://github.com/toncenter/ton-http-api-cpp
        // * Indexer: https://github.com/toncenter/ton-indexer
        // It is important to put real-time API under `/api/v2` route and indexer API under `/api/v3` route.
        url: 'https://toncenter.com',

        // Optional key to access higher RPS limits.
        key: '<MAINNET_API_KEY>',
      },
    },
    // Testing network. For experiments, beta tests, and feature previews.
    [Network.testnet().chainId]: { // "-3"
      apiClient: {
        url: 'https://testnet.toncenter.com',
        key: '<TESTNET_API_KEY>',
      },
    },
  },
  // ...later fields...
});
It is also possible to provide an entirely custom provider with its own ApiClient interface implementation.
import { Network } from '@ton/walletkit';

new TonWalletKit({
  networks: {
    [Network.testnet().chainId]: { // "-3"
      apiClient: /*  A complete ApiClient interface implementation */,
    },
  },
  // ...later fields...
});

​
Optional

​
deviceInfo
DeviceInfo
Core information and constraints of the given wallet. If not provided, defaults will be used.
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.
      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 every wallet has its own limit on the volume 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
How your wallet interacts with the TON Connect. If not provided, defaults will be used. 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 a 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. It 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;
}
​
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.Bridges are used for dApp communication — if the dApp exists in the same web environment as the wallet, then the JavaScript bridge is enough. Otherwise, use an HTTP bridge setup.
For HTTP bridge setups, use a publicly available and production-ready bridge deployed at https://connect.ton.org/bridge.
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;

  // Defaults to false
  disableHttpConnection?: boolean;

  // Settings for bridge-sdk
  heartbeatInterval?: number;
  reconnectInterval?: number;
  maxReconnectAttempts?: number;
}
​
storage
StorageConfig | StorageAdapter
How to store intermediate events.
// Either a small object:
interface StorageConfig {
  prefix?: string;
  maxRetries?: number;
  retryDelay?: number;
  allowMemory?: boolean;
}

// Or a complete StorageAdapter interface implementation:
interface StorageAdapter {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
  clear(): Promise<void>;
}
​
eventProcessor
EventProcessorConfig
How TON Connect events are processed. This is useful for background scripts in browser extensions that process incoming events and log them, but do so outside a queue.
interface EventProcessorConfig {
  disableEvents?: boolean;

  // If true, transaction events will not be emulated,
  // and their `preview` field will be undefined.
  disableTransactionEmulation?: boolean;
}
​
analytics
AnalyticsConfig
Collect and gather analytical data.
interface AnalyticsConfig {
  enabled?: boolean;

  // A web URL to send analytics data to.
  endpoint?: string;
}
​
dev
object
Extra configuration used when developing WalletKit itself. Irrelevant in other cases.

​
Next steps

Manage TON wallets

Handle connections

​
See also