Web3 Wallet Integration Guide for Bitcoin-Compatible Chains

Integrating a Web3 wallet into your decentralized application (DApp) is essential for enabling seamless user interactions on blockchain networks—especially those compatible with Bitcoin. This comprehensive guide walks you through the process of connecting apps or mini wallets using OKX Connect, focusing on Bitcoin-compatible chains and DEX API integration. Whether you're building a Telegram Mini App or a standalone DApp, this documentation ensures smooth onboarding and transaction execution.

👉 Discover how to effortlessly connect your DApp to a Web3 wallet today.

Installation and Initialization

Before integrating OKX Connect into your DApp, ensure that the OKX App is updated to version 6.92.0 or higher. This version supports all necessary features for secure and efficient Web3 connectivity.

You can install OKX Connect via npm:

npm install @okxweb3/connect

After installation, initialize the connection by creating a UI-integrated object. This object will manage wallet connections, transaction prompts, and user interactions.

Configuration Parameters

• dappMetaData (object)

  • name (string): Your DApp’s display name (not used as a unique identifier).
  • icon (string): URL to your app icon in PNG or ICO format (SVG not supported). Ideally 180x180px.

• actionsConfiguration (object)

  • modals: Controls visibility of modal dialogs during transactions — options include 'before', 'success', 'error', or 'all'. Default: 'before'.
  • returnStrategy: Deep link strategy after user signs or rejects a request. For apps, use custom schemes like myapp://.
  • tmaReturnUrl: Specifically for Telegram Mini Apps; set to 'back' (default) to return to DApp post-signature, 'none' to remain in wallet.

• uiPreferences

  • theme: Accepts THEME.DARK, THEME.LIGHT, or "SYSTEM" for automatic theme detection.
• language: Supports multiple locales including "en_US", "zh_CN", "es_ES", "fr_FR", and more. Defaults to "en_US".

Returns

• OKXUniversalConnectUI: The main interface object used for all subsequent operations.

Connecting a Wallet

To interact with blockchain functionalities, first connect the user's wallet to retrieve their address—essential for identification and signing transactions.

Request Parameters

• connectParams

  • namespaces: Define required blockchain namespaces:

    • EVM-based chains use "eip155"
    • Bitcoin-compatible chains use "btc"
    • If any requested chain isn’t supported, the wallet rejects the connection.
  • chains: Array of chain IDs (e.g., ["btc:mainnet"]).
  • defaultChain (optional): Sets the default active chain.
  • optionalNamespaces: Similar to namespaces, but non-critical—if unsupported, connection proceeds.
  • sessionConfig.redirect: Redirect URL after successful connection (useful for Telegram Mini Apps: "tg://resolve").

Returns (Promise)

• topic: Unique session identifier.
• namespaces: Active namespace details.
• chains: Connected chain list.
• accounts: User wallet addresses.
• methods: Supported methods per namespace.
• defaultChain: Current default chain.
• dappInfo: Registered DApp metadata (name, icon, redirect).

👉 See how easy it is to authenticate users with one-click wallet linking.

Connect and Sign in One Step

This method combines wallet connection with immediate data signing, streamlining authentication flows.

Additional Parameter

• signRequest

  • method: Only "btc_signMessage" is currently supported for Bitcoin chains.
  • chainId: Must be included in declared namespaces.
  • params: Varies based on method—typically includes message to sign.

The signed result is returned via the connect_signResponse event.

Check Wallet Connection Status

Verify whether a wallet is currently connected before proceeding with sensitive actions.

Returns

• boolean: true if connected, false otherwise.

Useful for UI state management and conditional rendering.

Prepare Bitcoin Transactions

To execute Bitcoin transactions, create an instance of OKXBtcProvider, passing the initialized okxUniversalConnectUI object to its constructor.

This provider enables advanced BTC operations such as PSBT handling and broadcast control.

Retrieve Wallet Account Information

Fetch public account details from the connected wallet.

Parameters

• chainId: Specify chain, e.g., "btc:mainnet" or "fractal:mainnet".

Returns

• address: Public wallet address.
• publicKey: Associated public key for verification.

Ideal for displaying user identity or preparing off-chain verifications.

Message Signing

Allow users to sign arbitrary messages securely.

Parameters

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

Returns

• Signed message as a hexadecimal string (Promise).

Commonly used for login authentication or proving ownership.

Send Bitcoin

Initiate a standard Bitcoin transfer.

Parameters

• chainId: Chain identifier.
• toAddress: Recipient’s address.
• satoshis: Amount in satoshis.
• options.feeRate (optional): Custom fee rate in sat/vB.

Returns

• Transaction hash (txid) upon success.

Perfect for peer-to-peer payments or reward distributions.

Sign PSBT (Partially Signed Bitcoin Transaction)

Handle complex multi-input transactions with full user control.

Parameters

• chain: Target chain ID.
• psbtHex: Raw PSBT in hex format.
• options.autoFinalized: Finalize PSBT after signing? Default: true.

• toSignInputs[]:

  • index: Input index to sign.
  • address, publicKey: Required for validation.
  • sighashTypes, disableTweakSigner: Advanced Taproot controls.

Returns

• Signed PSBT in hex format.

Supports multisig, HD wallets, and advanced scripting.

Sign Multiple PSBTs

Batch-sign several PSBTs at once for efficiency.

Same parameters as signPsbt, but accepts arrays:

• psbtHex[]
• options[]

Returns

• Array of signed PSBT hex strings.

Efficient for batch processing in DeFi or exchange platforms.

Sign and Broadcast Transaction (signAndPushPsbt)

Requires OKX App version 6.93.0 or higher

Finalize, sign, and directly broadcast a PSBT to the network.

Returns

• Object containing:

  • txhash: Broadcasted transaction ID.
  • signature: Final signed PSBT hex.

Eliminates need for external broadcasting services—ideal for custodial-free DEXs or trading bots.

👉 Start building powerful Bitcoin-powered DApps with full transaction control.

Disconnect Wallet

Terminate the current session cleanly.

Call this before attempting to reconnect or switch accounts. Clears session data and enhances security.

Event Handling

Listen to real-time events such as:

• Connection established
• Transaction confirmed
• User rejection
• Session expiry

Implement event listeners to improve UX responsiveness and error handling.

Error Codes

Handle common exceptions gracefully:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR: Unexpected internal issue.
• ALREADY_CONNECTED_ERROR: Prevent duplicate connections.
• NOT_CONNECTED_ERROR: Ensure connection before action.
• USER_REJECTS_ERROR: User denied request—prompt again if needed.
• METHOD_NOT_SUPPORTED: Method not available on selected chain.
• CHAIN_NOT_SUPPORTED: Chain not recognized by wallet.
• WALLET_NOT_SUPPORTED: Incompatible wallet environment.
• CONNECTION_ERROR: Network or handshake failure.

Log these errors for debugging and provide clear feedback to users.

Frequently Asked Questions (FAQ)

Q: Which chains are supported for Bitcoin-compatible integrations?
A: Mainnet and testnet variants of Bitcoin (btc:mainnet, btc:testnet) and Fractal Bitcoin (fractal:mainnet) are currently supported.

Q: Can I integrate this within a Telegram Mini App?
A: Yes. Use the tmaReturnUrl: 'back' setting to return to your Mini App after signing. Supported in OKX App v6.92.0+.

Q: Is SVG icon support available for DApp branding?
A: No. Only PNG and ICO formats are accepted. Use a 180x180px PNG for best display quality.

Q: What is the difference between required and optional namespaces?
A: Required namespaces must be fully supported by the wallet; otherwise, connection fails. Optional ones allow partial support without rejection.

Q: How do I handle Taproot address signing?
A: By default, tweakSigner is used. To sign with raw private keys, set disableTweakSigner: true in options.

Q: Can I customize transaction fees?
A: Yes. Pass the feeRate (in sat/vB) via the options object when sending Bitcoin or preparing PSBTs.

Core Keywords: Web3 wallet integration, Bitcoin-compatible chain, connect wallet API, DEX API documentation, PSBT signing, Telegram Mini App wallet, OKX Connect, BTC transaction broadcast