@okxconnect/ui: Integrate Web3 Wallet Connectivity with Ease

·

Integrating blockchain wallet connectivity into your decentralized application (DApp) has never been simpler. With @okxconnect/ui, developers can seamlessly enable users to connect wallets, sign transactions, and manage their digital identities—especially within Telegram-based environments. This lightweight yet powerful UI SDK enhances user experience by supporting in-app interactions through mobile wallets or the OKX Mini Wallet, all without leaving the Telegram interface.

Whether you're building a DApp for TON (The Open Network) or enhancing Web3 accessibility on messaging platforms, this guide walks you through setup, configuration, and advanced features while ensuring optimal readability and SEO performance.

Why Use @okxconnect/ui?

The @okxconnect/ui package builds upon the core OKX Connect SDK by adding a ready-to-use user interface. It streamlines wallet integration with minimal code, making it ideal for developers aiming to reduce friction in onboarding users. Key advantages include:

Core keywords naturally integrated: @okxconnect/ui, Web3 wallet integration, Telegram DApp, TON wallet connection, blockchain SDK, decentralized app, OKX Mini Wallet, send transaction.

Installation via npm

Start by installing the package using npm:

npm install @okxconnect/ui

This command adds the latest version of the library to your project dependencies, enabling immediate access to UI components and connection logic.

👉 Discover how easy it is to integrate Web3 functionality into your DApp today.

Initialize the SDK

Before connecting a wallet, initialize the OKXTonConnectUI instance with essential metadata and preferences.

Parameters

new OKXTonConnectUI({
  dappMetaData,
  buttonRootId,
  actionsConfiguration,
  uiPreferences,
  language,
  restoreConnection
});

dappMetaData

buttonRootId

Specify the HTML element ID where the "Connect Wallet" button will be injected. If omitted, no button appears automatically.

actionsConfiguration

uiPreferences

Set the visual theme: THEME.LIGHT, THEME.DARK, or 'SYSTEM'.

language

Supported values: 'en_US', 'ru_RU', 'zh_CN'. Defaults to English.

restoreConnection

Optional boolean to re-establish the last active wallet session on load.

Example Initialization

import { OKXTonConnectUI, THEME } from "@okxconnect/ui";

const okxTonConnectUI = new OKXTonConnectUI({
  dappMetaData: {
    name: "My DApp",
    icon: "https://mydapp.com/icon.png"
  },
  buttonRootId: "connect-button",
  actionsConfiguration: {
    returnStrategy: "none",
    tmaReturnUrl: "back"
  },
  uiPreferences: {
    theme: THEME.LIGHT
  },
  language: "en_US",
  restoreConnection: true
});

Connect a Wallet

Trigger the wallet connection flow manually or via an auto-generated button.

Manual Trigger

await okxTonConnectUI.openModal();

If no buttonRootId was provided during initialization, call this method directly from your UI logic (e.g., button click handler).

Auto Button Injection

Ensure an HTML element with the specified ID exists:

<div id="connect-button"></div>

The SDK injects a fully styled connect button here.

👉 See how leading DApps simplify wallet access with one-click integration.

Set tonProof Authentication

Use tonProof to verify user identity securely during connection.

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

const tonProofPayload = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
  okxTonConnectUI.setConnectRequestParameters(null);
} else {
  okxTonConnectUI.setConnectRequestParameters({
    state: "ready",
    value: { tonProof: tonProofPayload }
  });
}

This pattern ensures smooth UX—show loading states while fetching proof, then proceed when ready.

Manage Connection State

Get Current Wallet Info

const wallet = okxTonConnectUI.wallet;
const account = okxTonConnectUI.account;
const isConnected = okxTonConnectUI.connected;

These properties reflect real-time connection status and user data.

Disconnect Wallet

okxTonConnectUI.disconnect();

Clears the current session and updates state accordingly.

Close Modal Programmatically

okxTonConnectUI.closeModal();

Useful for custom navigation or error handling.

Listen to Wallet Status Changes

Subscribe to connection lifecycle events:

import { Wallet } from "@okxconnect/ui";

const unsubscribe = okxTonConnectUI.onStatusChange(
  (walletInfo: Wallet | null) => {
    console.log('Connection status:', walletInfo);
  },
  (err) => {
    console.error('Connection error:', err);
  }
);

// Call unsubscribe() when no longer needed
unsubscribe();

This observer pattern helps track successful connections, disconnections, or errors in real time.

Send Transactions Securely

Initiate and sign blockchain transactions with ease.

Method Signature

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

Transaction Object

Includes:

actionConfigurationRequest

Example Usage

import { OKXConnectError, OKX_CONNECT_ERROR_CODES } from "@okxconnect/core";

const transactionRequest = {
  validUntil: Math.floor(Date.now() / 1000) + 360,
  from: "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
  messages: [
    {
      address: "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
      amount: "20000000",
      stateInit: "base64bocblahblahblah=="
    }
  ]
};

okxTonConnectUI.sendTransaction(transactionRequest, {
  modals: 'all',
  tmaReturnUrl: 'back'
})
.then((result) => {
  const boc = result.boc;
  console.log("Signed transaction BOC:", boc);
})
.catch((error) => {
  if (error instanceof OKXConnectError && error.code === OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
    console.log("User rejected the transaction.");
  } else {
    console.error("Transaction failed:", error);
  }
});

Customize UI Preferences Dynamically

Update language or theme at runtime:

okxTonConnectUI.uiOptions = {
  language: 'zh_CN',
  uiPreferences: {
    theme: THEME.DARK
  }
};

This flexibility improves localization and accessibility across diverse user bases.

Monitor Events with Global Listeners

React to key moments in the user journey using standard DOM events.

Available Events

Add Event Listener

import { OKX_UI_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/ui";

window.addEventListener(OKX_UI_CONNECTION_AND_TRANSACTION_EVENT.OKX_UI_CONNECTION_STARTED, (event) => {
  if (event instanceof CustomEvent) {
    console.log('Connection initiated:', event.detail);
  }
});

These events empower analytics tracking, loading indicators, and UX enhancements.

Frequently Asked Questions (FAQ)

Can I use @okxconnect/ui outside of Telegram?

Yes. While optimized for Telegram Mini Apps, it works across standard web environments. The UI adapts based on context.

Does it support multiple wallets?

Currently focused on OKX Wallet and TON-compatible wallets. Future updates may expand compatibility.

Is user data stored?

No. All authentication and signing occur client-side. The SDK does not collect or store personal information.

How do I handle errors during transaction signing?

Catch errors using .catch() on sendTransaction(). Check for known error codes like USER_REJECTS_ERROR.

Can I hide success modals?

Yes. Configure modals: ['before'] to show only pre-signing confirmation, suppressing success/error popups.

Is there a way to test without a real wallet?

Use testnet versions of supported wallets and simulate payloads locally during development.

👉 Start building your next-generation Web3 experience now—effortless integration starts here.