UI Integration for TON: Connect App or Mini Wallet | Web3 Wallet & DEX API Guide

Integrating Web3 functionality into your decentralized application (DApp) has never been easier—especially when targeting users on Telegram. With the OKX TON Connect UI, developers can seamlessly enable wallet connections, transaction signing, and cross-network interactions with minimal setup. Whether your DApp runs within Telegram or as a standalone web experience, this guide walks you through every step of implementing a smooth, secure, and user-friendly onboarding flow.

Designed as a higher-level abstraction over the core SDK, the OKX TON Connect UI reduces development time while offering full control over appearance, localization, and behavior. It supports both native mobile wallet connections and in-app experiences via the OKX Telegram Mini Wallet, giving users flexibility without compromising security.

Why Use OKX TON Connect UI?

If you're building on The Open Network (TON), integrating wallet connectivity is essential—but so is keeping the user experience frictionless. The OKX TON Connect UI simplifies this by providing:

Pre-built UI components for connecting wallets
Support for multiple connection methods: App wallets and Telegram Mini Apps
Cross-network compatibility and request handling
Easy migration from existing Ton Connect or OKX Connect implementations
Customizable themes, languages, and return strategies

👉 Discover how to implement seamless Web3 authentication today.

Getting Started: Installation via npm

To begin, install the package using npm:

npm install @okxweb3/ton-connect-ui

This lightweight library includes everything needed to initialize the connection interface and interact with TON-compatible wallets.

Initializing the Connection Interface

Before connecting a wallet, instantiate the OKXTonConnectUI class with configuration options tailored to your DApp:

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

Configuration Parameters

dappMetaData: Object containing your app’s name and icon URL (PNG format recommended, ideally 180x180px).
buttonRootId: The HTML element ID where the connect button will be injected. Omitting this means manual trigger handling.
actionsConfiguration:
- modals: Controls which confirmation modals appear ('before', 'success', 'error', or 'all')
- returnStrategy: Deep link strategy after user action (e.g., tg://resolve for Telegram)
- tmaReturnUrl: For Telegram Mini Apps; use 'back' to return to your DApp post-signing
uiPreferences: Set theme (THEME.DARK, THEME.LIGHT, or "SYSTEM")
language: Supports multiple locales including en_US, zh_CN, ru_RU, and more (defaults to English)
restoreConnection: Optional boolean to automatically reconnect on page load

This setup ensures a localized, responsive experience aligned with your brand and platform context.

Monitoring Wallet Connection Status

Use the status change listener to detect real-time updates:

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

Events include successful connections, reconnections, and disconnections. Always unsubscribe when no longer needed to optimize performance.

👉 See live examples of dynamic wallet state management.

Connecting a Wallet

The UI automatically generates a connect button if buttonRootId is provided. Alternatively, trigger manually:

await okxTonConnectUI.openModal();

This opens a modal allowing users to choose between their preferred wallet method—either launching an external app or using the embedded OKX Telegram Mini Wallet.

Implementing tonProof Authentication

Securely verify user identity using tonProof. To prepare:

Set state to 'loading' while generating proof data
Once ready, update state to 'ready' and provide the signed value
Use setConnectRequestParameters(null) to remove the loading state if needed

This cryptographic handshake enhances trust and enables personalized experiences.

Closing the Connection Modal Programmatically

In certain flows (e.g., timeouts or conditional logic), you may want to close the connection prompt:

okxTonConnectUI.closeModal();

This provides fine-grained control over user interaction timing.

Retrieving Connected Wallet Information

After connection, access wallet details including address and network:

const wallet = okxTonConnectUI.getWallet();
if (wallet) {
  const { address } = wallet.account;
  console.log("User address:", address);
}

This data is crucial for personalizing content, tracking sessions, or initiating transactions.

Disconnecting from the Wallet

Allow users to disconnect cleanly:

await okxTonConnectUI.disconnect();

This clears local session data and notifies the wallet, ensuring privacy and security.

Sending Transactions Securely

Initiate blockchain transactions with:

const result = await okxTonConnectUI.sendTransaction(transaction, actionConfigurationRequest);

Transaction Parameters

transaction: Standard TON message object (address, amount, payload)
actionConfigurationRequest: Optional modal and return behavior settings

Returns a promise resolving to { boc: string }, the signed message cell that can be broadcasted to the network.

Customizing UI Preferences Dynamically

Change theme or language at runtime:

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

Ideal for apps that support dynamic mode switching or multi-language audiences.

Listening to UI Events

Enhance interactivity by reacting to key lifecycle events:

Event Name	Trigger Condition
`OKX_UI_CONNECTION_STARTED`	User begins connection
`OKX_UI_CONNECTION_COMPLETED`	Wallet successfully connected
`OKX_UI_CONNECTION_ERROR`	Connection canceled or failed
`OKX_UI_DISCONNECTION`	User initiates disconnect
`OKX_UI_TRANSACTION_SENT_FOR_SIGNATURE`	Transaction sent to wallet
`OKX_UI_TRANSACTION_SIGNED`	User approved and signed

Subscribe using standard event listeners to build responsive feedback systems.

Error Handling and Troubleshooting

Common error codes help diagnose issues:

UNKNOWN_ERROR: Unexpected failure
ALREADY_CONNECTED_ERROR: Prevent duplicate connections
NOT_CONNECTED_ERROR: Ensure connection before actions
USER_REJECTS_ERROR: User declined request
CHAIN_NOT_SUPPORTED: Incompatible network selected
CONNECTION_ERROR: Network or handshake failure

Handle these gracefully in your UI to maintain user trust.

👉 Access comprehensive developer tools and debugging resources.

Frequently Asked Questions (FAQ)

Q: Can I use this UI if my DApp runs outside Telegram?
A: Yes. While optimized for Telegram Mini Apps, it works equally well on standard web platforms.

Q: Is migration from Ton Connect straightforward?
A: Absolutely. If you're already using Ton Connect standards, integration requires minimal code changes.

Q: Does it support multiple networks simultaneously?
A: Yes. With ProviderUI support, you can manage requests across different chains in one session.

Q: What permissions does the wallet request?
A: Only basic account info by default. Additional permissions like tonProof require explicit user consent.

Q: How secure is the Telegram Mini Wallet integration?
A: All private keys remain in the user's wallet. Your DApp never accesses sensitive data.

Q: Can I customize the look of the connect button?
A: While default styling is provided, you can hide the built-in button and create your own trigger using openModal().

By leveraging the OKX TON Connect UI, developers gain a powerful, production-ready solution for Web3 onboarding—combining ease of use with enterprise-grade reliability. Whether you're launching a new DApp or enhancing an existing one, this toolkit accelerates development while ensuring a polished user journey across devices and platforms.