UI Integration Guide for EVM-Compatible Chains & Web3 Wallet Connectivity

Introduction

Our SDK provides a ready-to-use UI interface for seamless integration. When your DApp runs within Telegram, users can choose to open the OKX App wallet or stay within Telegram to access the OKX Telegram Mini Wallet.

Installation via npm

npm install @okx/web3-connect-ui

Initialization

Before connecting a wallet, create an instance to handle wallet connections, transactions, and other operations.

Request Parameters

Parameter	Type	Description
DAppMetaData	object	App metadata: `name` (string) and `icon` (URL to 180x180px PNG)
actionsConfiguration	object	Configures modals (`before`/`success`/`error`) and return strategies for deep linking
uiPreferences	object	Sets `theme` (DARK/LIGHT/SYSTEM) and `language` (default: en_US)
restoreConnection	boolean	Auto-reconnects previous sessions

Example

const connectUI = new OKXUniversalConnectUI({
  DAppMetaData: { name: "MyDApp", icon: "https://example.com/icon.png" },
  actionsConfiguration: { modals: ['before'], returnStrategy: 'tg://resolve' },
  uiPreferences: { theme: "SYSTEM", language: "en_US" }
});

Connecting a Wallet

Retrieve wallet addresses for identification and transaction signing:

await universalUi.openModal({
  namespaces: { eip155: { chains: ["eip155:1"], rpcMap: {"1": "https://eth.llamarpc.com"} } },
  optionalNamespaces: { eip155: { chains: ["eip155:42161"] } }
});

Response

topic: Session ID
accounts: Connected wallet addresses
chains: Supported chain IDs

Wallet Connection with Signature

Connect and sign data in one step. Signatures are returned via connect_signResponse events.

Example

await universalUi.openModalAndSign({
  namespaces: { eip155: { chains: ["eip155:1"] } },
  signRequest: [{
    method: "personal_sign",
    chainId: "eip155:1",
    params: ["0x68656c6c6f20776f726c64"]
  }]
});

Checking Wallet Connection Status

const isConnected = universalUi.isConnected();

Transaction Preparation

Send transactions or signature requests:

const txHash = await universalUi.request({
  method: "eth_sendTransaction",
  params: [{ to: "0x...", value: "0x..." }],
  chain: "eip155:1"
});

Using Custom RPC Endpoints

Extend functionality by configuring EVM-compatible RPC URLs during wallet connection:

rpcMap: {
  "1": "https://eth.llamarpc.com",
  "42161": "https://arb1.arbitrum.io/rpc"
}

Event Handling

Listen for modal state changes and session updates:

universalUi.on('modal_state', (state) => { /* handle state */ });
// Remove listener when done
universalUi.off('modal_state');

Error Codes

Code	Description
ALREADY_CONNECTED_ERROR	Wallet already connected
CHAIN_NOT_SUPPORTED	Unsupported blockchain network
USER_REJECTS_ERROR	User declined the request

FAQ

How do I handle user rejection errors?

Implement fallback logic when receiving USER_REJECTS_ERROR:

try {
  await connectWallet();
} catch (err) {
  if (err.code === 'USER_REJECTS_ERROR') showAlternativeOptions();
}

Can I change the UI theme dynamically?

Yes, use setUIConfig():

universalUi.setUIConfig({ theme: "DARK", language: "zh_CN" });

What's the recommended RPC configuration?

Always include backup RPC URLs for reliability:
👉 Best practices for RPC configuration

How do Telegram Mini Apps handle returns?

Configure tmaReturnUrl as back to close the wallet after signing and return to your DApp.

👉 [Learn more about Telegram Mini Apps](https://www.okx.com/join/BLOCKSTAR)

For additional examples and advanced configurations, refer to our EVM-compatible chain documentation.