How to integrate a decentralized application (dApp)

This guide helps you integrate your dApp with TON or build one from scratch using TON Connect and auxiliary libraries. TON Connect is a standard wallet connection protocol in TON. It consists of supplementary SDKs and supervises two major use cases: dApps integrations with TON and custom wallet integrations. To proceed with a dApp integration, select your framework or environment:

React

Next.js

Vanilla JS

Integration

React

Install necessary libraries

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, install the following packages as well:

npm i @ton-community/assets-sdk @ton/ton @ton/core

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://<YOUR_APP_URL>/tonconnect-manifest.json, and be accessible with a direct GET request.Here’s an example of such a file:

tonconnect-manifest.json

{
  "url": "https://tonconnect-sdk-demo-dapp.vercel.app/",
  "name": "Demo Dapp with React UI",
  "iconUrl": "https://tonconnect-sdk-demo-dapp.vercel.app/apple-touch-icon.png",
  "termsOfUseUrl": "https://tonconnect-sdk-demo-dapp.vercel.app/terms-of-use.txt",
  "privacyPolicyUrl": "https://tonconnect-sdk-demo-dapp.vercel.app/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.

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.Some in-wallet browsers automatically open a wallet connection modal when your dApp loads. Still, always provide a button alternative in case the user dismissed the modal window or wants to connect a wallet after doing their research.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" }}/>

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 and opens the corresponding wallet modal, returning a promise that resolves once the modal window opens. 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
  }
};

In the object assigned, you should only pass options that you want to change — they will be merged with the current UI options. UI element will be re-rendered after such assignment. See all available uiOptions in the external 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://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json"
    >
      <TonConnectButton />
      <button
        {/*
          Notice that it is 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://tonconnect-sdk-demo-dapp.vercel.app/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>

Ecosystem

Payment processing

Standard contracts

Contract development

Tolk language

TVM: TON Virtual Machine

Blockchain foundations

Legacy languages

Contributing

How to integrate a decentralized application (dApp)

React

Next.js

Vanilla JS

Integration

React

Common usage recipes

Manual connection initiation

UI customization

Minimal React setup

Next.js

Vanilla JS

See also

React

Next.js

Vanilla JS

​Integration

​React

Common usage recipes

​Manual connection initiation

​UI customization

​Minimal React setup

​Next.js

​Vanilla JS

​See also

Integration

React

Manual connection initiation

UI customization

Minimal React setup

Next.js

Vanilla JS

See also