Integrating your decentralized application (DApp) with EVM-compatible chains has never been easier with OKX Connect. This comprehensive guide walks you through the entire process—from initialization to error handling—using Markdown formatting and SEO best practices.
Why Use OKX Connect for EVM-Compatible Chains?
👉 Discover how OKX Connect simplifies blockchain integration
OKX Connect provides a seamless way to:
– Connect wallets to DApps
– Sign transactions securely
– Interact with EVM-compatible chains efficiently
Getting Started with OKX Connect
Prerequisites
- Ensure the OKX App is updated to version 6.90.1 or later.
- Basic familiarity with npm and JavaScript.
Installation via npm
bash
npm install @okx/okx-connect
Initializing OKX Connect
Before connecting to a wallet, initialize the OKX Connect object with the following parameters:
Request Parameters
| Parameter | Type | Description |
|---|---|---|
dappMetaData.name |
string | Your DApp’s name (non-unique identifier) |
dappMetaData.icon |
string | URL of a 180x180px PNG/ICO icon (SVG not supported) |
actionsConfiguration.modals |
array | Alert display modes: before, success, error, or all |
uiPreferences.theme |
enum | THEME.DARK, THEME.LIGHT, or SYSTEM |
language |
string | Supports en_US, zh_CN, ar_AE, and 20+ other languages |
Return Value: OKXUniversalConnectUI object for subsequent operations.
Connecting to a Wallet
Key Request Parameters
| Parameter | Type | Description |
|---|---|---|
namespaces |
object | Required connection details (use eip155 for EVM chains) |
chains |
array | Chain IDs (e.g., eip155:1 for Ethereum) |
optionalNamespaces |
object | Custom network requests (falls back if unsupported) |
Example:
javascript
const result = await connectWallet({
namespaces: { eip155: { chains: ['eip155:1'] } }
});
Return Value:
– topic: Session ID
– accounts: Connected wallet addresses
– methods: Supported wallet methods (e.g., personal_sign)
Signing Transactions
👉 Learn advanced signing techniques
To sign data after connecting:
1. Specify the method (e.g., personal_sign).
2. Include the chainId and params for the transaction.
Error Handling:
– Rejected connections throw OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR.
– Unsupported chains trigger OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED.
Managing Sessions
Check Connection Status
javascript
const isConnected = checkWalletConnection(); // Returns boolean
Disconnect a Wallet
javascript
disconnectWallet();
Advanced Features
Custom RPC Configuration
Override default RPC endpoints via rpcMap:
javascript
rpcMap: { 'eip155:1': 'https://custom.ethereum.rpc' }
UI Customization
Update themes or languages dynamically:
javascript
setUIConfig({ theme: THEME.DARK, language: 'fr_FR' });
Error Codes Reference
| Code | Description |
|---|---|
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR |
Unspecified failure |
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR |
Wallet disconnected |
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED |
Invalid operation |
FAQs
1. How do I handle unsupported chains?
Use optionalNamespaces to gracefully fall back or prompt users to add the chain manually via wallet_addEthereumChain.
2. Can I change the UI language after initialization?
Yes, call setUIConfig with the new language parameter.
3. What’s the default chain if none is specified?
The first chain in your namespaces or optionalNamespaces array.
4. How do I test error scenarios?
Simulate rejections or unsupported methods to trigger specific error codes.
5. Is SVG supported for DApp icons?
No—use PNG or ICO formats (180x180px recommended).
6. How are sessions restored?
Enable restoreConnection: true during initialization to reconnect automatically.
Final Thoughts
OKX Connect streamlines EVM-compatible chain integration with:
– Multi-language/theme support
– Custom RPC configuration
– Comprehensive error handling
👉 Start integrating OKX Connect today
For further reading, explore our EVM SDK documentation (links removed per guidelines).