Bitcoin-Compatible Chain Integration with OKX Connect UI

Integrating a Bitcoin-compatible chain into your decentralized application (DApp) has never been easier. With OKX Connect, developers can seamlessly link their apps to secure wallet solutions—whether through a full mobile App Wallet or the lightweight OKX Mini Wallet within Telegram. This guide walks you through the complete integration process using the OKX Universal Connect UI, offering step-by-step instructions for connection, transaction signing, account management, and more.

Whether you're building on Bitcoin, Fractal, or other BTC-ecosystem chains, this documentation ensures smooth interoperability while maintaining user experience and security.

Installation and Initialization

To begin integrating OKX Connect into your DApp, ensure that users have the OKX App version 6.92.0 or higher installed. This is required to access the latest features of the Universal Connect UI.

You can install the SDK via npm:

npm install @okxweb3/connect

Before initiating any wallet interaction, create an instance of OKXUniversalConnectUI. This object provides the necessary interface for connecting wallets, sending transactions, and managing user sessions.

Request 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). Recommended size: 180x180px.

• actionsConfiguration – Object

  • modals: 'before' | 'success' | 'error' | 'all' — Controls when alerts appear during transactions. Default: 'before'.
  • returnStrategy: 'none' | {custom-scheme}://{host}' — Defines deep link behavior after signing (e.g., tg://resolve for Telegram).
  • tmaReturnUrl: 'back' | 'none' | {custom-scheme}' — Return policy for Telegram Mini App; default is 'back'.

• uiPreferences – Object

  • theme: THEME.DARK, THEME.LIGHT, or 'SYSTEM'
  • language: Supported locales include 'en_US', 'zh_CN', 'es_ES', 'fr_FR', and more. Defaults to 'en_US'.

Return Value

• OKXUniversalConnectUI — The initialized UI interface object used for all subsequent operations.

👉 Discover how to set up seamless wallet connections in minutes

Connecting to the OKX Wallet

Establishing a wallet connection allows your DApp to retrieve the user's address and obtain permission to sign transactions securely.

Request Parameters

• connectParams – ConnectParams

  • namespaces: { [namespace: string]: ConnectNamespace }

    • Use 'eip155' for EVM chains or 'btc' for Bitcoin-compatible chains.
    • If any requested chain isn't supported, the wallet will reject the connection.
  • chains: string[] — List of chain IDs (e.g., ["btc:mainnet"]).
  • defaultChain?: string — Preferred chain for initial session.
  • optionalNamespaces: Optional fallback namespaces; connection proceeds even if these aren't supported.

  • sessionConfig:

    • redirect: string — Deep link to redirect post-connection (use tg://resolve for Telegram Mini Apps).

Return Value

A Promise resolving to:

• topic: Session identifier
• namespaces: Connected namespace details
• chains: Active chain list
• accounts: Wallet addresses involved
• methods: Supported signing methods
• defaultChain: Current default chain
• dappInfo: Name and icon of your DApp

Connect and Sign in One Step

This method combines wallet connection with immediate data signing—ideal for authentication flows. The result triggers the 'connect_signResponse' event.

Additional Parameters

• signRequest – RequestParams[] (max one method at a time)

  • method: e.g., 'btc_signMessage'
  • chainId: Must match one from the requested namespaces
  • params: Method-specific parameters (e.g., message to sign)

Returns the same session data as standard connection, plus signed output via event callback.

Check Wallet Connection Status

Determine whether a wallet is currently connected.

Return Value

• boolean: true if connected, otherwise false

Use this before attempting transactions or fetching account data.

Prepare for Trading Operations

After establishing a session, instantiate an OKXBtcProvider object using the initialized okxUniversalConnectUI. This provider enables Bitcoin-specific actions like sending BTC or signing PSBTs.

const btcProvider = new OKXBtcProvider(okxUniversalConnectUI);

Retrieve Wallet Account Information

Fetch public wallet details such as address and public key.

Request Parameters

• chainId: e.g., 'btc:mainnet', 'fractal:mainnet'

Return Value

• Object

  • address: User’s wallet address
  • publicKey: Associated public key

Ideal for displaying user identity or preparing transaction inputs.

👉 Learn how to integrate Bitcoin wallet functionality effortlessly

Sign a Message

Securely sign arbitrary messages—commonly used for login authentication.

Parameters

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

Return Value

• Promise: Signature in hex format

Supports both legacy and Taproot-based addresses.

Send Bitcoin Transactions

Enable users to transfer BTC directly from your DApp.

Parameters

• chainId: Chain identifier (required)
• toAddress: Recipient address
• satoshis: Amount in satoshis

• options?:

  • feeRate: Custom fee rate in sat/vB

Return Value

• Promise: Transaction hash (txid)

Perfect for peer-to-peer transfers, payments, or withdrawals.

Sign PSBT (Partially Signed Bitcoin Transaction)

Sign pre-built transactions without broadcasting—giving full control over transaction flow.

Parameters

• chain: e.g., 'btc:mainnet'
• psbtHex: Hex-encoded PSBT

• options:

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

  • toSignInputs[]: Specify which inputs to sign with:

    • index, address, publicKey, optional sighashTypes, and disableTweakSigner for Taproot

Return Value

• Promise: Signed PSBT in hex

Useful for multi-sig setups or advanced DeFi interactions.

Sign Multiple PSBTs

Batch-sign several PSBTs in one request.

Parameters

• chainId: Target chain
• psbtHexs: Array of PSBT hex strings
• options[]: Per-PSBT signing options (same structure as above)

Return Value

• Promise<string[]>: Array of signed PSBTs

Efficient for batch operations like NFT mints or portfolio rebalancing.

Sign and Broadcast PSBT

Signs the transaction and automatically pushes it to the network.

Requires OKX App version 6.93.0 or later

Parameters

Same as signPsbt, with automatic broadcast upon completion.

Return Value

• Promise