Using TON Wallets

Recommended: JavaScript SDK for React Native

While this SDK is still supported, we recommend using newer JavaScript SDK, which is optimized for React Native, but also comes with a host of other benefits.

TON is exposed as a first-class module on the headless React Native client — dynamicClient.ton — alongside dynamicClient.wallets, dynamicClient.bitcoin, and the chain extensions. There is no separate TonExtension to install: the module ships with @dynamic-labs/legacy-client and routes every call through the embedded WebView, which already includes the TON wallet connectors and a TonController that handles the bridge messages.

Checking if a wallet is a TON wallet

React Native

import { dynamicClient } from '<path to client file>';

const wallet = dynamicClient.wallets.primary;
if (!wallet || wallet.chain !== 'TON') {
  throw new Error('This wallet is not a TON wallet');
}

wallet.chain returns one of 'EVM' | 'SOL' | 'BTC' | 'SUI' | 'TON'. To list every TON wallet the user has connected:

React Native

const tonWallets = dynamicClient.wallets.userWallets.filter(
  (w) => w.chain === 'TON',
);

Configuring the client

TON support is enabled the moment you create the client; no extension is required. Optionally pass tonNetworks to override the dashboard network list (custom entries win on chainId conflicts).

import { createClient } from '@dynamic-labs/legacy-client';
import { ReactNativeExtension } from '@dynamic-labs/legacy-react-native-extension';
import { WebExtension } from '@dynamic-labs/legacy-web-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
  appName: 'Your App',
  appLogoUrl: 'https://your-domain.com/logo.png',
})
  .extend(ReactNativeExtension({ appOrigin: 'https://your-domain.com' }))
  .extend(WebExtension({}));

import { createClient } from '@dynamic-labs/legacy-client';
import { ReactNativeExtension } from '@dynamic-labs/legacy-react-native-extension';
import { WebExtension } from '@dynamic-labs/legacy-web-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
  tonNetworks: [
    {
      chainId: -239,
      networkId: -239,
      name: 'TON Mainnet',
      rpcUrls: ['https://your-toncenter.example.com/api/v2/jsonRPC'],
      nativeCurrency: { name: 'Toncoin', symbol: 'TON', decimals: 9 },
      blockExplorerUrls: ['https://tonviewer.com'],
    },
  ],
})
  .extend(ReactNativeExtension({ appOrigin: 'https://your-domain.com' }))
  .extend(WebExtension({}));

The `dynamicClient.ton` module

Every method takes a walletId (string) — typically read from wallet.id of a wallet you’ve already filtered by chain === 'TON'.

Method	Purpose
`signMessage`	Sign an arbitrary message with the TON wallet.
`sendTon`	Transfer native Toncoin to a recipient.
`sendJetton`	Transfer a Jetton (TON-native token) to a recipient.
`getBalance`	Returns the wallet’s Toncoin balance (in nanotons, as a string).
`getNetworkDetails`	Returns the `{ chainId, name }` of the wallet’s network.

Sign a message

React Native

const wallet = dynamicClient.wallets.userWallets.find((w) => w.chain === 'TON');
if (!wallet) throw new Error('No TON wallet');

const { signature } = await dynamicClient.ton.signMessage({
  walletId: wallet.id,
  message: 'Hello, TON!',
});

The signing scheme follows what the underlying connector supports (TonConnect proof for external wallets, Ed25519 for embedded MPC wallets).

Get balance

React Native

const wallet = dynamicClient.wallets.userWallets.find((w) => w.chain === 'TON');
if (!wallet) throw new Error('No TON wallet');

const { balance } = await dynamicClient.ton.getBalance({
  walletId: wallet.id,
});

// balance is a nanoton-denominated string. Convert to TON for display:
const ton = Number(balance) / 1e9;

Get network details

React Native

const { chainId, name } = await dynamicClient.ton.getNetworkDetails({
  walletId: wallet.id,
});
// chainId === -239 for mainnet, -3 for testnet

Embedded vs external TON wallets

Embedded (MPC) TON wallets — derived from the same root entropy as the user’s other embedded wallets but with a TON-specific Ed25519 derived key. The private key is never reconstructed in your app; signing happens through the MPC ceremony.
External TON wallets — connect via TonConnect (Tonkeeper, MyTonWallet, OpenMask, etc.). The signing protocol depends on the connector.

A single user session can hold multiple wallets across chains. Filter by wallet.chain to find the right one.

Examples

Send TON — transfer native Toncoin.
Send a Jetton — transfer a TON-native token.

Installation & Configuration

Authenticate

Wallets

Gasless

Chains & Networks

Users & Verified Credentials

Gating & Access Control

Integrations

React Native SDK Reference

Using TON Wallets

Recommended: JavaScript SDK for React Native

Checking if a wallet is a TON wallet

Configuring the client

The `dynamicClient.ton` module

Sign a message

Get balance

Get network details

Embedded vs external TON wallets

Examples

Recommended: JavaScript SDK for React Native

​Checking if a wallet is a TON wallet

​Configuring the client

​The dynamicClient.ton module

​Sign a message

​Get balance

​Get network details

​Embedded vs external TON wallets

​Examples

Checking if a wallet is a TON wallet

Configuring the client

The `dynamicClient.ton` module

Sign a message

Get balance

Get network details

Embedded vs external TON wallets

Examples