UI Integration for Ton Wallet Connection and DEX Interface

Integrating a seamless wallet connection experience is essential for decentralized applications (DApps) operating on the TON blockchain. With OKX's UI integration tools, developers can easily enable users to connect via the OKX App Wallet or stay within Telegram using the lightweight OKX Mini Wallet—offering flexibility, enhanced user experience, and faster onboarding.

Whether your DApp runs inside Telegram or as a standalone web application, the OKXTonConnectUI provides a ready-to-use interface that simplifies wallet connectivity while supporting advanced features like transaction signing, state monitoring, and deep-link return strategies.

This guide walks you through setting up, customizing, and managing wallet connections using OKX’s UI components—optimized for performance, usability, and compatibility with the TON ecosystem.

Why Use OKX UI for Ton Wallet Integration?

The OKX UI solution eliminates the need for building custom connection flows from scratch. It offers:

• Pre-built wallet connection buttons and modals
• Native support for Telegram Mini Apps via OKX Mini Wallet
• Multi-network request handling
• Automatic session restoration
• Built-in event tracking and error handling

If you've previously used Ton Connect or OKX Connect, migrating to this UI-based approach reduces development time and ensures consistency across platforms.

👉 Discover how easy it is to integrate secure wallet connectivity today.

Installation via npm

To begin integrating the OKX Ton Connect UI into your project, install the SDK using npm:

npm install @okxweb3/ton-connect-ui

This package includes all necessary components for initializing the connection interface, handling user interactions, and managing transactions securely.

Initialization: Setting Up OKXTonConnectUI

Before enabling wallet connections, initialize the OKXTonConnectUI object with configuration parameters tailored to your app’s needs.

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

Configuration Parameters

• dappMetaData – Object containing:

  • name: Your DApp’s display name.
  • icon: Public URL of your app icon (PNG or ICO format recommended; SVG not supported). A 180x180px image works best.
• 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 behavior:

  • modals: Choose which alerts to show ('before', 'success', 'error') or use 'all'.
  • returnStrategy: Deep link strategy after signing (e.g., tg://resolve for Telegram).
  • tmaReturnUrl: For Telegram Mini Wallet; 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 – Localization support including 'en_US', 'zh_CN', 'ru_RU', 'es_ES', 'fr_FR', and more. Defaults to English (en_US).
• restoreConnection (Optional) – Set to true to automatically reconnect users on page reload if they were previously connected.

This initialization sets the foundation for smooth, persistent wallet interactions.

Monitoring Wallet State Changes

Keep track of connection status in real time by listening to wallet state changes:

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

Triggers on events such as:

• Successful connection
• Reconnection after refresh
• Manual disconnection

Always call unsubscribe() when the listener is no longer needed to free up resources.

Connecting to a Wallet

Users can connect via two primary methods:

1. Clicking the auto-rendered "Connect" button (if buttonRootId is provided)
2. Programmatically calling:

await okxTonConnectUI.openModal();

This opens a modal allowing users to choose between launching the OKX App Wallet or using the OKX Mini Wallet directly in Telegram—maximizing accessibility without leaving the chat environment.

👉 Enable one-click wallet access with minimal setup effort.

Using tonProof for Secure Authentication

To verify user ownership securely, implement tonProof—a cryptographic proof method that confirms identity without exposing private keys.

Before initiating connection:

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

Once ready:

okxTonConnectUI.setConnectRequestParameters({ 
  state: 'ready', 
  value: 'your_payload_here' 
});

To cancel:

okxTonConnectUI.setConnectRequestParameters(null);

This enhances security during login flows and protects against spoofing attacks.

Retrieving Connected Wallet Information

After successful connection, retrieve details about the active wallet:

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

This data enables personalized experiences, transaction preparation, and account verification.

Disconnecting from the Wallet

Allow users to disconnect cleanly:

await okxTonConnectUI.disconnect();

This clears the session and triggers the OKX_UI_DISCONNECTION event, ensuring secure logout and proper state management.

Sending Transactions Securely

Initiate transactions with a simple promise-based method:

const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 360,
  messages: [
    {
      address: "UQ...", // Recipient address
      amount: "100000000" // Amount in nanotons
    }
  ]
};

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

Optional Configuration

Pass an actionConfigurationRequest object to customize behavior:

• modals: Control alert visibility
• returnStrategy: Define post-signing navigation
• tmaReturnUrl: Set return logic for Telegram Mini Wallet

Customizing UI Settings Dynamically

Change theme or language at runtime:

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

These updates apply immediately, improving accessibility and user comfort across regions and devices.

Listening to Connection Events

Subscribe to real-time events for better control and analytics:

Example listener:

window.addEventListener('message', (event) => {
  if (event.data.type === 'OKX_UI_TRANSACTION_SIGNED') {
    console.log('Transaction signed successfully');
  }
});

Use these events to update UI states, log analytics, or trigger post-action workflows.

Handling Errors Gracefully

Anticipate and respond to common errors using built-in codes:

Proper error handling improves user trust and reduces friction during onboarding.

Frequently Asked Questions (FAQ)

Q: Can I use this UI in Telegram Mini Apps?

Yes. The OKX UI fully supports Telegram environments, allowing users to connect via the OKX Mini Wallet without exiting the chat.

Q: Is it possible to customize the connect button?

Absolutely. You can hide the default button by omitting buttonRootId and build your own trigger that calls openModal() programmatically.

Q: Does it support automatic reconnection?

Yes. Set restoreConnection: true during initialization to restore active sessions when users revisit your DApp.

Q: What happens if a user rejects a transaction?

The sendTransaction() promise throws an error with code USER_REJECTS_ERROR. Handle it gracefully with user-friendly messages.

Q: Can I change the language dynamically?

Yes. Use setLanguage('es_ES') or similar methods to switch languages based on user preferences.

Q: Is SVG icon supported for DApp metadata?

No. Only PNG and ICO formats are currently supported. Use a 180x180px PNG for optimal rendering.

👉 Start integrating a seamless, secure wallet experience now.