UI Integration for EVM-Compatible Chains: Connect Your DApp or Mini Wallet

Integrating a seamless and secure wallet connection into your decentralized application (DApp) is essential for delivering a smooth user experience. With the OKX Connect SDK, developers can easily implement wallet connectivity for EVM-compatible blockchains, enabling users to sign transactions, manage assets, and interact with Web3 services across platforms—including mobile apps and Telegram Mini Wallets.

This guide walks you through the full integration process, from initialization to disconnecting sessions, with clear code examples and best practices. Whether you're building a DApp, a mini-app on Telegram, or integrating multi-chain support, this documentation ensures your project remains compatible, user-friendly, and efficient.

Installation via npm

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

npm install @okxweb3/connect

Ensure your environment supports modern JavaScript (ES6+) and that you're using a bundler like Webpack or Vite for frontend integration.

👉 Discover how to set up wallet connectivity in under 5 minutes

Initialize the SDK

Before connecting to any wallet, initialize the OKXUniversalConnectUI instance with configuration options tailored to your app’s needs.

Request Parameters

• dappMetaData (object)

  • name (string): Your DApp's display name.
  • icon (string): URL of your app icon (PNG or ICO format recommended; SVG not supported). Use a 180x180px image for optimal display.

• actionsConfiguration (object)

  • modals: Controls when alerts appear during transactions ('before', 'success', 'error', or 'all'). Default: 'before'.
  • returnStrategy: Specifies deep link behavior after user action in app wallets (e.g., 'okx://wallet'). For Telegram bots, use tg://resolve.

• tmaReturnUrl (string)

  • For Telegram Mini Apps: 'back' returns to the DApp after signing; 'none' takes no action. Default: 'back'.

• uiPreferences (object)

  • theme: Choose between THEME.DARK, THEME.LIGHT, or 'SYSTEM' for automatic theme detection.
  • language: Supported languages include 'en_US', 'zh_CN', 'es_ES', 'fr_FR', and more. Defaults to 'en_US'.

• restoreConnection (boolean, optional)

  • If true, automatically restores the last active session on app reload.

Return Value

• Returns an instance of OKXUniversalConnectUI for further operations.

Example

import { OKXUniversalConnectUI } from '@okxweb3/connect';

const okxConnect = new OKXUniversalConnectUI({
  dappMetaData: {
    name: 'My Web3 DApp',
    icon: 'https://example.com/icon.png'
  },
  actionsConfiguration: {
    modals: 'all',
    returnStrategy: 'myapp://return'
  },
  tmaReturnUrl: 'back',
  uiPreferences: {
    theme: 'SYSTEM',
    language: 'en_US'
  },
  restoreConnection: true
});

Connect to a Wallet

Establish a secure session by requesting access to the user’s wallet address and transaction signing capabilities.

Request Parameters

• connectParams (ConnectParams)

  • namespaces: Required chain namespace (e.g., "eip155" for EVM chains).
  • chains: Array of chain IDs in EIP-155 format (e.g., ["eip155:1", "eip155:137"]).
  • defaultChain: Optional default chain ID.
  • rpcMap: Map of custom RPC URLs per chain ID (only EVM supported).
  • optionalNamespaces: Additional chains; connection proceeds even if unsupported. Useful for custom networks.

Return Value

A Promise resolving to:

• topic: Session identifier.
• namespaces: Confirmed namespaces.
• chains: Connected chain IDs.
• accounts: Wallet addresses.
• methods: Supported methods (e.g., personal_sign).
• sessionConfig, dappInfo: Metadata about session and DApp.

Example

const session = await okxConnect.connect({
  namespaces: {
    eip155: {
      chains: ['eip155:1'],
      methods: ['personal_sign'],
      events: ['chainChanged', 'accountsChanged']
    }
  },
  rpcMap: {
    'eip155:1': 'https://mainnet.infura.io/v3/YOUR_KEY'
  }
});

👉 See real-world DApp integration examples now

Sign Data and Connect

Combine connection with immediate data signing, such as signing login messages.

Additional Parameter

• signRequest: Array containing one request object with:

  • method: E.g., 'personal_sign'.
  • chainId: Target chain (must be in namespaces).
  • params: Signing payload (e.g., [message, address]).

The result triggers the 'connect_signResponse' event.

Check Connection Status

Verify whether a wallet is currently connected.

Return Value

• Boolean: true if connected, otherwise false.

Example

if (okxConnect.isConnected()) {
  console.log('Wallet is connected');
}

Prepare and Send Transactions

Send requests for signatures or blockchain transactions.

Parameters

• method: E.g., eth_sendTransaction, eth_signTypedData.
• params: Method-specific arguments.
• chain: Chain ID (recommended).
• actionConfigurationRequest: Customize modal behavior and return strategy.

Return Value

Same as standard EVM transaction response—supports all EIP-155 compliant chains.

Use Custom RPC Endpoints

For non-standard or private EVM networks, configure custom RPCs via rpcMap during connection:

rpcMap: {
  'eip155:99999': 'https://my-custom-chain-rpc.com'
}

Ensure the chain ID is listed in chains.

Manage Session Information

Retrieve details of the active session:

const sessionInfo = okxConnect.getSessionInfo();
console.log(sessionInfo.accounts);

Useful for UI updates and state management.

Update UI Settings Dynamically

Change theme or language post-initialization:

okxConnect.setTheme('DARK');
okxConnect.setLanguage('zh_CN');

Also configurable during initialization.

Set Default Chain

When supporting multiple chains, define the default:

okxConnect.setDefaultChain('eip155:137'); // Polygon

All unsigned actions will default to this chain unless specified otherwise.

Disconnect Wallet

Terminate the current session securely:

await okxConnect.disconnect();

Clears local session data and notifies the wallet.

Handle Events

Listen for real-time updates:

okxConnect.on('connect', (data) => console.log('Connected:', data));
okxConnect.on('disconnect', () => console.log('Disconnected'));
okxConnect.on('accountsChanged', (accounts) => updateUI(accounts));

Supported events: connect, disconnect, accountsChanged, chainChanged.

Error Handling

Common error codes during interactions:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR – Unexpected failure
• ALREADY_CONNECTED_ERROR – Attempted duplicate connection
• NOT_CONNECTED_ERROR – Action requires active session
• USER_REJECTS_ERROR – User denied request
• METHOD_NOT_SUPPORTED – Unsupported RPC method
• CHAIN_NOT_SUPPORTED – Chain not available in wallet
• CONNECTION_ERROR – Network or handshake failure

Handle these gracefully in your UI to improve user experience.

Frequently Asked Questions

How do I support custom EVM networks?

Include your chain in optionalNamespaces and provide an RPC URL via rpcMap. If the wallet doesn’t recognize it, use wallet_addEthereumChain later.

Can I integrate with Telegram Mini Wallets?

Yes. Set tmaReturnUrl: 'back' and use Telegram-safe deep links. The SDK fully supports TMA (Telegram Mini App) environments.

What permissions does OKX Connect request?

Only basic account access and signing permissions. No private keys are exposed. Users approve each action.

Is SVG icon supported for DApp metadata?

No. Only PNG or ICO formats are accepted. Use a 180x180px PNG for best results.

How do I restore a previous session?

Enable restoreConnection: true during initialization. The SDK checks for valid sessions on load.

Which EVM chains are supported?

All EIP-155 compliant chains—including Ethereum, BSC, Polygon, Arbitrum, Optimism, and custom networks.

👉 Start integrating today—get full SDK access instantly