Bitcoin-Compatible Chain Integration with OKX Wallet UI

Integrating blockchain functionality into decentralized applications (DApps) has become essential for delivering seamless user experiences in the Web3 ecosystem. For developers building on Bitcoin-compatible chains, leveraging a robust and user-friendly wallet interface is crucial. The OKX Wallet UI offers a powerful solution that supports both mobile app integration and lightweight access via Telegram Mini Wallet—making it easier than ever to connect users to your DApp without friction.

Whether you're building a decentralized exchange (DEX), NFT marketplace, or blockchain-based gaming platform, this guide walks you through the full integration process using the OKX Universal Connect UI. We’ll cover initialization, wallet connection, transaction signing, and more—all while ensuring compatibility with Bitcoin and EVM-based networks.

Installation and Initialization

To begin integrating the OKX Wallet UI into your DApp, ensure that users have the OKX App version 6.92.0 or later installed. This guarantees access to the latest features and security updates required for smooth interoperability.

You can install the SDK via npm:

npm install @okxweb3/connect

Before connecting to a wallet, initialize the OKXUniversalConnectUI object to enable UI-driven interactions such as connection prompts, transaction confirmations, and error handling.

Request Parameters

• dappMetaData (object)

  • name (string): Your application's display name.
  • icon (string): URL of your app icon in PNG or ICO format (SVG not supported). Recommended size: 180x180px.

• actionsConfiguration (object)

  • modals: Controls alert behavior during transactions. Options: 'before', 'success', 'error', or 'all'. Default: 'before'.
  • returnStrategy: Deep link strategy after user signs/rejects (e.g., tg://resolve for Telegram).
  • tmaReturnUrl: Return policy for Telegram Mini App. Use 'back', 'none', or a custom deep link. Default: 'back'.

• uiPreferences

  • theme: Choose from THEME.DARK, THEME.LIGHT, or 'SYSTEM' for automatic theme detection.
• language: Supported locales include 'en_US', 'zh_CN', 'es_ES', 'fr_FR', 'de_DE', and others. Defaults to 'en_US'.

👉 Get started with seamless wallet integration today

Connecting to the OKX Wallet

Establishing a wallet connection allows your DApp to retrieve the user’s address and gain permission to request transaction signatures.

Request Parameters

• connectParams

  • namespaces: Define required chains (e.g., 'eip155' for EVM, 'btc' for Bitcoin). If any requested chain isn’t supported, the connection will be rejected.

    • chains: Array of chain IDs (e.g., ['btc:mainnet']).
    • defaultChain?: Optional default chain ID.
  • optionalNamespaces: Chains that enhance functionality but aren’t mandatory.

  • sessionConfig

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

Return Value

A promise resolving to:

• topic: Unique session identifier.
• namespaces: Active namespace details.
• chains: Connected chain list.
• accounts: User wallet addresses.
• methods: Supported signing methods.
• defaultChain: Current default chain.
• dappInfo: Your app’s metadata.

This structured response enables dynamic routing and feature toggling based on connected capabilities.

Connect and Sign in One Step

For streamlined authentication, combine wallet connection with an immediate signing request. This method triggers the 'connect_signResponse' event upon completion.

Request Parameters

Includes all fields from connectParams, plus:

• signRequest (array)

  • method: Signing method (e.g., 'btc_signMessage').
  • chainId: Target chain (must be in namespaces).
  • params: Method-specific parameters.

Useful for login flows where message signing verifies ownership instantly.

Check Wallet Connection Status

Verify whether a wallet is currently connected using a simple synchronous check.

Return Value

• boolean: Returns true if connected, false otherwise.

Ideal for UI elements like “Connect Wallet” buttons that change state dynamically.

Prepare for Trading or Transactions

After successful connection, create an OKXBtcProvider instance by passing the initialized okxUniversalConnectUI. This provider enables direct interaction with Bitcoin-compatible networks for sending transactions, signing PSBTs, and querying balances.

Retrieve Wallet Account Information

Fetch public account data such as address and public key.

Request Parameters

• chainId: Chain identifier (e.g., btc:mainnet, fractal:mainnet).

Return Value

• Object containing:

  • address: User’s wallet address.
  • publicKey: Corresponding public key for verification.

👉 Access real-time wallet data with minimal setup

Sign Messages Securely

Authenticate users by requesting a digital signature over a plain text message.

Request Parameters

• chain: Target blockchain (e.g., 'btc:mainnet').
• signStr: Message string to sign.
• type: Signature type—'ecdsa' (default) or 'bip322-simple'.

Return Value

• Promise resolving to signature string.

Commonly used for non-transactional authentication in DEXs or gated content platforms.

Send Bitcoin Transactions

Enable peer-to-peer transfers directly from your DApp interface.

Request Parameters

• chainId: Chain ID (e.g., btc:mainnet).
• toAddress: Recipient’s Bitcoin address.
• satoshis: Amount in satoshis.

• options (optional)

  • feeRate: Custom fee rate in sat/vB.

Return Value

• Promise resolving to transaction hash (txid).

Perfect for tipping systems, payouts, or on-chain settlements.

Sign PSBTs (Partially Signed Bitcoin Transactions)

For advanced use cases like multi-sig wallets or batch transactions, sign PSBTs with full control over inputs.

Request Parameters

• chain: Target chain (e.g., btc:mainnet).
• psbtHex: Hex-encoded PSBT.

• options

  • autoFinalized: Finalize PSBT after signing (default: true).

  • toSignInputs: Specify which inputs to sign, including:

    • index, address, publicKey, optional sighashTypes.
  • disableTweakSigner: Use original private key for Taproot signing.

Return Value

• Signed PSBT as hex string.

Sign Multiple PSBTs

Batch-sign multiple transactions efficiently.

Request Parameters

Same as single PSBT signing, but accepts an array of psbtHexs and optional per-PSBT options.

Return Value

• Array of signed PSBT hex strings.

Ideal for DeFi aggregators or high-volume trading interfaces.

Sign and Broadcast PSBT

Available in OKX App version 6.93.0+, this method signs and pushes the transaction to the network in one step.

Request Parameters

Same as signPsbt.

Return Value

• Object containing:

  • txhash: Broadcasted transaction ID.
  • signature: Signed PSBT hex.

Reduces latency and improves reliability in time-sensitive operations.

Disconnect Wallet

Terminate the current session cleanly:

await okxUniversalConnectUI.disconnect();

Always disconnect before attempting to switch accounts or reconnect.

Event Handling

Monitor key events like:

• 'connect'
• 'disconnect'
• 'signResponse'

These allow responsive UI updates and error recovery mechanisms.

Error Codes Reference

Handle exceptions gracefully using standardized error codes:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR
• ALREADY_CONNECTED_ERROR
• NOT_CONNECTED_ERROR
• USER_REJECTS_ERROR
• METHOD_NOT_SUPPORTED
• CHAIN_NOT_SUPPORTED
• CONNECTION_ERROR

Implementing proper error handling improves user trust and reduces support load.

👉 Solve common integration issues fast with expert tools

Frequently Asked Questions (FAQ)

Q: Can I integrate OKX Wallet UI into a Telegram Mini App?
A: Yes. By setting the redirect URL to tg://resolve, you can keep users within Telegram while launching the OKX Mini Wallet for seamless interaction.

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

Q: What Bitcoin networks are supported?
A: Mainnet (btc:mainnet) and testnet (btc:testnet) are supported. Fractal Bitcoin (fractal:mainnet) is also available.

Q: Can I customize the UI theme?
A: Yes. Choose between dark, light, or system-default themes via the uiPreferences.theme setting.

Q: How do I handle user rejection during signing?
A: Catch the USER_REJECTS_ERROR code and provide clear feedback in your UI to guide retry attempts.

Q: Does OKX support Taproot addresses?
A: Yes. Use the disableTweakSigner option when signing to control how Taproot signatures are generated.

By following this guide, developers can deliver secure, efficient, and user-friendly integrations between their DApps and Bitcoin-compatible blockchains using the OKX Wallet UI—enhancing accessibility across mobile and messaging platforms alike.