How to integrate a decentralized application (dApp) with TON

This guide helps you integrate your dApp with TON or build a fresh one from scratch with the help of TON Connect and auxiliary libraries.

TON Connect is a standard wallet connection protocol used on TON. It consists of many supplementary SDKs and supervises two major use-cases: integrations of dApps with TON and custom wallet integrations. The former are the focus of this guide.

To proceed with a dApp integration, select your framework or environment:

React

Next.js

Vanilla JS

Integration

React

1. Install necessary libraries

   To start integrating TON Connect into your dApp, you need to install the @tonconnect/ui-react package:

   npm i @tonconnect/ui-react
   

   That is enough for the most basic usage. However, to allow for more complex examples and further tweaks, install the following packages as well:

   npm i @ton-community/assets-sdk @ton/ton @ton/core
   
2. Create a TON Connect manifest

   TON Connect manifest is a small JSON file that lets wallets discover information about your dApp. It should be named tonconnect-manifest.json, placed at https://[yourapp.com]/tonconnect-manifest.json, and be accessible with a simple GET request.

   Here’s an example of such a file:

   tonconnect-manifest.json

   {
     "url": "https://ton-connect.github.io/demo-dapp-with-react-ui/",
     "name": "Demo Dapp with React UI",
     "iconUrl": "https://ton-connect.github.io/demo-dapp-with-react-ui/apple-touch-icon.png",
     "termsOfUseUrl": "https://ton-connect.github.io/demo-dapp-with-react-ui/terms-of-use.txt",
     "privacyPolicyUrl": "https://ton-connect.github.io/demo-dapp-with-react-ui/privacy-policy.txt"
   }
   

   After creating the manifest file, import TonConnectUIProvider to the root of your dApp and pass the manifest URL:

   import { TonConnectUIProvider } from '@tonconnect/ui-react';
   
   export function App() {
     return (
       <TonConnectUIProvider
         manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json"
       >
         { /* Your app */ }
       </TonConnectUIProvider>
     );
   }
   

   See more detailed information here: TON Connect manifest.

3. Add a button in the UI

   Users need a clear way of connecting their wallets to your app, so you must give a clear UI element to do so. Usually, that is a Connect wallet button.

   That said, opening your web dApp from the in-wallet browser of some wallets might automatically show a wallet connection modal window. But even in those cases, it is good to provide a button alternative in case the user dismissed the modal window and wants to connect a wallet after doing their research (DYOR).

   Adding TonConnectButton is straightforward:

   import { TonConnectButton } from '@tonconnect/ui-react';
   
   export const Header = () => {
     return (
       <header>
         <span>My App with React UI</span>
         <TonConnectButton />
       </header>
     );
   };
   

   The TonConnectButton is a universal UI component for initializing a connection. After the wallet is connected, it transforms into a wallet menu. Prefer to place the Connect wallet button in the top right corner of your app.

   You can add the className and style props to the button:

   <TonConnectButton className="my-button-class" style={{ float: "right" }}/>
   
4. Utilize TON Connect in your dApp

   Common usage recipes

Manual connection initiation

You can always initiate the connection manually using the useTonConnectUI hook and openModal method.

import { useTonConnectUI } from '@tonconnect/ui-react';

export const Header = () => {
  const [tonConnectUI, setOptions] = useTonConnectUI();
  return (
    <header>
      <span>My App with React UI</span>
      <button onClick={() => tonConnectUI.openModal()}>
        Connect Wallet
      </button>
    </header>
  );
};

To open a modal window for a specific wallet, use the openSingleWalletModal() method. It takes the wallet’s app_name as a parameter and opens the corresponding wallet modal, returning a promise that resolves once the modal window opens successfully.

To find the correct app_name of the target wallet, refer to the wallets-list.json file.

<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet')}>
  Connect Wallet
</button>

UI customization

To customize the UI of the modal, use the tonConnectUI object provided by the useTonConnectUI() hook, and then assign designated values as an object to the uiOptions property.

// Somewhere early in the component:
const [tonConnectUI] = useTonConnectUI();

// ...

// Somewhere later in the same component:
tonConnectUI.uiOptions = {
  language: 'ru', // sets the target language
  uiPreferences: {
    theme: THEME.DARK, // dark theme of the modal
  }
};

UI element will be re-rendered after such assignment. In the object assigned, you should only pass options that you want to change — they will be merged with the current UI options.

See all available uiOptions in the separate reference: TonConnectUiOptions Interface.

Minimal React setup

Putting all the above together, here’s a most minimal React dApp integration example.

First, start by creating a new project with React and Vite:

npm create vite@latest demo-react-dapp -- --template react-ts

Then, go into the project and add the @tonconnect/ui-react dependency:

cd demo-react-dapp
npm i @tonconnect/ui-react # this will also install other missing dependencies

Edit your App.tsx to have the following imports present:

src/App.tsx

import {
  TonConnectUIProvider,
  TonConnectButton,
  useTonConnectUI,
  useTonWallet,
  CHAIN,
} from '@tonconnect/ui-react';

Finally, in the same App.tsx file, replace your App() function with the following:

src/App.tsx

function App() {
  const [tonConnectUI] = useTonConnectUI();
  const wallet = useTonWallet();

  const sendToncoin = async (amount: string) => {
    if (!wallet) return;

    // Once the user has connected,
    // you can prepare and send a message from the wallet:
    try {
      await tonConnectUI.sendTransaction({
        validUntil: Math.floor(Date.now() / 1000) + 300,
        network: CHAIN.TESTNET,
        messages: [{ address: wallet.account.address, amount }],
      });
    }
  };

  return (
    <TonConnectUIProvider
      {/*
        We re-use an existing manifest here. To specify your own while developing locally,
        setup a tunnel and an https domain with the help of ngrok or similar tools.
      */}
      manifestUrl="https://ton-connect.github.io/demo-dapp-with-react-ui/tonconnect-manifest.json"
    >
      <TonConnectButton />
      <button
        {/*
          Notice that it's important to specify Toncoin in nanoToncoin format,
          where 1 Toncoin is equal to 10⁹ nanoToncoin:
        */}
        onClick={() => sendToncoin(String(100_000_000))}
      >
        Send 0.1 TON
      </button>
    </TonConnectUIProvider>
  );
}

Now, execute npm run dev to launch and preview your app in the browser at http://localhost:5173. All changes in code will be reflected live.

Connect a wallet and try using the Send 0.1 TON button. Notice that the exact sum of Toncoin shown in your wallet will be different, because there are certain fees required for such a transfer by the blockchain itself. When building apps, make sure to always take fees into consideration and show them to the end-user.

Next.js

TonConnectUIProvider relies on browser APIs and should be rendered only on the client side, i.e., on the frontend. As such, in a Next.js application, you should mark the component that wraps the provider with "use client" directive. Alternatively, dynamically import the provider to disable server-side rendering. Both approaches ensure that the provider is invoked only in the browser and works correctly there.

Example for the app router:

app/providers.tsx

'use client';

import { TonConnectUIProvider } from '@tonconnect/ui-react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TonConnectUIProvider
      manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json"
    >
      {children}
    </TonConnectUIProvider>
  );
}

For the pages router, you can dynamically import the provider:

import dynamic from 'next/dynamic';

const TonConnectUIProvider = dynamic(
  () => import('@tonconnect/ui-react').then(m => m.TonConnectUIProvider),
  { ssr: false }
);

function MyApp({ Component, pageProps }) {
  return (
    <TonConnectUIProvider
      manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json"
    >
      <Component {...pageProps} />
    </TonConnectUIProvider>
  );
}

Vanilla JS

For quick testing, use the following single-file HTML example.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>TON Connect sandbox</title>
  <script src="https://unpkg.com/@tonconnect/ui@latest/dist/tonconnect-ui.min.js"></script>
</head>
<body>
  <div id="ton-connect"></div>
  <button id="send" disabled>Send 0.1 TON</button>
  <script>
    const ui = new TON_CONNECT_UI.TonConnectUI({
      // Let's re-use the manifest from the demo app
      manifestUrl: 'https://ton-connect.github.io/demo-dapp-with-react-ui/tonconnect-manifest.json',
      buttonRootId: 'ton-connect', // anchor id with the element to hook the "Connect wallet" button onto
    });
    ui.onStatusChange(w => document.getElementById('send').disabled = !w);
    document.getElementById('send').onclick = async () => {
      // This will send 0.1 Toncoin from the connected wallet, beware!
      try {
        await ui.sendTransaction({
          validUntil: Math.floor(Date.now()/1000) + 300,
          messages: [{ address: ui.account.address, amount: String(100_000_000) }],
        });
      }
    };
  </script>
</body>
</html>

Usage

Once the app is integrated, follow one of these common usage recipes:

• Send Toncoin
• Send USDT
• Send a Jetton
• Send an NFT
• Check Toncoin balance
• Check USDT balance
• Check Jetton balance
• Check NFT items present
• Track a transaction and confirm its status
• Make a sign data request and verify signed data
• Make a proof request and verify it

See also

Read more about the TON Connect:

TON Connect overview

Skim the reference pages with more in-depth information:

TON Connect manifests

Discover wallet integration guides or explore complete examples:

Integrate a wallet

WalletKit overview