「Bitcoin 生态」与「多链互通」已是 2025 年开发者的高频关键词。无论你是想在 Telegram 里做 Mini App，还是在浏览器端做一站式 DEX，本文将用简明代码与可视化步骤，教你「如何 30 分钟完成 OKX Connect 接入」。核心关键词：OKX Connect、Bitcoin 兼容链、Mini Wallet、API DEX、BTC 签名、PSBT、钱包连接。

一、SDK 还是 UI？场景一张图就懂

不同于纯后端 SDK，OKX Connect 额外提供了开箱即用的 UI 连接器，依据使用场景自动跳转：

在 桌面浏览器：弹出浏览器扩展钱包
在 Telegram Mini App：自动唤起 Mini Wallet 并停留在聊天环境
在 移动端 WebView：一键跳转 OKX App Wallet 并在完成后自动返回

👉 立即体验官方 Demo，一键连钱包无需写后端

二、三分钟完成安装

npm i @okxconnect/ui

最低版本要求：OKX App ≥ 6.92.0（签名 BTC 主网）
≥ 6.93.0 支持「Sign & Push PSBT」一步到位

import { OKXUniversalConnectUI, THEME } from '@okxconnect/ui'

const okxUI = await OKXUniversalConnectUI.init({
  dappMetaData: {
    name: '我的 Supper DEX',
    icon: 'https://your-cdn.com/icon180.png'
  },
  actionsConfiguration: {
    modals: 'all',
    // 深链返回策略
    returnStrategy: 'tg://resolve',
    tmaReturnUrl: 'back' // 自动回到 Telegram 聊天
  },
  uiPreferences: {
    theme: THEME.SYSTEM // 或 DARK / LIGHT
  },
  language: 'zh_CN' // 支持 18 种语言
})

三、连接钱包 & 监听事件

const session = await okxUI.connect({
  namespaces: {
    btc: {
      chains: ['btc:mainnet', 'fractal:mainnet'],
      methods: [
        'btc_getAccounts',
        'btc_signMessage',
        'btc_signPsbt',
        'btc_sendBitcoin'
      ]
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:56'],
      methods: ['personal_sign']
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve'
  }
})
// session.accounts = ['bc1p...', '0xAB...']

一次性同时支持 Bitcoin 主网 / Fractal 主网 / 以太坊 / BSC 等链，多链账户一次拿齐。

四、核心功能代码直抄

1. 获取账户信息

const provider = new OKXBtcProvider(session)
const acc = await provider.getAccounts({ chainId: 'btc:mainnet' })
console.log(acc.address) // bc1q...

2. 签名一条消息

const sig = await provider.signMessage({
  chain: 'btc:mainnet',
  signStr: 'Hello Bitcoin!',
  type: 'bip322-simple'
})

3. 发送原生 BTC

const txid = await provider.sendBitcoin({
  chainId: 'btc:mainnet',
  toAddress: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
  satoshis: 100000, // 0.001 BTC
  options: { feeRate: 12000 } // 自定义费率（sat/vB）
})

4. 一键签名 & 上链 PSBT

const { txhash, signature } = await provider.signAndPushPsbt({
  chain: 'btc:mainnet',
  psbtHex: '70736274ff0100...',
  options: {
    autoFinalized: true,
    toSignInputs: [
      {
        index: 0,
        address: 'bc1pabcd...',
        sighashTypes: [1]
      }
    ]
  }
})

五、断开连接 & 清理会话

await okxUI.disconnect()

建议在新的用户登录或链切换前先执行，避免残余会话导致的 ALREADY_CONNECTED_ERROR。

FAQ｜高频疑惑一答到底

Q1：我能同时连接 Mini Wallet 与 App Wallet 吗？
A：不能，当前会话与单钱包绑定。切换需要先 disconnect()。

Q2：PSBT 里能否分批签名多个输入？
A：可以，使用 signPsbts（数组形式）或 signAndPushPsbt（单tx 会自动遍历输入）。

Q3：用户已拒绝会怎样？
A：会触发 USER_REJECTS_ERROR，请在前端捕获并提示：“签名已取消，请重新发起”。

Q4：调试时报 CHAIN_NOT_SUPPORTED？
A：核对 chainId 拼写，双边支持列表务必对齐：btc:mainnet、fractal:mainnet 目前社区最稳，👉 查看实时链状态。

Q5：如何更换主题？
A：重新 init({ uiPreferences: {theme: THEME.DARK} }) 即可，旧主题立即生效，无需清除缓存。

六、错误码速查表

错误码	含义	解决要点
UNKNOWN_ERROR	通用异常	刷新重试
ALREADY_CONNECTED	已连接	先 `disconnect()`
NOT_CONNECTED	无会话	重新 `connect()`
USER_REJECTS	用户拒绝	友好提示重签
METHOD_NOT_SUPPORTED	方法不支持	检查链配置
CHAIN_NOT_SUPPORTED	链未支持	升级 OKX App ≥6.92.0
WALLET_NOT_SUPPORTED	钱包环境不符	换到支持版本
CONNECTION_ERROR	网络/节点问题	切换 RPC 节点

七、3 个超实用场景建议

Telegram Mini Bot 做「闪电红包」
使用 Mini Wallet，发送 0.0001 BTC ≈ 立即到账，无需跳出聊天窗口，红包利器。
浏览器端「跨链 NFT 市场」
一张 PSBT 同时打包 BTC、ETH 两笔付款，导航深度链接自动回调到指定作品页。
Mobile Web 和 App 共存
通过 浏览器 UA 检测，iOS/Android 分别跳转：App Store / Google Play 深度安装页，当日新增用户转化率可提升 26%。

下一分钟就能开始

把上面「安装 + 连接钱包」两段代码粘进你的入口组件，就能跑通 OKX Connect 全流程。仍旧空白？👉 直接抄完整示例仓库（含 React、Vue、Vanilla 三份样板），零配置运行。祝你早日在 Bitcoin 兼容链上发第一个 DApp！

OKX Connect 完整接入指南：打通 Bitcoin 兼容链的 DApp UI 与钱包