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

Installation

Before initializing the TON Connect’s AppKit, install it with the necessary peer dependencies:
#     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
Core packages require a Buffer polyfill. Extend the module bundle configuration according to the bundler in use:
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
  // ...prior options...
  resolve: {
    alias: {
      buffer: 'buffer/',
    },
  },
  define: {
    Buffer: ['buffer', 'Buffer'],
  },
  // ...later options...
});

Initialization

The basic kit initialization does not require any configuration options.
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>;
};
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.
import {
  AppKit,
  AppKitProvider,
  // Enables TON wallet connections
  TonConnectConnector,
} from '@ton/appkit-react';
import '@ton/appkit-react/styles.css';

const kit = new AppKit({
  connectors: [
    new TonConnectConnector({
      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>;
};

Providers

The setup with connectors connects to TON wallets via services such as Tonkeeper. To enable advanced DeFi operations like asset swaps, configure DeFi providers. Omniston is the primary swap provider. To set it up:
1

Install the SDK

npm i @ston-fi/omniston-sdk
2

Set up the swap provider

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

// Omniston as a swap provider
import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';

const kit = new AppKit({
  // Set up a swap provider
  providers: [new OmnistonSwapProvider({
    /* custom configuration options */
  })],
});

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:
// AppKit
import {
  AppKit,
  AppKitProvider,
  Network,
  // Wallet connector
  TonConnectConnector,
} from '@ton/appkit-react';

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

// DeFi provider
import { OmnistonSwapProvider } from '@ston-fi/omniston-sdk';

// 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.
    new TonConnectConnector({
      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()],
});

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

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.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
  TonConnectConnector,
} from '@ton/appkit-react';
import '@ton/appkit-react/styles.css';

const kit = new AppKit({
  connectors: [
    new TonConnectConnector({
      // 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,
  TonConnectConnector,
} from '@ton/appkit';

const kit = new AppKit({
  connectors: [
    new TonConnectConnector({
      // Pass the existing TonConnectUI instance object
      tonConnectUI
    }),
  ]
});
One can also extend the existing AppKit instance dynamically:
// Passing the existing TonConnectUI instance object
kit.addConnector(new TonConnectConnector({ 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

See also