# How to initialize the TON Connect's AppKit (https://docs-fpm2731fy-ton-core-docs.vercel.app/llms/ecosystem/appkit/init/content.md)



If there is a dApp that uses [TON Connect UI libraries](#relation-to-ton-connect-libraries), migrate that dApp to AppKit in a few steps:

* [Migrate from `@tonconnect/ui-react` (React)](#migrate-from-%40tonconnect%2Fui-react)
* [Migrate from `@tonconnect/ui` (Vanilla)](#migrate-from-%40tonconnect%2Fui)

## Installation [#installation]

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

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```shell  icon="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
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```shell  icon="globe"
      #     AppKit      TanStack Query       TON Connect    Core packages         # Buffer polyfill
      npm i @ton/appkit @tanstack/query-core @tonconnect/ui @ton/core @ton/crypto buffer
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

Core packages require a `Buffer` [polyfill](https://en.wikipedia.org/wiki/Polyfill_\(programming\)). Extend the module bundle configuration according to the bundler in use:

<CodeGroup>
  <CodeBlockTabs defaultValue="Vite">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Vite">
        Vite
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Webpack">
        Webpack
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Vite">
      ```ts
      // vite.config.js
      import { defineConfig } from 'vite';
      export default defineConfig({
        // ...prior options...
        resolve: {
          alias: {
            buffer: 'buffer/',
          },
        },
        define: {
          Buffer: ['buffer', 'Buffer'],
        },
        // ...later options...
      });
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Webpack">
      ```ts
      // 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...
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Initialization [#initialization]

<Callout type="tip">
  Jump to a [complete and exhaustive setup](#complete-setup).
</Callout>

The basic kit initialization does not require any configuration options.

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="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>;
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe"
      import { AppKit } from '@ton/appkit';

      const kit = new AppKit({});
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

To communicate with the blockchain, AppKit uses [TON Center APIs](/llms/ecosystem/api/toncenter/introduction/content.md) by default. In particular, operations with assets require many API calls — [obtain a key to access higher limits](/llms/ecosystem/api/toncenter/get-api-key/content.md) and prevent [frequent rate limit 429 errors](/llms/ecosystem/api/toncenter/rate-limit/content.md).

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

```ts
// 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 [#connectors]

The [basic setup](#initialization) 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](/llms/ecosystem/ton-connect/manifest/content.md) adjusted to the needs of a given dApp.

For local development and testing, use the [manifest file from this demo dApp](https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json).

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="react" expandable
      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>;
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe" expandable
      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',
            },
          }),
        ],
      });
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Providers [#providers]

The [setup with connectors](#connectors) connects to TON wallets via services such as [Tonkeeper](/llms/ecosystem/wallet-apps/tonkeeper/content.md). To enable advanced DeFi operations like asset swaps or staking, or to set up a [streaming API](/llms/ecosystem/api/toncenter/streaming/overview/content.md) service, configure providers.

Supported swap providers:

* [Omniston](https://ston.fi/omniston). Requires the `@ston-fi/omniston-sdk` package.
* [DeDust](https://dedust.io). Has no additional dependencies.

Supported staking providers:

* [Tonstakers](https://tonstakers.com). Has no additional dependencies.

Supported streaming providers:

* [TON Center Streaming API v2](/llms/ecosystem/api/toncenter/streaming/overview/content.md). Has no additional dependencies.
* TonAPI Streaming API v2. Has no additional dependencies.

<Callout type="note">
  AppKit uses the first registered swap provider by default. Pass `providerId` when requesting a quote to target a specific provider.
</Callout>

<Steps>
  <Step>
    #### Install the SDK for Omniston [#install-the-sdk-for-omniston]

    Swaps with Omniston require its SDK to be installed:

    ```shell
    npm i @ston-fi/omniston-sdk
    ```
  </Step>

  <Step>
    #### Set up one or more providers [#set-up-one-or-more-providers]

    ```ts
    // Or @ton/appkit-react for React
    import {
      AppKit,
      Network,
      // TON Center
      createTonCenterStreamingProvider,
      // TonAPI
      // createTonApiStreamingProvider,
    } from '@ton/appkit';

    // Swap providers
    import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
    import { DeDustSwapProvider } from '@ton/appkit/swap/dedust';

    // Tonstakers as a staking provider
    import { createTonstakersProvider } from '@ton/appkit/staking/tonstakers';

    const kit = new AppKit({
      // Providers setup
      providers: [
        // AppKit uses the first registered swap provider by default.
        new OmnistonSwapProvider({
          /* custom configuration options, none are required */
        }),
        new DeDustSwapProvider({
          /* custom configuration options, none are required */
        }),
        // Staking
        createTonstakersProvider({
          /* custom configuration options, none are required */
        }),
        // Use either TON Center or TonAPI streaming, not both.
        // The provider registered last takes priority.
        // AppKit does not allow toggling between streaming providers.
        createTonCenterStreamingProvider({
          network: Network.mainnet(),

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

          // Optional custom WebSocket endpoint URL.
          // If omitted or undefined, defaults to the
          // official URL based on the current `network` context.
          endpoint: undefined,
        }),
      ],
    });
    ```
  </Step>
</Steps>

### Queries and mutations [#queries-and-mutations]

[TanStack Query](https://tanstack.com/query/latest) is an opinionated library that simplifies fetching, caching, synchronizing and updating server state in web applications.

To enable [it for React](https://tanstack.com/query/latest/docs/framework/react/overview), wrap the application inside `AppKitProvider` in the `QueryClientProvider` from `@tanstack/react-query`:

```tsx
// 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 [#complete-setup]

The following initialization example sets up everything at once:

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="react"
      // AppKit
      import {
        AppKit,
        AppKitProvider,
        Network,
        // Wallet connector
        createTonConnectConnector,
        // Streaming API
        createTonCenterStreamingProvider,
      } from '@ton/appkit-react';

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

      // DeFi providers
      import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
      import { DeDustSwapProvider } from '@ton/appkit/swap/dedust';
      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 providers.
        providers: [
          // AppKit uses the first registered swap provider by default.
          new OmnistonSwapProvider(),
          new DeDustSwapProvider(),
          // Staking
          createTonstakersProvider(),
          // Streaming
          createTonCenterStreamingProvider({
            network: Network.mainnet(),

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

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

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe"
      // AppKit
      import {
        AppKit,
        Network,
        // Wallet connector
        createTonConnectConnector,
        // Streaming API
        createTonCenterStreamingProvider,
      } from '@ton/appkit';

      // DeFi providers
      import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
      import { DeDustSwapProvider } from '@ton/appkit/swap/dedust';
      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 providers.
        providers: [
          // AppKit uses the first registered swap provider by default.
          new OmnistonSwapProvider(),
          new DeDustSwapProvider(),
          // Staking
          createTonstakersProvider(),
          // Streaming
          createTonCenterStreamingProvider({
            network: Network.mainnet(),

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

## Dynamic configuration [#dynamic-configuration]

AppKit instance can be dynamically extended with new [connectors](#connectors) and [providers](#providers).

### Add new connectors [#add-new-connectors]

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

```ts
kit.addConnector(connector);
```

### Add new providers [#add-new-providers]

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

```ts
kit.registerProvider(provider);
```

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

```ts
kit.swapManager.registerProvider(swapProvider);
```

To add a [streaming API](/llms/ecosystem/api/toncenter/streaming/overview/content.md) provider, register it via `kit.streamingManager`:

```ts
kit.streamingManager.registerProvider(streamingProvider);
```

Check whether a network supports real-time subscriptions with the `hasStreamingProvider(kit, network)` function.

## Configuration parameters [#configuration-parameters]

<ParamField path="networks" type="Record<CHAIN, NetworkConfig>">
  For one or more TON networks, configure their respective API or RPC providers to interact with.

  ```ts title="TypeScript" icon="globe"
  // 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.

  ```ts title="TypeScript" icon="globe"
  // 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...
  });
  ```
</ParamField>

<ParamField path="connectors" type="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:

  ```ts
  interface ConnectorMetadata {
    /**
     * Connector name
     */
    name: string;
    /**
     * Connector icon URL
     */
    iconUrl?: string;
  }
  ```
</ParamField>

<ParamField path="providers" type="Providers[] | undefined">
  Array of DeFi or auxiliary providers that enable additional functionality, such as asset swaps via [Omniston](https://ston.fi/omniston).
</ParamField>

## Relation to TON Connect libraries [#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` [#migrate-from-tonconnectui-react]

Before migrating, [install AppKit and peer packages](#installation) and add necessary polyfills.

<Steps>
  <Step>
    #### Ensure the TON Connect UI package is of the latest version [#ensure-the-ton-connect-ui-package-is-of-the-latest-version]

    Ensure that TON Connect packages are of the latest version:

    ```shell
    npm up @tonconnect/ui-react --save
    ```
  </Step>

  <Step>
    #### Initialize AppKit and replace TonConnectUIProvider [#initialize-appkit-and-replace-tonconnectuiprovider]

    Use `AppKitProvider` in place of the `TonConnectUIProvider`:

    ```tsx
    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](#complete-setup) for all the possible AppKit configuration options.
  </Step>

  <Step>
    #### Keep existing hooks as is [#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.
  </Step>
</Steps>

### Migrate from `@tonconnect/ui` [#migrate-from-tonconnectui]

Before migrating, [install AppKit and peer packages](#installation) and add necessary polyfills.

<Steps>
  <Step>
    #### Ensure the TON Connect UI package is of the latest version [#ensure-the-ton-connect-ui-package-is-of-the-latest-version-1]

    ```shell
    npm up @tonconnect/ui --save
    ```
  </Step>

  <Step>
    #### Initialize AppKit and reuse TonConnectUI object [#initialize-appkit-and-reuse-tonconnectui-object]

    It is possible to reuse the existing `TonConnectUI` object when configuring AppKit [connectors](#connectors):

    ```ts
    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:

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

    Refer to the [complete initialization setup](#complete-setup) for all the possible AppKit configuration options.
  </Step>

  <Step>
    #### Replace method calls with exported functions [#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](/llms/ecosystem/appkit/overview/content.md) for concrete examples.
  </Step>
</Steps>

## Next steps [#next-steps]

<Columns cols="2">
  <Card title="Work with Toncoin" icon="gem" horizontal="true" href="/ecosystem/appkit/toncoin" />
</Columns>

## See also [#see-also]

* [AppKit overview](/llms/ecosystem/appkit/overview/content.md)
* [TON Connect's app manifest](/llms/ecosystem/ton-connect/manifest/content.md)
* [TON Connect overview](/llms/ecosystem/ton-connect/overview/content.md)