A Comprehensive Guide to Integrating OKX Wallet UI for DApps

Integrating a secure and user-friendly wallet connection is crucial for any decentralized application (DApp) aiming to interact with blockchain networks. The OKX Wallet provides a robust UI interface that simplifies this process, supporting both standard app wallets and Telegram Mini Wallets. This guide walks you through the essential steps for seamless integration.

Installation and Initialization

Before diving into the connection process, ensure your OKX App is updated to version 6.92.0 or later. To integrate OKX Connect into your DApp, use npm for installation.

To begin, create an object that facilitates UI interactions for wallet connections and transactions. This object requires specific parameters:

• dappMetaData: An object containing:

  • name: Your application’s name (not used as a unique identifier).
  • icon: A URL pointing to a PNG or ICO icon (180x180px recommended; SVG is unsupported).

• actionsConfiguration: Configures modal displays and return strategies:

  • modals: Sets alert modes during transactions (‘before’, ‘success’, ‘error’, or ‘all’).
  • returnStrategy: Defines post-signing deep link behavior for app wallets (e.g., ‘none’ or a custom URI like tg://resolve for Telegram).
  • tmaReturnUrl: Specific to Telegram Mini Wallet, similar to returnStrategy.

• uiPreferences: Customizes UI appearance:

  • theme: Options include THEME.DARK, THEME.LIGHT, or SYSTEM.
  • language: Supports multiple locales (default: en_US).

This setup returns an OKXUniversalConnectUI object, enabling subsequent operations.

Connecting to OKX Wallet

The connection process retrieves the wallet address and parameters necessary for transaction signing. Use connectParams to specify:

• namespaces: Required namespaces like eip155 for EVM or btc for Bitcoin. If unsupported, the wallet rejects the connection.

  • chains: Array of chain IDs.
  • defaultChain: Optional default chain.
• optionalNamespaces: Optional namespaces for flexible connections.
• sessionConfig: Includes redirect for post-connection deep links (e.g., tg://resolve for Telegram).

The method returns a promise containing session details like topic, accounts, methods, and dappInfo.

Connect to Wallet and Sign

This method combines connection and signing in one step, with results via the connect_signResponse event. Parameters mirror the connection process, with added signRequest for method execution:

• method: e.g., btc_signMessage for Bitcoin.
• chainId: Must match a namespace chain.
• params: Method-specific parameters.

The return value includes session data and DApp information.

Determine If the Wallet Is Connected

Check connectivity status with a simple method returning a boolean value. This helps avoid redundant connection attempts.

Prepare to Trade

Initialize an OKXBtcProvider object using the okxUniversalConnectUI instance. This prepares your DApp for Bitcoin-related operations.

Get Wallet Account Information

Retrieve account details by specifying a chainId (e.g., btc:mainnet). Returns an object with:

• address: The wallet address.
• publicKey: The associated public key.

Sign Message

Request a message signature with parameters:

• chain: The target chain.
• signStr: The message string.
• type: Optional signature type (‘ecdsa’ or ‘bip322-simple’).

Returns a promise resolving to the signature string.

Send Bitcoin

Initiate Bitcoin transfers with:

• chainId: e.g., btc:mainnet.
• toAddress: Recipient address.
• satoshis: Amount in satoshis.
• options: Optional feeRate.

Returns the transaction hash.

Sign PSBT

Sign a Partially Signed Bitcoin Transaction (PSBT) using:

• chain: Target chain.
• psbtHex: PSBT hex string.
• options: Includes autoFinalized, toSignInputs (with index, address, public key), and sighashTypes.

Returns the signed PSBT hex string.

Sign Multiple PSBTs

Similar to single PSBT signing but accepts an array of psbtHexs and options. Returns an array of signed PSBT hex strings.

Sign and Push PSBT

Requires App ≥6.93.0. Signs and broadcasts a PSBT in one step. Parameters match single PSBT signing. Returns an object with:

• txhash: Transaction hash.
• signature: Signed PSBT hex string.

Disconnect Wallet

Terminate the current session and disconnect the wallet. Essential for switching wallets or resetting connections.

Event Handling

Events like connect_signResponse manage asynchronous operations. Ensure your DApp listens for relevant events to handle responses appropriately.

Error Codes

Common exceptions during operations include:

Handle these errors gracefully to improve user experience.

Frequently Asked Questions

What is the OKX Wallet UI?
The OKX Wallet UI is a pre-built interface that allows DApps to connect with OKX wallets seamlessly. It supports both mobile apps and Telegram Mini Wallets, simplifying user authentication and transaction signing.

How do I handle unsupported chains or methods?
If a user’s wallet doesn’t support a requested chain or method, the connection will be rejected. Use optionalNamespaces for flexible fallbacks and always check error codes like CHAIN_NOT_SUPPORTED to guide users.

Can I customize the UI’s appearance?
Yes, use uiPreferences to set themes (DARK/LIGHT/SYSTEM) and language (e.g., en_US or ar_AE). However, icon and name fields are fixed for consistency.

What’s the difference between ‘returnStrategy’ and ‘tmaReturnUrl’?
returnStrategy applies to standard app wallets, defining post-action navigation. tmaReturnUrl is specific to Telegram Mini Wallets, offering similar control within Telegram’s environment.

How do I troubleshoot connection errors?
Start by verifying the OKX App version (≥6.92.0). Ensure parameters like chainId and namespaces are correctly specified. 👉 Explore advanced troubleshooting strategies for detailed steps.

Is there a way to test integration without live transactions?
Use testnets for development. Most methods support testnet chains (e.g., btc:testnet), allowing safe experimentation without real funds.

Integrating OKX Wallet UI streamlines user onboarding and transaction processes. By following this guide, developers can ensure secure, efficient interactions with Bitcoin and EVM-based blockchains.