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

Integrating a secure, reliable wallet connection into your decentralized application (DApp) is essential for delivering a seamless user experience. With growing demand for cross-chain compatibility and mobile-first solutions, developers need efficient tools to connect apps with wallets across EVM-compatible blockchains. This guide walks you through integrating OKX Connect, a powerful SDK that enables smooth connectivity between your DApp or Telegram Mini App and the OKX Wallet.

Whether you're building on Ethereum, BSC, Polygon, or any EVM-compatible chain, this documentation covers installation, initialization, connection flow, transaction handling, and error management—all while maintaining high performance and security standards.

Installation and Initialization

Before beginning integration, ensure the OKX Wallet app is updated to version 6.88.0 or later. This version supports the latest Web3Connect features required for DApp interactions.

To install the OKX Universal Provider SDK via npm:

npm install @okxweb3/web3-provider

Once installed, initialize the provider with your DApp’s metadata. This step prepares the environment for wallet interaction.

import { OKXUniversalProvider } from '@okxweb3/web3-provider';

const provider = await OKXUniversalProvider.init({
  DAppMetaData: {
    name: 'My DApp',
    icon: 'https://mydapp.com/icon.png' // 180x180px PNG recommended
  }
});

Parameters

DAppMetaData – Object containing:
- name (string): Display name of your application. Not used as an identifier.
- icon (string): Public URL to your app's icon in PNG or ICO format. SVG is not supported. A 180×180px image is ideal for clarity across devices.

Returns

An instance of OKXUniversalProvider, used for all subsequent operations including connecting, signing, and sending transactions.

👉 Get started with seamless wallet integration today.

Connect to Wallet

Establishing a secure session allows your DApp to access the user’s wallet address—essential for authentication and transaction signing.

Use the connect() method with appropriate namespace and chain configurations:

const session = await okxUniversalProvider.connect({
  namespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:56'], // Ethereum Mainnet & BSC
      defaultChain: 'eip155:56',
      rpcMap: {
        'eip155:1': 'https://eth-mainnet.alchemyapi.io/v2/your-key',
        'eip155:56': 'https://bsc-dataseed.binance.org/'
      },
      methods: ['eth_sendTransaction', 'personal_sign'],
      events: ['chainChanged', 'accountsChanged']
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:137'], // Optional: Polygon
      methods: ['eth_signTypedData_v4'],
      events: ['disconnect']
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve' // For Telegram Mini Apps
  }
});

Parameters

namespaces: Required chain and method details. Must include supported chains under eip155 for EVM systems.
chains: Array of chain IDs (e.g., eip155:1 for Ethereum).
defaultChain: Sets the default blockchain for operations.
rpcMap: Custom RPC URLs per chain. Required if using non-standard endpoints.
optionalNamespaces: Allows connection even if some chains aren’t supported by the wallet.
sessionConfig.redirect: Redirect URI after successful connection. Use tg://resolve for Telegram Mini Apps.

Returns (Promise)

topic: Unique session identifier.
namespaces: Confirmed namespaces and chains.
accounts: Connected wallet addresses.
methods: Supported wallet methods.
defaultChain: Active default chain ID.
DAppInfo: Name, icon, and redirect info.

Check Wallet Connection Status

Verify whether a wallet is currently connected before initiating transactions or requests.

const isConnected = okxUniversalProvider.isConnected();
console.log(isConnected); // true or false

This synchronous method returns a boolean value indicating the current session status.

Send Signatures and Transactions

The core functionality of any Web3 app involves signing messages and sending transactions. Use the request() method to interact securely with the wallet.

// Sign a message
const signature = await okxUniversalProvider.request({
  method: 'personal_sign',
  params: ['0xHelloWorld', accounts[0]]
});

// Send a transaction
const txHash = await okxUniversalProvider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: accounts[0],
    to: '0x...',
    value: '0x29a2241af62c0000', // 1 ETH in hex
    gasLimit: '0x5208'
  }],
  chain: 'eip155:1'
});

Supported Methods

Method	Description	Return Type
`personal_sign`	Sign arbitrary data	Hex string
`eth_signTypedData_v4`	Sign structured data (EIP-712)	Hex string
`eth_sendTransaction`	Send a signed transaction	Transaction hash
`eth_accounts` / `eth_requestAccounts`	Get connected addresses	String array
`eth_chainId`	Retrieve current chain ID	Number
`wallet_switchEthereumChain`	Switch user’s active network	null
`wallet_addEthereumChain`	Add a new custom chain	null
`wallet_watchAsset`	Add token to wallet watchlist	Boolean

👉 Unlock advanced Web3 capabilities with one simple integration.

Using Custom RPCs

When default node providers don’t meet performance or privacy needs, configure custom RPC endpoints during connection via rpcMap.

Ensure each RPC URL corresponds to a chain listed in the chains array. This supports faster queries, private indexing, or integration with services like Alchemy, Infura, or self-hosted nodes.

Example:

rpcMap: {
  'eip155:1': 'https://mainnet.infura.io/v3/YOUR_PROJECT_ID',
  'eip155:137': 'https://polygon-rpc.com'
}

Set Default Network

When supporting multiple EVM chains, set a default network to streamline user interactions:

defaultChain: 'eip155:56' // Binance Smart Chain as default

If no chain is specified in a request, the SDK uses this default. Users can later switch networks using wallet_switchEthereumChain.

Disconnect Wallet

Terminate the active session securely:

await okxUniversalProvider.disconnect();

This removes all session data from both client and wallet sides. Always disconnect before attempting to connect a different wallet.

Event Listeners

Listen to real-time events such as account changes or network switches:

okxUniversalProvider.on('accountsChanged', (accounts) => {
  console.log('New accounts:', accounts);
});

okxUniversalProvider.on('chainChanged', (chainId) => {
  console.log('Switched to chain:', chainId);
});

Supported events include:

accountsChanged
chainChanged
disconnect

Error Handling and Codes

Proper error handling improves UX and debugging efficiency. The SDK throws standardized error codes:

OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR – Unexpected internal issue
ALREADY_CONNECTED_ERROR – Attempted duplicate connection
NOT_CONNECTED_ERROR – Operation requires active session
USER_REJECTS_ERROR – User denied request
METHOD_NOT_SUPPORTED – Requested method not available
CHAIN_NOT_SUPPORTED – Chain not supported by wallet
CONNECTION_ERROR – Failed to establish session

Handle rejections gracefully:

try {
  await okxUniversalProvider.connect(params);
} catch (error) {
  if (error.code === OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
    alert('Connection was rejected.');
  }
}

Frequently Asked Questions

Q: Which chains are supported?
A: All EVM-compatible chains including Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, and more. Use chain IDs prefixed with eip155:.

Q: Can I integrate this in a Telegram Mini App?
A: Yes. Set the redirect parameter to tg://resolve in sessionConfig for proper deep linking behavior within Telegram.

Q: What should I do if a custom chain isn’t recognized?
A: Include it in optionalNamespaces. If still unsupported, use wallet_addEthereumChain after connection to prompt users to add it manually.

Q: Is SVG icon supported during initialization?
A: No. Only PNG or ICO formats are accepted. Use a 180×180px PNG for best display quality.

Q: How do I switch networks programmatically?
A: Call request() with method wallet_switchEthereumChain and pass the desired chain ID.

Q: Can I support non-EVM blockchains?
A: Currently, only EVM-compatible chains are supported via the eip155 namespace. Support for other ecosystems may be added in future updates.

👉 Maximize your DApp’s potential—connect with confidence now.

Core Keywords

EVM-compatible chain, wallet integration SDK, connect DApp to wallet, Web3 provider, OKX Connect, decentralized application integration, blockchain API, Mini App wallet connection

This comprehensive guide ensures developers can efficiently integrate wallet connectivity into their applications while adhering to best practices in security, usability, and scalability.