UI Integration for Ton Wallet Connection via OKX Connect

Connecting users to decentralized applications (DApps) on the TON blockchain has never been smoother. With OKX Connect, developers can implement a seamless, secure, and user-friendly wallet integration using either SDKs or a ready-to-use UI interface. This guide walks you through the full process of integrating the OKX Wallet UI into your DApp—especially if it operates within Telegram—offering users the flexibility to connect via the OKX Mobile App or directly through the OKX Mini Wallet.

Whether you're building a decentralized exchange (DEX), NFT marketplace, or any Web3 experience on TON, this integration reduces development time and enhances user onboarding.

👉 Discover how to effortlessly integrate wallet connectivity into your DApp today.

Why Use the OKX UI for Ton Wallet Connection?

The OKX UI solution simplifies wallet connectivity by providing pre-built components that handle connection flows, transaction signing, and state management. If your DApp runs inside Telegram, users can stay in-app and use the OKX Mini Wallet, eliminating friction and improving conversion.

For developers:

Reuse existing Ton Connect logic to reduce migration effort.
Leverage ProviderUI if already using OKX Connect, enabling multi-network support and concurrent requests.
Reduce development overhead with plug-and-play UI components.

Install via npm

To get started, install the required package using npm:

npm install @okxweb3/ton-connect-ui

This package includes all necessary modules for initializing and managing wallet connections through an intuitive UI layer.

Initialize the OKX Ton Connect UI

Before establishing a connection, initialize the OKXTonConnectUI object with configuration options tailored to your DApp’s branding and functionality.

Initialization Syntax

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

Request Parameters

dappMetaData – Object containing your app's identity:
- name: Application name (non-unique).
- icon: URL to a PNG or ICO icon (preferably 180x180px). SVG is not supported.
buttonRootId (optional) – The HTML element ID where the "Connect Wallet" button will be injected. If omitted, no button is rendered automatically.
actionsConfiguration – Controls post-action navigation:
- modals: Choose which alerts to show ('before', 'success', 'error') or use 'all'.
- returnStrategy: Deep link strategy after user action (e.g., tg://resolve for Telegram apps).
- tmaReturnUrl: For Telegram Mini Apps; set to 'back' to return to your DApp after signing.
uiPreferences – Customize appearance:
- theme: Supports THEME.DARK, THEME.LIGHT, or 'SYSTEM' for automatic detection.
language – Set interface language (e.g., 'en_US', 'zh_CN', 'es_ES'). Defaults to 'en_US'.
restoreConnection (optional) – Boolean to auto-reconnect on page load.

Returns

An instance of OKXTonConnectUI, used for all subsequent operations.

Example

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-wallet-btn',
  actionsConfiguration: {
    returnStrategy: 'tg://resolve',
    tmaReturnUrl: 'back'
  },
  uiPreferences: {
    theme: THEME.LIGHT
  },
  language: 'en_US',
  restoreConnection: true
});

Monitor Wallet State Changes

Track real-time wallet status changes such as connected, reconnected, or disconnected states.

Use the same method as OKXTonConnect.onStatusChange:

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

// Unsubscribe when no longer needed
// ui.offStatusChange(listener);

This helps maintain accurate UI state and enables personalized user experiences based on connection status.

Connect to Wallet

Trigger the wallet connection flow programmatically or via the injected button.

If using a custom trigger:

await ui.openModal();

This opens a modal allowing users to choose between connecting via the OKX mobile app or launching the OKX Mini Wallet within Telegram.

👉 See how fast you can launch a full wallet connection flow.

Set the tonProof Authentication

Securely authenticate users using tonProof, a signature-based login protocol.

Steps:

Set state to 'loading' before preparing parameters.
Once ready, update to 'ready' and provide the value.
Optionally remove loading state with setConnectRequestParameters(null).

Example

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

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

This ensures secure, non-invasive authentication without exposing private keys.

Get Connected Wallet Info

Retrieve details about the currently connected wallet:

const wallet = ui.getWallet();
if (wallet) {
  console.log('Address:', wallet.account.address);
  console.log('Chain:', wallet.account.chain);
}

You also get walletInfo, including name and icon, useful for displaying in your UI.

Disconnect from Wallet

Allow users to disconnect cleanly:

await ui.disconnect();

This clears local session data and updates the UI accordingly.

Send Transaction

Initiate and sign transactions securely through the wallet interface.

Method

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

Parameters

transaction: Standard TON transaction object (address, amount, etc.).
actionConfigurationRequest: Optional override for modals and return strategies.

Example

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

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

Returns a Base64-encoded Bag-of-Cells (BOC) upon successful signing.

Customize UI Configuration

Dynamically update theme or language after initialization:

ui.setUIPreferences({ theme: THEME.DARK });
ui.setLanguage('zh_CN');

These changes apply instantly, enhancing accessibility and user preference alignment.

Listen to Connection Events

Subscribe to key lifecycle events for better UX control:

Event Name	Trigger Timing
`OKX_UI_CONNECTION_STARTED`	User begins connecting
`OKX_UI_CONNECTION_COMPLETED`	Connection successful
`OKX_UI_CONNECTION_ERROR`	User cancels or error occurs
`OKX_UI_DISCONNECTION`	User disconnects
`OKX_UI_TRANSACTION_SENT_FOR_SIGNATURE`	Transaction sent to wallet
`OKX_UI_TRANSACTION_SIGNED`	User approved transaction

Example Listener

window.addEventListener('message', (event) => {
  if (event.data?.event === 'OKX_UI_CONNECTION_COMPLETED') {
    console.log('Wallet connected successfully!');
    // Update UI
  }
});

Use these events to show loaders, success messages, or analytics tracking.

Error Handling and Codes

Handle common errors gracefully with standardized codes:

UNKNOWN_ERROR: Unexpected issue.
ALREADY_CONNECTED_ERROR: Prevent duplicate connections.
NOT_CONNECTED_ERROR: Ensure wallet is linked before actions.
USER_REJECTS_ERROR: User denied request.
METHOD_NOT_SUPPORTED: Feature not available.
CHAIN_NOT_SUPPORTED: Incompatible network.
WALLET_NOT_SUPPORTED: Unsupported wallet type.
CONNECTION_ERROR: Network or handshake failure.

Proper error handling improves reliability and user trust.

FAQ

Can I use this UI if my DApp runs in Telegram?

Yes. The OKX UI supports both standalone websites and Telegram Mini Apps. Users can connect via the OKX Mini Wallet without leaving Telegram.

Does this support multiple blockchain networks?

While focused on TON, OKX Connect supports multi-network capabilities when using ProviderUI, making future cross-chain expansion easier.

Is tonProof required?

No, but it’s recommended for secure user authentication without exposing sensitive data.

Can I customize the "Connect Wallet" button?

Yes. You can either let the UI inject a default button or build your own trigger using openModal().

How do I handle disconnection?

Call ui.disconnect() to terminate the session. Always listen for state changes to reflect UI updates.

Is this compatible with existing Ton Connect implementations?

Yes. If you already use Ton Connect, you can integrate OKX UI with minimal code changes—reducing development time significantly.

👉 Start integrating secure, seamless wallet access in minutes.

Core Keywords

Ton Wallet Connection
OKX Connect UI
DApp Wallet Integration
Telegram Mini Wallet
tonProof Authentication
Send TON Transaction
Web3 SDK
Blockchain Developer Tools

By leveraging these keywords naturally throughout the content, this guide aligns with search intent while delivering actionable technical insights for developers building on TON.