UI Integration for EVM-Compatible Chains with OKX Connect

Integrating wallet connectivity into decentralized applications (dApps) is a critical step in delivering seamless user experiences on blockchain platforms. For developers building on EVM-compatible chains, OKX Connect offers a robust, developer-friendly SDK that simplifies wallet integration while supporting advanced features like multi-chain connectivity, transaction signing, and customizable UI behavior.

To get started, ensure your OKX App is updated to version 6.90.1 or later, enabling full access to the latest OKX Connect capabilities.

Installing OKX Connect via npm

The easiest way to integrate OKX Connect into your dApp is through npm:

npm install @okxconnect/connect

This lightweight package provides all necessary tools for initializing sessions, managing connections, and handling transactions across EVM-compatible networks.

Initializing the SDK

Before connecting to a wallet, you must initialize the OKX Connect interface with configuration options tailored to your application’s needs.

Key Initialization Parameters

dappMetaData
- name: Your dApp’s display name (non-unique).
- icon: Public URL to a 180x180px PNG icon (SVG not supported).
actionsConfiguration
- modals: Controls when alerts appear during transactions — 'before', 'success', 'error', or 'all'. Default: 'before'.
- returnStrategy: Deep link strategy after user action in app wallet (e.g., myapp://return).
- tmaReturnUrl: For Telegram Mini Wallet; use 'back' to return to dApp post-signing (default), or 'none' for no redirect.
uiPreferences
- theme: Supports THEME.DARK, THEME.LIGHT, or 'SYSTEM' for auto-detection.
- language: Choose from supported locales including 'en_US', 'zh_CN', 'es_ES', 'fr_FR', and more. Defaults to 'en_US'.
restoreConnection (optional)
Set to true to automatically reconnect users on return visits.

👉 Discover how easy it is to integrate secure, multi-chain wallet access into your dApp.

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

const okxConnect = new OKXUniversalConnectUI({
  dappMetaData: {
    name: 'My DeFi Dashboard',
    icon: 'https://mydapp.com/icon.png'
  },
  actionsConfiguration: {
    modals: 'all',
    returnStrategy: 'mydapp://return',
    tmaReturnUrl: 'back'
  },
  uiPreferences: {
    theme: THEME.LIGHT,
    language: 'en_US'
  },
  restoreConnection: true
});

Returns: An instance of OKXUniversalConnectUI ready for connection workflows.

Connecting to a Wallet

Establishing a wallet connection grants your dApp access to the user’s address and transaction-signing capabilities.

Request Parameters

namespaces: Required namespace object. For EVM chains, use "eip155" as the key.
chains: Array of chain IDs in EIP-155 format (e.g., eip155:1 for Ethereum).
defaultChain (optional): Sets the default network for operations.
rpcMap (optional): Map chain IDs to custom RPC endpoints (only EVM-supported).
optionalNamespaces: Include fallback chains or custom networks. If unsupported, connection proceeds without them.

⚠️ If any required chain in namespaces isn't supported by the wallet, the connection will be rejected.

Returns a Promise resolving to:

topic: Unique session identifier.
namespaces: Confirmed namespace details.
chains: Active connected chains.
accounts: User wallet addresses.
methods: Supported signing/transaction methods.
defaultChain: Current default chain.
dappInfo: Registered app metadata.

Connect and Sign in One Step

You can initiate both connection and data signing simultaneously using openModalAndSign.

Extended Parameters

Includes all connection fields plus:

signRequest: Array containing one request object:
- method: e.g., 'personal_sign'.
- chainId: Must match one from namespaces.
- params: Data to sign (e.g., message hash and address).

Upon success, the event 'connect_signResponse' returns the signature.

👉 See how top dApps streamline onboarding with one-click wallet connect and sign flows.

Check Wallet Connection Status

Determine if a wallet is currently connected:

const isConnected = okxConnect.isConnected();

Returns: Boolean value indicating active session status.

Useful for conditional rendering and protecting sensitive actions behind authentication checks.

Prepare and Send Transactions

Use requestArguments to send signing requests or execute transactions.

Parameters

method: Such as eth_sendTransaction, eth_signTransaction, or personal_sign.
params: Method-specific arguments.
chain: Target chain ID (defaults to current session’s default chain).
actionConfigurationRequest: Overrides global modal/display settings:
- modals: Alert timing.
- tmaReturnUrl: Post-sign behavior in Telegram Mini Wallet.

For full details on response formats, refer to EVM-compatible transaction handling documentation.

Using Custom RPC Endpoints

When default methods are insufficient, configure custom RPCs via rpcMap during connection:

rpcMap: {
  'eip155:1': 'https://eth-mainnet.my-custom-rpc.com',
  'eip155:137': 'https://polygon-rpc.com'
}

This enables interaction with private nodes or enhanced performance layers.

✅ Ensure configured chains are listed in the chains array.

Manage Active Sessions

Get Current Session Info

Retrieve live session data:

const session = okxConnect.getSession();

Returns account, chain, method, and namespace details — ideal for dynamic UI updates.

Set Default Chain

Switch the active network context:

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

Ensures correct routing when multiple chains are available.

Disconnect Wallet

Terminate the current session cleanly:

await okxConnect.disconnect();

Clears local state and revokes dApp permissions securely.

Customize UI Settings

Update theme or language dynamically:

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

Improves accessibility and aligns with user preferences without requiring reinitialization.

Handle Events and Errors

Supported Events

Listen for real-time updates:

'connect': On successful connection.
'disconnect': When session ends.
'signResponse': Signature callback.
'session_update': Chain or account changes.

Common Error Codes

Code	Meaning
`OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR`	Unexpected internal error
`ALREADY_CONNECTED_ERROR`	Attempted duplicate connection
`NOT_CONNECTED_ERROR`	Action requires prior connection
`USER_REJECTS_ERROR`	User denied request
`METHOD_NOT_SUPPORTED`	Wallet doesn’t support requested method
`CHAIN_NOT_SUPPORTED`	Chain not available in wallet
`CONNECTION_ERROR`	Network or protocol failure

Handle these gracefully with user-facing messages and retry logic where appropriate.

FAQ

How do I support custom blockchain networks?

Include your network in optionalNamespaces with proper chain ID and RPC configuration. If the wallet doesn’t recognize it, call wallet_addEthereumChain afterward to prompt addition.

Can I connect without showing popups?

Yes — set modals: [] or 'none' in initialization or request-level configurations to suppress alerts.

Is Telegram Mini Wallet supported?

Absolutely. Use tmaReturnUrl: 'back' to ensure users return to your mini app after signing. Ideal for Web3 experiences within Telegram.

What happens if a user rejects a transaction?

The promise rejects with USER_REJECTS_ERROR. You should catch this and inform the user without retrying automatically.

Does OKX Connect support non-EVM chains?

Currently, only EVM-compatible chains are supported via the EIP-155 namespace. Support for other ecosystems may be expanded in future versions.

Can I restore a previous session automatically?

Yes — set restoreConnection: true during initialization to resume existing sessions on page reload or app restart.

👉 Start building smarter, faster dApps with seamless wallet integration today.