SDK | EVM-Compatible Chains | Connect App or Mini Wallet | Web3 Wallet Integration | DEX API Documentation

Integrating Web3 functionality into your decentralized application (DApp) has never been more seamless. With the right tools and clear documentation, developers can efficiently connect apps and mini wallets to EVM-compatible blockchains, enabling smooth interactions with decentralized exchanges (DEXs), smart contracts, and digital assets. This guide walks you through the complete integration process using a robust SDK designed for modern Web3 development.

Whether you're building a Telegram Mini App or a standalone DApp, this documentation covers initialization, wallet connection, transaction handling, RPC usage, event listening, and error management—all tailored for EVM-based ecosystems.

Installation and Initialization

Before integrating the SDK, ensure that users have OKX App version 6.88.0 or higher installed. This guarantees full support for the latest Web3 features and security updates.

To begin, install the OKXUniversalProvider via npm:

npm install okx-universal-provider

Once installed, initialize the provider with your DApp’s metadata. This step is essential for establishing trust and recognition during wallet connection requests.

OKXUniversalProvider.init({
  DAppMetaData: {
    name: "Your DApp Name",
    icon: "https://yourdapp.com/icon.png" // Must be PNG or ICO format (180x180px recommended)
  }
});

Parameters

• DAppMetaData – Object containing:

  • name (string): The display name of your application.
  • icon (string): Public URL to your app's icon. SVG is not supported; PNG or ICO formats are preferred.

Returns

• OKXUniversalProvider: An instance used for all subsequent wallet interactions.

👉 Get started with seamless Web3 integration today.

Connecting a Wallet

To interact with blockchain functionality, users must first connect their wallet. The connection process retrieves essential data such as account addresses and enables transaction signing.

Use the following method to initiate connection:

okxUniversalProvider.connect(connectParams);

Request Parameters

• connectParams – Configuration object:

  • namespaces: Required namespace information. For EVM chains, use "eip155".

    • chains: Array of chain IDs (e.g., ["eip155:1", "eip155:137"]).
    • defaultChain: Optional default chain ID.
    • rpcMap: Optional mapping of chain IDs to custom RPC URLs (must be EVM-compatible and included in chains).
  • optionalNamespaces: Additional namespaces that won't block connection if unsupported.

  • sessionConfig:

    • redirect: Post-connection redirect URL. For Telegram Mini Apps, use tg://resolve.

If a requested chain isn’t supported by the wallet, the connection will be rejected unless listed under optionalNamespaces.

Returns (Promise)

Upon successful connection, returns session details:

• topic: Unique session identifier.
• namespaces: Active namespace details.
• chains: Connected chain IDs.
• accounts: User wallet addresses.
• methods: Supported wallet methods.
• defaultChain: Current default chain.
• DAppInfo: Includes name, icon, and redirect info.

Check Wallet Connection Status

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

const isConnected = okxUniversalProvider.isConnected();

Returns

• boolean: true if connected; otherwise false.

This check helps prevent errors during user interactions and ensures proper UI state management.

Preparing Transactions and Signing Requests

Send requests to the wallet for actions like signing messages or executing transactions.

okxUniversalProvider.request(requestArguments);

Request Parameters

• requestArguments – Object with:

  • method: Name of the Ethereum JSON-RPC method.
  • params: Method-specific parameters.
  • redirect: Deep link for post-action navigation (e.g., tg://resolve).
  • chain: Target chain ID (optional; defaults to current default chain).

Supported Methods and Return Values

👉 Unlock advanced Web3 capabilities with one integration.

Using Custom RPC Endpoints

When standard methods don't meet your needs, configure custom RPC endpoints during the connection phase using the rpcMap parameter.

Example:

rpcMap: {
  "eip155:10000": "https://custom-rpc.example.com"
}

This allows direct access to node-level operations on EVM-compatible chains included in your chains array.

Setting Default Network

When supporting multiple chains, define a default network to streamline user experience. If no chain is specified in a request, the SDK uses the default.

Set it during connection:

defaultChain: "eip155:1"

This avoids confusion and reduces redundant chain-switching prompts.

Disconnecting Wallet

To end a session securely:

okxUniversalProvider.disconnect();

This removes the active session and clears sensitive data. Always disconnect before attempting to reconnect with a different wallet.

Event Handling

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

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

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

Supported events include:

• accountsChanged
• chainChanged
• disconnect

Event listeners enhance responsiveness and improve UX in dynamic environments like mini apps.

Error Codes

Common exceptions during integration:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR: Unexpected internal error.
• OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR: Attempted duplicate connection.
• OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR: Action requires prior connection.
• OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR: User denied request.
• OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED: Unsupported RPC method.
• OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED: Chain not available in wallet.
• OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED: Incompatible wallet detected.
• OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR: Failed to establish session.

Handle these gracefully with user-friendly feedback.

Frequently Asked Questions

Q: What are the core keywords for SEO optimization in this guide?
A: The primary keywords are Web3 wallet integration, EVM-compatible chains, DEX API documentation, connect app to wallet, SDK for DApps, Telegram Mini Wallet, blockchain transaction signing, and RPC configuration for EVM.

Q: Can I connect a Telegram Mini App using this SDK?
A: Yes. Use the redirect parameter with tg://resolve in both connect() and individual requests to enable deep linking within Telegram.

Q: Is SVG supported for DApp icons?
A: No. Only PNG and ICO formats are supported. Use a 180x180px PNG for best results.

Q: How do I add a custom blockchain?
A: Include it in optionalNamespaces with its chain ID and RPC URL. If not recognized, call wallet_addEthereumChain after connection.

Q: What happens if a user rejects a transaction?
A: The promise rejects with USER_REJECTS_ERROR. Always wrap requests in try-catch blocks for proper handling.

Q: Can I switch networks programmatically?
A: Yes. Use wallet_switchEthereumChain with the desired chain ID in the params.

👉 Maximize your DApp’s potential with powerful Web3 tools.