UI Integration for Ton Wallet Connection via OKX Connect

Integrating a seamless wallet connection experience into your decentralized application (DApp) is crucial for user adoption and engagement. With OKX Connect, developers can easily implement a robust, user-friendly interface that supports both mobile App Wallets and Telegram Mini Wallets—ideal for DApps operating within the TON (The Open Network) ecosystem.

This guide walks you through the complete process of integrating OKXTonConnectUI, covering initialization, connection handling, transaction signing, event monitoring, and error management—all while optimizing for performance and usability.

Whether you're building on TON for the first time or migrating from another wallet solution like Ton Connect or OKX Connect, this documentation ensures minimal development overhead and maximum compatibility.

👉 Get started with secure, one-click wallet integration today.

Why Use OKX UI for Ton Wallet Integration?

The OKX Connect SDK offers not only backend functionality but also a ready-to-use UI layer that simplifies wallet onboarding. When users interact with your DApp inside Telegram, they can choose between:

Opening the full OKX App Wallet
Using the lightweight OKX Mini Wallet directly within Telegram

This flexibility enhances user retention by reducing friction during onboarding and transaction approval.

If you’ve previously used Ton Connect, you can continue leveraging familiar patterns while upgrading to enhanced features. If you're coming from OKX Connect, switching to ProviderUI enables support for multiple network requests simultaneously—boosting efficiency and responsiveness.

Install via npm

To begin, install the required package using npm:

npm install @okxweb3/okx-connector-ton

This package includes everything needed to initialize and manage wallet connections via UI components.

Initialize OKXTonConnectUI

Before connecting to any wallet, instantiate the OKXTonConnectUI object with configuration options tailored to your app’s needs.

const okxTonConnectUI = new OKXTonConnectUI(
  dappMetaData,
  buttonRootId,
  actionsConfiguration,
  uiPreferences,
  language,
  restoreConnection
);

Configuration Parameters

dappMetaData – Object containing:
- name: Your app's display name (non-unique)
- icon: Public URL to a 180×180px PNG icon (SVG not supported)
buttonRootId – The HTML element ID where the "Connect Wallet" button will be injected. Omitting this hides the auto-generated button.
actionsConfiguration – Controls post-action behavior:
- modals: Choose which alerts appear ('before', 'success', 'error', or 'all')
- returnStrategy: Deep link strategy after signing (e.g., tg://resolve for Telegram)
- tmaReturnUrl: For Mini Apps; use 'back' to return to your DApp after signing
uiPreferences – Customize appearance:
- theme: Supports THEME.DARK, THEME.LIGHT, or 'SYSTEM' for auto-detection
language – Localization support including 'en_US', 'zh_CN', 'es_ES', and more (default: 'en_US')
restoreConnection – Boolean to automatically reconnect on page reload (optional)

👉 Easily embed a professional-grade wallet button in minutes.

Monitor Wallet State Changes

Track real-time connection status using the built-in state observer:

okxTonConnectUI.onStatusChange((wallet) => {
  if (wallet) {
    console.log("Connected:", wallet.address);
  } else {
    console.log("Disconnected");
  }
});

Events include successful connection, reconnection, and disconnection. Always call unsubscribe() when no longer monitoring to free up resources.

Connect to Wallet

Trigger the connection flow either via the auto-rendered button or programmatically:

await okxTonConnectUI.openModal();

This opens a modal allowing users to select their preferred wallet method—especially useful when no buttonRootId is specified.

Set tonProof Authentication

Securely authenticate users using tonProof, a signature-based login mechanism:

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

// Once ready
okxTonConnectUI.setConnectRequestParameters({
  state: 'ready',
  value: 'proof_payload_here'
});

To cancel, pass null. This ensures smooth UX during dynamic authentication flows.

Get Connected Wallet Info

Retrieve details about the currently connected wallet:

const wallet = okxTonConnectUI.wallet;
if (wallet) {
  console.log("Address:", wallet.address);
  console.log("Chain:", wallet.chain);
}

Useful for personalizing user interfaces and validating session states.

Send Transactions

Initiate and sign transactions securely:

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

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

You can override actionConfigurationRequest per call to customize modals and return strategies.

Disconnect from Wallet

Allow users to end their session cleanly:

await okxTonConnectUI.disconnect();

This clears local session data and updates the UI accordingly.

Customize UI Configuration

Change theme or language dynamically after initialization:

okxTonConnectUI.setUiPreferences({ theme: THEME.DARK });
okxTonConnectUI.setLanguage('zh_CN');

These settings enhance accessibility and user comfort across devices and regions.

Listen to UI Events

React to key lifecycle events using event listeners:

Event Name	Trigger Timing
`OKX_UI_CONNECTION_STARTED`	User begins connection
`OKX_UI_CONNECTION_COMPLETED`	Connection successful
`OKX_UI_CONNECTION_ERROR`	User rejected or error occurred
`OKX_UI_TRANSACTION_SIGNED`	Transaction approved and signed
`OKX_UI_DISCONNECTION`	User initiates disconnect

Example listener:

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

Perfect for analytics, logging, or triggering onboarding tours.

Handle Errors Gracefully

Common error codes help diagnose issues quickly:

UNKNOWN_ERROR: Unexpected failure
ALREADY_CONNECTED_ERROR: Prevent duplicate connections
NOT_CONNECTED_ERROR: Ensure wallet is linked before actions
USER_REJECTS_ERROR: User declined request
CHAIN_NOT_SUPPORTED: Incompatible blockchain selected
CONNECTION_ERROR: Network or protocol issue

Proper handling improves UX and reduces support load.

Frequently Asked Questions

Can I use this in a Telegram Mini App?

Yes. The UI automatically adapts to Telegram environments, supporting both full App Wallets and the embedded OKX Mini Wallet.

Does it support multiple simultaneous connections?

Yes, when using ProviderUI, you can manage concurrent requests across different networks or accounts.

Is tonProof required?

No, but it's highly recommended for secure user authentication without exposing private keys.

How do I localize my app?

Set the language parameter during initialization or update it later using setLanguage() with supported codes like 'fr_FR' or 'vi_VN'.

Can I remove the default connect button?

Yes. Simply omit the buttonRootId parameter and trigger connection manually via openModal().

What happens if the user closes the app?

If restoreConnection: true, the session will automatically reconnect when the user returns—provided the wallet still grants access.

👉 Integrate a high-performance wallet connector with full UI support now.