Adding TON Extensions

Add TON blockchain support to your Dynamic client

Make sure you enable TON chain in the Dynamic dashboard.

Installation

npm install @dynamic-labs-sdk/ton

Default TON extension

If you wish to support TON external wallets (via TonConnect) and Dynamic embedded wallets, you can add the default TON extension to your client using the addTonExtension method.

import { createDynamicClient } from "@dynamic-labs-sdk/client";
import { addTonExtension } from "@dynamic-labs-sdk/ton";

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
});

addTonExtension();

This enables support for external wallets like Tonkeeper, MyTonWallet, and Telegram Wallet (via TonConnect), as well as embedded wallets managed by Dynamic’s infrastructure (via WaaS).

Standalone TON extensions

If you want to be more granular, you can add the standalone TON extensions individually to your client.

TonConnect extension

import { addTonConnectExtension } from "@dynamic-labs-sdk/ton/ton-connect";

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
});

// this will add support for external TON wallets via TonConnect
addTonConnectExtension();

WaaS TON extension

import { addWaasTonExtension } from "@dynamic-labs-sdk/ton/waas";

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
});

// this will add support for Dynamic embedded TON wallets only
addWaasTonExtension();

Reusing an existing TonConnectUI instance

By default, addTonExtension and addTonConnectExtension create a new TonConnectUI instance internally, using your client’s metadata.universalLink to derive the manifest URL. If your app already manages a TonConnectUI instance (for example via useTonConnectUI from @tonconnect/ui-react), you can pass it in to avoid duplicate instances.

import { createDynamicClient } from "@dynamic-labs-sdk/client";
import { addTonExtension } from "@dynamic-labs-sdk/ton";
import { TonConnectUI } from "@tonconnect/ui";

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
});

const tonConnectUI = new TonConnectUI({
  manifestUrl: "https://your-app.com/tonconnect-manifest.json",
});

addTonExtension({ tonConnectUI });

Combining extensions

You can combine as many extensions as you want to support all the wallets you want to support.

import { addTonConnectExtension } from "@dynamic-labs-sdk/ton/ton-connect";
import { addWaasTonExtension } from "@dynamic-labs-sdk/ton/waas";

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
});

addTonConnectExtension();
addWaasTonExtension();

TonConnect manifest

When using TonConnect (via addTonExtension or addTonConnectExtension), the SDK expects a tonconnect-manifest.json file to be served at your app’s origin. The URL is derived from the client’s metadata.universalLink setting, which defaults to window.location.origin:

{metadata.universalLink}/tonconnect-manifest.json

If your manifest is hosted at a different URL, you can configure it via the metadata.universalLink option when creating the client:

const dynamicClient = createDynamicClient({
  environmentId: "YOUR_ENVIRONMENT_ID",
  metadata: {
    universalLink: "https://your-app.com",
  },
});

This manifest contains metadata about your app that is displayed in the user’s wallet during connection. Place this file in your app’s public directory (e.g. public/tonconnect-manifest.json):

{
  "url": "https://your-app.com",
  "name": "Your App Name",
  "iconUrl": "https://your-app.com/icon.png",
  "termsOfUseUrl": "https://your-app.com/terms",
  "privacyPolicyUrl": "https://your-app.com/privacy"
}

For more details on the manifest format, see the TonConnect documentation.

Browser polyfill for Buffer

The TON ecosystem libraries (@ton/core, @ton/crypto) use Node.js’s Buffer internally. If you’re running in a browser environment where Buffer is not available globally, you’ll need to add a polyfill.

In your application’s entry point (before any TON-related code runs), add the following:

import { Buffer } from "buffer";

if (!globalThis.Buffer) {
  globalThis.Buffer = Buffer;
}

This is only needed in browser environments. Node.js has Buffer available globally by default.

Related functions

• isTonWalletAccount - Check if a wallet account is a TON account
• sendTon - Send native TON
• sendJetton - Send Jetton tokens
• sendTransaction - Send a custom TON transaction
• generateTonConnectProof - Generate a TonConnect proof for authentication