UI Integration for TON Web3 Wallets: Connect Apps & Mini Wallets via DEX API

Integrating Web3 functionality into your decentralized application (DApp) has never been more seamless—especially when targeting users on Telegram. With the OKX TON Connect UI, developers can quickly implement wallet connection flows that support both native mobile wallets and in-app Mini Wallet experiences within Telegram.

This guide walks you through the full integration process using the OKXTonConnectUI SDK, enabling smooth onboarding for users across platforms while reducing development overhead. Whether you're building a decentralized exchange (DEX), NFT marketplace, or gaming DApp on The Open Network (TON), this documentation ensures robust, secure, and user-friendly wallet interactions.

👉 Discover how to seamlessly connect Web3 wallets in minutes

Why Use OKX TON Connect UI?

The OKX TON Connect UI simplifies Web3 onboarding by offering pre-built components for connecting TON-compatible wallets. If your DApp operates within Telegram, users can either launch their external mobile wallet or use the OKX Telegram Mini Wallet without leaving the chat environment.

Developers who previously used Ton Connect can continue leveraging familiar patterns with minimal changes. Those coming from OKX Connect can upgrade to ProviderUI, which supports multi-network requests and reduces redundant coding efforts.

Built with developer efficiency and user experience in mind, this UI layer abstracts complex connection logic while maintaining full control over customization.

Install via npm

To get started, install the SDK using npm:

npm install @okxweb3/ton-connect-ui

This package includes everything needed to initialize, manage, and interact with TON wallets through an intuitive interface.

Initialize the Connection Interface

Before connecting a wallet, create an instance of OKXTonConnectUI. This object manages all interactions including connection, transaction signing, and event handling.

Syntax

new OKXTonConnectUI(dappMetaData, buttonRootId, actionsConfiguration, uiPreferences, language, restoreConnection)

Parameters

• dappMetaData (object)

  • name (string): Your DApp’s display name.
  • icon (string): URL to your app icon (PNG or ICO format recommended; 180x180px ideal).
• buttonRootId (string, optional): The HTML element ID where the "Connect Wallet" button will be injected. If omitted, no button is rendered automatically.

• actionsConfiguration (object)

  • modals: Controls visibility of UI modals during actions ('before', 'success', 'error', or 'all').
  • returnStrategy: Deep link strategy after user action (e.g., 'tg://resolve' for Telegram).
  • tmaReturnUrl: For Mini Apps—set to 'back' to return to DApp post-signing, 'none' to stay in wallet.

• uiPreferences (object)

  • theme: Set to THEME.DARK, THEME.LIGHT, or "SYSTEM" for automatic detection.
• language (string): Supported locales include "en_US", "zh_CN", "ru_RU", "es_ES", and more. Defaults to "en_US".
• restoreConnection (boolean, optional): Automatically reconnects if a previous session exists.

Example Initialization

import { OKXTonConnectUI, THEME } from '@okxweb3/ton-connect-ui';

const ui = new OKXTonConnectUI({
  dappMetaData: {
    name: 'My TON DApp',
    icon: 'https://example.com/icon.png'
  },
  buttonRootId: 'connect-btn',
  actionsConfiguration: {
    returnStrategy: 'tg://resolve',
    tmaReturnUrl: 'back'
  },
  uiPreferences: { theme: THEME.DARK },
  language: 'en_US',
  restoreConnection: true
});

Monitor Wallet Status Changes

Track real-time wallet state with the status change listener. Events include:

• Connection established
• Reconnection restored
• Disconnection triggered

Use this to update UI elements dynamically based on connection status.

👉 See live integration examples for wallet state management

Usage

ui.onStatusChange((wallet) => {
  if (wallet) {
    console.log('Connected to:', wallet.account.address);
  } else {
    console.log('Disconnected');
  }
});

When no longer needed, call unsubscribe() to free resources:

const unsubscribe = ui.onStatusChange(...);
unsubscribe();

Connect a Wallet

Trigger the connection modal manually if not using the auto-rendered button:

await ui.openModal();

This opens a list of available wallets. Users can choose between launching their mobile app or using the OKX Telegram Mini Wallet directly inside Telegram.

Set tonProof for Authentication

Securely authenticate users via tonProof, a signature-based verification method.

Set the state to 'loading' while preparing proof data, then switch to 'ready' with the signed value:

ui.setConnectRequestParameters({
  state: 'loading'
});

// After generating proof
ui.setConnectRequestParameters({
  state: 'ready',
  value: 'your-tonproof-signature-here'
});

To remove the requirement, pass null.

Close Connection Modal Programmatically

Dismiss the connection popup without completing it:

ui.closeModal();

Useful for time-sensitive flows or when redirecting users mid-process.

Retrieve Connected Wallet Info

Check current connection status and access wallet details:

const wallet = ui.getWallet();
if (wallet) {
  const { address, chain } = wallet.account;
  console.log(`Connected to ${address} on ${chain}`);
}

Also retrieve walletInfo for provider metadata like name and icon.

Disconnect from Wallet

Allow users to log out or switch accounts:

await ui.disconnect();

Clears local session and notifies the connected wallet.

Send Transactions

Request transaction signing with full control over UX feedback.

Method

sendTransaction(transaction, actionConfigurationRequest): Promise<{ boc: string }>

Parameters

• transaction: Standard TON transaction object (see TON SDK docs).
• actionConfigurationRequest: Optional overrides for modals and return strategies.

Example

const tx = {
  validUntil: Math.floor(Date.now() / 1000) + 600,
  messages: [
    {
      address: 'UQD...',
      amount: '100000000'
    }
  ]
};

try {
  const result = await ui.sendTransaction(tx);
  console.log('Signed BOC:', result.boc);
} catch (error) {
  console.error('Transaction rejected:', error);
}

Customize UI Settings

Update preferences at runtime:

ui.setUiPreferences({ theme: THEME.LIGHT });
ui.setLanguage('zh_CN');

Supports dynamic theme switching and language localization without reinitializing.

Listen to UI Events

React to key moments in the user journey:

Example Listener

window.addEventListener('OKX_UI_CONNECTION_COMPLETED', () => {
  console.log('Wallet connected successfully!');
});

Error Handling & Codes

Understand common errors during connection and signing:

Handle these gracefully in your UI to improve user retention.

Frequently Asked Questions (FAQ)

Q: Can I use this UI in non-Telegram environments?
A: Yes. While optimized for Telegram Mini Apps, it works seamlessly on any web platform supporting TON wallets.

Q: Is user data stored during connection?
A: No. All authentication is client-side and private. We do not collect personal information.

Q: Does it support multiple blockchain networks?
A: Yes. With ProviderUI integration, you can manage requests across multiple chains simultaneously.

Q: How do I localize my DApp interface?
A: Use the language parameter during initialization or update dynamically with setLanguage().

Q: What happens if the user closes Telegram during signing?
A: The request remains pending until resumed or timed out. Use proper error handling to guide recovery.

Q: Can I style the connection button myself?
A: While default styling is provided, you can hide the injected button and build a custom trigger using openModal().

👉 Start integrating secure, multi-platform Web3 access today

Core Keywords

• TON Web3 wallet
• Telegram Mini Wallet
• OKX Connect UI
• DApp wallet integration
• Ton Connect SDK
• Web3 authentication
• Blockchain transaction signing
• Decentralized app onboarding