Ton Connect Integration with OKX Wallet UI: A Developer Guide

Integrating cryptocurrency wallets into decentralized applications (DApps) is a critical step in delivering seamless user experiences. For developers building on The Open Network (TON), OKX Wallet offers a powerful and flexible solution through its OKXTonConnectUI interface. This guide walks you through the full integration process, from initialization to transaction handling, while supporting both mobile App Wallet and Telegram Mini Wallet environments.

Whether you're upgrading from Ton Connect or migrating from OKX Connect, this UI-based approach reduces development time, supports multi-network requests, and ensures smooth user interactions across platforms.

👉 Discover how to integrate TON wallet connectivity with minimal code effort.

Why Use OKX Wallet UI for TON DApps?

The OKXTonConnectUI SDK provides a ready-to-use user interface that simplifies wallet connection workflows. Unlike low-level SDKs that require custom UI development, this solution delivers:

One-click wallet connection via embedded buttons
Native support for Telegram Mini Apps, allowing users to stay within Telegram
Automatic session restoration for returning users
Real-time event monitoring and error handling
Multi-language and theme support for global accessibility

By leveraging OKXTonConnectUI, developers can focus on core DApp functionality instead of reinventing authentication flows.

Core Keywords

Ton Connect
OKX Wallet
TON DApp integration
Telegram Mini Wallet
Web3 wallet connection
Blockchain API
Decentralized exchange (DEX)
Wallet SDK

Installation via NPM

To get started, install the OKX Ton Connect UI package using npm:

npm install @okxweb3/ton-connect-ui

This lightweight library includes all necessary components for wallet connectivity, including UI elements, event handlers, and transaction signing utilities.

Initialization: Setting Up OKXTonConnectUI

Before enabling wallet connections, initialize the OKXTonConnectUI object with your DApp’s metadata and configuration preferences.

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

const okxTonConnectUI = new OKXTonConnectUI({
  dappMetaData: {
    name: 'My TON DApp',
    icon: 'https://example.com/icon-180x180.png'
  },
  buttonRootId: 'ton-connect-button',
  actionsConfiguration: {
    modals: 'all',
    returnStrategy: 'tg://resolve',
    tmaReturnUrl: 'back'
  },
  uiPreferences: {
    theme: THEME.LIGHT
  },
  language: 'en_US',
  restoreConnection: true
});

Key Parameters Explained

dappMetaData.name: Your DApp’s display name (not used as identifier).
icon: Must be a direct URL to a PNG or ICO file (180x180px recommended; SVG not supported).
buttonRootId: The HTML element ID where the connect button will render.
returnStrategy: For Telegram environments, use tg://resolve to return users after signing.
tmaReturnUrl: Set to 'back' so users return to your DApp after closing the Mini Wallet.
restoreConnection: When true, automatically reconnects users on page reload if previously connected.

👉 See how top TON DApps streamline onboarding with smart wallet integration.

Monitor Wallet State Changes

Track connection status in real time using the onStatusChange method. It detects events like successful connection, reconnection, or disconnection.

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

// Unsubscribe when no longer needed
// okxTonConnectUI.offStatusChange();

This listener is essential for updating UI states, enabling features only when authenticated, or showing personalized content.

Connect to Wallet

The connection process retrieves the user’s wallet address—required for identifying accounts and signing transactions.

If you’ve set a buttonRootId, the "Connect" button appears automatically. Otherwise, trigger it programmatically:

await okxTonConnectUI.openModal();

This opens a modal interface where users choose between opening the OKX mobile App Wallet or launching the Telegram Mini Wallet directly within the chat environment.

Set tonProof for Secure Authentication

To enhance security and verify user ownership of the wallet, use tonProof—a signed message challenge.

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

// Once ready
okxTonConnectUI.setConnectRequestParameters({
  state: 'ready',
  value: 'your-payload-here'
});

// To remove
// okxTonConnectUI.setConnectRequestParameters(null);

This feature helps prevent impersonation and is ideal for gated content or private DApp features.

Get Connected Wallet Information

Retrieve details about the currently connected wallet using:

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

This data enables personalized experiences, such as balance checks or transaction history display.

Send Transactions Securely

Use sendTransaction to request user approval for on-chain actions:

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

try {
  const result = await okxTonConnectUI.sendTransaction(transaction, {
    modals: 'all',
    returnStrategy: 'tg://resolve'
  });
  console.log('Transaction BOC:', result.boc);
} catch (error) {
  console.error('Transaction failed:', error);
}

The boc (Bag of Cells) response contains the signed transaction, ready for blockchain submission.

Disconnect from Wallet

Allow users to securely disconnect at any time:

await okxTonConnectUI.disconnect();

This clears local session data and resets the connection state.

Customize UI Configuration

Adjust theme and language dynamically after initialization:

okxTonConnectUI.setUiOptions({
  theme: THEME.DARK,
  language: 'zh_CN'
});

These settings improve accessibility and align with user preferences or system defaults.

Listen to Real-Time Events

Enhance user feedback by listening to lifecycle events:

window.addEventListener('message', (event) => {
  switch (event.data.type) {
    case 'OKX_UI_CONNECTION_STARTED':
      console.log('Connection initiated');
      break;
    case 'OKX_UI_TRANSACTION_SIGNED':
      console.log('Transaction approved by user');
      break;
    case 'OKX_UI_DISCONNECTION':
      console.log('Wallet disconnected');
      break;
  }
});

Supported events include:

Connection start/completion/error
Reconnection attempts
Transaction signing status
Disconnection triggers

These events help build responsive interfaces with loading indicators, success messages, or error alerts.

Handle Common Error Codes

Anticipate and manage errors gracefully using standardized codes:

Error Code	Meaning
`UNKNOWN_ERROR`	Unexpected internal issue
`ALREADY_CONNECTED_ERROR`	Prevent duplicate connections
`NOT_CONNECTED_ERROR`	No active wallet session
`USER_REJECTS_ERROR`	User denied request
`METHOD_NOT_SUPPORTED`	Feature unavailable
`CHAIN_NOT_SUPPORTED`	Incompatible network
`WALLET_NOT_SUPPORTED`	Unsupported wallet type
`CONNECTION_ERROR`	Network or protocol failure

Use these codes to display context-aware messages and guide users toward resolution.

Frequently Asked Questions (FAQ)

Q: Can I use OKXTonConnectUI in non-Telegram environments?
A: Yes. While optimized for Telegram Mini Apps, it works seamlessly in standard web browsers and mobile DApps.

Q: Is SVG icon support planned?
A: Currently only PNG and ICO formats are supported. Use rasterized icons for compatibility.

Q: How does session restoration work?
A: When restoreConnection: true, the SDK checks for existing sessions on page load and reconnects silently if valid.

Q: What happens if a user rejects a transaction?
A: The promise rejects with USER_REJECTS_ERROR, which you should catch and handle gracefully in your UI.

Q: Can I customize the connection modal?
A: Limited customization is available via uiPreferences. Full UI overrides require using the base SDK instead.

Q: Does this support multiple wallet connections?
A: No—only one wallet can be connected at a time per session.

👉 Start integrating secure TON wallet access in under 10 minutes.

With robust event handling, cross-platform compatibility, and minimal setup requirements, OKXTonConnectUI empowers developers to deliver professional-grade Web3 experiences on the TON blockchain. By focusing on usability and reliability, it accelerates DApp deployment while maintaining high security standards.