How to initialize the TON Connect's AppKit

If there is a dApp that uses TON Connect UI libraries, migrate that dApp to AppKit in a few steps:

• Migrate from @tonconnect/ui-react (React)
• Migrate from @tonconnect/ui (Vanilla)

Installation

Before initializing the TON Connect’s AppKit, install it with the necessary peer dependencies:

React

#     AppKit React      TanStack Query        TON Connect          Core packages         # Buffer polyfill
npm i @ton/appkit-react @tanstack/react-query @tonconnect/ui-react @ton/core @ton/crypto buffer

#     AppKit      TanStack Query       TON Connect    Core packages         # Buffer polyfill
npm i @ton/appkit @tanstack/query-core @tonconnect/ui @ton/core @ton/crypto buffer

Core packages require a Buffer polyfill. Extend the module bundle configuration according to the bundler in use:

Vite

// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
  // ...prior options...
  resolve: {
    alias: {
      buffer: 'buffer/',
    },
  },
  define: {
    Buffer: ['buffer', 'Buffer'],
  },
  // ...later options...
});

// webpack.config.js
const webpack = require('webpack');
module.exports = {
  // ...prior options...
  resolve: {
    fallback: {
      buffer: require.resolve('buffer/'),
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
    })
  ],
  // ...later options...
}

Initialization

The basic kit initialization does not require any configuration options.

React

import { AppKit, AppKitProvider } from '@ton/appkit-react';
import '@ton/appkit-react/styles.css';

const kit = new AppKit({});

// Wrap application in `AppKitProvider` and pass the `AppKit` instance.
export function App() {
  return <AppKitProvider appKit={kit}>{/* ...app... */}</AppKitProvider>;
};

import { AppKit } from '@ton/appkit';

const kit = new AppKit({});

To communicate with the blockchain, AppKit uses TON Center APIs by default. In particular, operations with assets require many API calls — obtain a key to access higher limits and prevent frequent rate limit 429 errors.

Alternative API clients and their configuration options can be supplied per network:

// Or @ton/appkit-react for React
import { AppKit, Network } from '@ton/appkit';

const kit = new AppKit({
  // Configure networks and API clients.
  networks: {
    // Mainnet is TON's production network.
    // All contracts and funds are real.
    [Network.mainnet().chainId]: {
      apiClient: {
        // Most commonly used, official API client.
        url: 'https://toncenter.com',

        // A key to access higher RPS limits.
        // Get it from https://t.me/toncenter
        key: '<MAINNET_API_KEY>',
      },
    },
  },
});

Connectors

The basic setup allows for direct API requests but is insufficient for connecting TON wallets via the TON Connect protocol. For that, configure a connector and host a public app manifest file adjusted to the needs of a given dApp.

For local development and testing, use the manifest file from this demo dApp.

React

import {
  AppKit,
  AppKitProvider,
  // Enables TON wallet connections
  createTonConnectConnector,
} from '@ton/appkit-react';
import '@ton/appkit-react/styles.css';

const kit = new AppKit({
  connectors: [
    createTonConnectConnector({
      tonConnectOptions: {
        // Public link to the application manifest JSON file.
        // For local development and testing, use the one from a demo dApp:
        manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
      },
    }),
  ],
});

// Wrap application in `AppKitProvider` and pass the `AppKit` instance.
export function App() {
  return <AppKitProvider appKit={kit}>{/* ...app... */}</AppKitProvider>;
};

import {
  AppKit,
  // Enables TON wallet connections
  createTonConnectConnector,
} from '@ton/appkit';

const kit = new AppKit({
  connectors: [
    createTonConnectConnector({
      tonConnectOptions: {
        // Public link to the application manifest JSON file.
        // For local development and testing, use the one from a demo dApp:
        manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
      },
    }),
  ],
});

Providers

The setup with connectors connects to TON wallets via services such as Tonkeeper. To enable advanced DeFi operations like asset swaps or staking, configure DeFi providers.

Supported swap providers:

• Omniston is the primary swap provider.

Supported staking providers:

• Tonstakers is the primary staking provider.

To set up all DeFi providers:

1. Install the SDK

   Swaps with Omniston require its SDK to be installed:

   npm i @ston-fi/omniston-sdk
   
2. Set up DeFi providers

   // Or @ton/appkit-react for React
   import { AppKit } from '@ton/appkit';
   
   // Omniston as a swap provider
   import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
   
   // Tonstakers as a staking provider
   import { createTonstakersProvider } from '@ton/appkit/staking/tonstakers';
   
   const kit = new AppKit({
     // DeFi providers setup
     providers: [
       // Swaps
       new OmnistonSwapProvider({
         /* custom configuration options, all optional */
       }),
       // Staking
       createTonstakersProvider({
         /* custom configuration options, all optional */
       }),
     ],
   });
   

Queries and mutations

TanStack Query is an opinionated library that simplifies fetching, caching, synchronizing and updating server state in web applications.

To enable it for React, wrap the application inside AppKitProvider in the QueryClientProvider from @tanstack/react-query:

// Additional imports
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Query client
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Do not refetch when window is refocused
      refetchOnWindowFocus: false,
    },
  },
});

// ...AppKit initialization as shown prior...

// Modified entrypoint
export function App() {
  return (
    <AppKitProvider appKit={kit}>
      <QueryClientProvider client={queryClient}>
        {/* ...app... */}
      </QueryClientProvider>
    </AppKitProvider>
  );
}

Complete setup

The following initialization example sets up everything at once:

React

// AppKit
import {
  AppKit,
  AppKitProvider,
  Network,
  // Wallet connector
  createTonConnectConnector,
} from '@ton/appkit-react';

// Styles
import '@ton/appkit-react/styles.css';

// DeFi providers
import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
import { createTonstakersProvider } from '@ton/appkit/staking/tonstakers';

// TanStack Query
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Query client
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Do not refetch when window is refocused
      refetchOnWindowFocus: false,
    },
  },
});

// Initialization
const kit = new AppKit({
  // 1. Configure networks and API clients.
  networks: {
    // Production network. All contracts and funds are real.
    [Network.mainnet().chainId]: {
      apiClient: {
        // Most commonly used, official API client.
        url: 'https://toncenter.com',

        // A key to access higher RPS limits.
        // Get it from https://t.me/toncenter
        key: '<MAINNET_API_KEY>',
      },
    },
  },
  // 2. Configure connectors.
  connectors: [
    // Enables connections with TON wallet services, such as Tonkeeper or MyTonWallet.
    createTonConnectConnector({
      tonConnectOptions: {
        // Public link to the application manifest JSON file.
        // For local development and testing, use the one from a demo dApp:
        manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
      },
    }),
  ],
  // 3. Configure DeFi providers.
  providers: [
    new OmnistonSwapProvider(),
    createTonstakersProvider(),
  ],
});

// 4. Wrap the rest of the app in a QueryClientProvider and an AppKitProvider.
export function App() {
  return (
    <AppKitProvider appKit={kit}>
      <QueryClientProvider client={queryClient}>
        {/* ...app... */}
      </QueryClientProvider>
    </AppKitProvider>
  )
};

// AppKit
import {
  AppKit,
  Network,
  // Wallet connector
  createTonConnectConnector,
} from '@ton/appkit';

// DeFi providers
import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
import { createTonstakersProvider } from '@ton/appkit/staking/tonstakers';

// Initialization
const kit = new AppKit({
  // 1. Configure networks and API clients.
  networks: {
    // Production network. All contracts and funds are real.
    [Network.mainnet().chainId]: {
      apiClient: {
        // Most commonly used, official API client.
        url: 'https://toncenter.com',

        // A key to access higher RPS limits.
        // Get it from https://t.me/toncenter
        key: '<MAINNET_API_KEY>',
      },
    },
  },
  // 2. Configure connectors.
  connectors: [
    // Enables connections with TON wallet services, such as Tonkeeper or MyTonWallet.
    createTonConnectConnector({
      tonConnectOptions: {
        // Public link to the application manifest JSON file.
        // For local development and testing, use the one from a demo dApp:
        manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
      },
    }),
  ],
  // 3. Configure DeFi providers.
  providers: [
    new OmnistonSwapProvider(),
    createTonstakersProvider(),
  ],
});

Dynamic configuration

AppKit instance can be dynamically extended with new connectors and providers.

Add new connectors

To add a new connector, call the .addConnector() method on the initialized AppKit object:

kit.addConnector(connector);

Add new providers

To add a new provider, call the .registerProvider() method on the initialized AppKit object:

kit.registerProvider(provider);

To specifically add a swap provider, register it via kit.swapManager:

kit.swapManager.registerProvider(swapProvider);

Configuration parameters

networks · Record<CHAIN, NetworkConfig>

For one or more TON networks, configure their respective API or RPC providers to interact with.

TypeScript

// Or @ton/appkit-react for React
import { Network } from '@ton/appkit';

new AppKit({
  networks: {
    // Production network. All contracts and funds are real.
    [Network.mainnet().chainId]: { // "-239"
      apiClient: {
        // Most commonly used, official API client.
        //
        // 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.

TypeScript

// Or @ton/appkit-react for React
import { Network } from '@ton/appkit';

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

connectors · Connector[] | undefined

Array of connectors that enable wallet connections. The primary connector is TonConnectConnector, which is created by dedicated function.

Each connector must expose the following methods:

• initialize() — creates the connector, restores connections, sets up event listeners.
• destroy() — cleans up connector resources.
• connectWallet() — connects a wallet through the UI.
• disconnectWallet() — disconnects a wallet.
• getConnectedWallets() — lists connected wallets.

Additionally, each connector has metadata that can be displayed in the UI:

interface ConnectorMetadata {
  /**
   * Connector name
   */
  name: string;
  /**
   * Connector icon URL
   */
  iconUrl?: string;
}

providers · Providers[] | undefined

Array of DeFi providers that enable additional functionality, such as asset swaps via Omniston.

Relation to TON Connect libraries

Lower-level TON Connect libraries, such as @tonconnect/ui-react and @tonconnect/ui, only give access to wallet services via the TON Connect protocol and basic facilities to query connected TON wallets with direct API calls.

AppKit builds on the foundation provided by these libraries and extends functionality with convenient components, hooks, and functions. It enables balance tracking and asset management, gives ready-made React UI components for common cases, handles API-related state management, and even registers DeFi integrations for advanced use cases.

If there is an existing dApp that uses either @tonconnect/ui-react or @tonconnect/ui, consider migrating to AppKit to simplify development and reduce boilerplate.

Migrate from @tonconnect/ui-react

Before migrating, install AppKit and peer packages and add necessary polyfills.

1. Ensure the TON Connect UI package is of the latest version

   Ensure that TON Connect packages are of the latest version:

   npm up @tonconnect/ui-react --save
   
2. Initialize AppKit and replace TonConnectUIProvider

   Use AppKitProvider in place of the TonConnectUIProvider:

   import {
     AppKit,
     // Replaces <TonConnectUIProvider>
     AppKitProvider,
     // Wallet connector
     createTonConnectConnector,
   } from '@ton/appkit-react';
   import '@ton/appkit-react/styles.css';
   
   const kit = new AppKit({
     connectors: [
       createTonConnectConnector({
         // In place of props on the TonConnectUIProvider
         tonConnectOptions: {
           // Public link to the application manifest JSON file.
           // For local development and testing, use the one from a demo dApp:
           manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
         },
       }),
     ],
   });
   
   export function App() {
     return (
       // In place of the TonConnectUIProvider
       <AppKitProvider appKit={kit}>
         {/* ...rest of the app... */}
       </AppKitProvider>
     );
   }
   

   Refer to the complete initialization setup for all the possible AppKit configuration options.

3. Keep existing hooks as is

   The AppKitProvider bridges to TON Connect under the hood. Existing few @tonconnect/ui-react hooks, such as useTonAddress(), useTonWallet(), and others, will continue to work inside the AppKitProvider automatically.

Migrate from @tonconnect/ui

Before migrating, install AppKit and peer packages and add necessary polyfills.

1. Ensure the TON Connect UI package is of the latest version

   npm up @tonconnect/ui --save
   
2. Initialize AppKit and reuse TonConnectUI object

   It is possible to reuse the existing TonConnectUI object when configuring AppKit connectors:

   import {
     AppKit,
     createTonConnectConnector,
   } from '@ton/appkit';
   
   const kit = new AppKit({
     connectors: [
       createTonConnectConnector({
         // Pass the existing TonConnectUI instance object
         tonConnectUI
       }),
     ]
   });
   

   One can also extend the existing AppKit instance dynamically:

   // Passing the existing TonConnectUI instance object
   kit.addConnector(createTonConnectConnector({ tonConnectUI }));
   

   Refer to the complete initialization setup for all the possible AppKit configuration options.

3. Replace method calls with exported functions

   Instead of consolidating everything within the instantiated TonConnectUI object, AppKit offers several tree-shakable functions that enhance and expand the capabilities of the existing TonConnectUI functionality. Refer to relevant how-to pages for concrete examples.

Next steps

Work with Toncoin

See also

• AppKit overview
• TON Connect’s app manifest
• TON Connect overview