OKX DEX 集成指南：用 UI 接口一键接入 Bitcoin 兼容链钱包

本文用中文重新梳理官方文档，帮助开发者用 OKX Connect 的 UI 接口在 30 分钟内完成 Bitcoin 兼容链 钱包连接、交易签名与发送，并兼容 Telegram Mini 钱包 与移动端 App 钱包 双重场景。

关键词：OKX Connect、Bitcoin 兼容链、DEX API、Mini Wallet、钱包集成、UI 接口、BTC 签名、PSBT 签名、Telegram Mini App

为什么用 UI 而不是 SDK 接入

零学习成本：所有交互由官方弹窗完成，开发者不必维护复杂界面。
跨端一致：同一行代码同时支持 Telegram Mini Wallet 和 移动端 App 钱包。
主题自定义：内置暗黑、亮色与跟随系统三种模式，和 DApp 品牌色保持一致。

准备工作：更新与环境

将 OKX App 升级到 6.92.0 及以上 版本。
安装依赖
```
npm install @okxconnect/ui
```

👉 节省调试时间，查看最新版本号与兼容性测试工具

创建 UI 连接对象

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

const okxUI = new OKXUniversalConnectUI({
  dappMetaData: {
    name: '我的 BTC DApp',
    icon: 'https://yourcdn.com/icon-180.png' // 180×180 PNG
  },
  actionsConfiguration: {
    modals: ['before', 'success'],          // 只给关键步骤弹窗
    returnStrategy: 'tg://resolve',         // Telegram 内拉起
    tmaReturnUrl: 'back'                    // Mini Wallet 签名后返回
  },
  uiPreferences: {
    theme: THEME.SYSTEM                     // 自动跟随系统
  },
  language: 'zh_CN'
});

连接钱包并拿到地址

调用 okxUI.connect() 即可弹出钱包选择页：

const session = await okxUI.connect({
  namespaces: {
    btc: {
      chains: ['btc:mainnet'],
      defaultChain: 'btc:mainnet',
      methods: ['btc_signMessage', 'btc_sendBitcoin', 'btc_signPsbt']
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve'  // 成功与否都会返回 Mini App
  }
});

console.log(session.accounts); // ['bc1p...xyz']

核心操作 API 速查

1. 获取钱包账户信息

const { address, publicKey } = await okxUI.getAccount({ chainId: 'btc:mainnet' });

2. BTC 转账

const txhash = await okxUI.sendBitcoin({
  chainId: 'btc:mainnet',
  toAddress: 'bc1q...receiver',
  satoshis: 100000,     // 0.001 BTC
  options: { feeRate: 12 }
});

3. 消息签名

const signature = await okxUI.signMessage({
  chain: 'btc:mainnet',
  signStr: 'hello world',
  type: 'bip322-simple'
});

4. 单 PSBT 签名与广播

const { txhash, signature } = await okxUI.signAndPushPsbt({
  chain: 'btc:mainnet',
  psbtHex: '70736274ff010...',
  options: { autoFinalized: true }
});

5. 批量 PSBT 签名

const signedHexArray = await okxUI.signMultiplePsbts({
  chainId: 'btc:mainnet',
  psbtHexs: [psbt1, psbt2, psbt3],
  options: [...] // 与单 PSBT 相同，可逐项定制
});

切换与断开钱包

每次想换钱包时，务必先断开：

await okxUI.disconnect();

完整事件监听

okxUI.on('connect_signResponse', res => {
  // 处理签名回调
});

okxUI.on('session_delete', () => {
  // 钱包断开后刷新本地状态
});

常见问题答疑

Q1：Telegram Mini 钱包里没有 OKX 图标？
A：确保用户 已更新到 6.92+ 且在 Telegram 内置浏览器内点击按钮，系统会自动拉起。

Q2：想同时支持 EVM 和 BTC？
A：在 namespaces 中同时填写 eip155 与 btc 两套配置即可；钱包会提示用户切换链。

Q3：PNG 图标被裁切怎么处理？
A：保持 180×180 像素，并四周留足 20px 安全边距，避免边缘被系统圆角裁剪。

Q4：签名被拒绝后如何优雅提醒？
A：监听事件 connect_signResponse.err.code === 'USER_REJECTS_ERROR'，在 UI 弹出“用户已取消”即可。

Q5：如何自定义交易手续费？
A：sendBitcoin 和 signPsbt 都支持手动传入 feeRate，单位为 sat/vB；不传时用钱包推荐的费率。

错误码一览

ALREADY_CONNECTED_ERROR：重复连接 → 直接调用 disconnect() 后重连
CHAIN_NOT_SUPPORTED：请求的链不在钱包支持列表 → 检查 chains 参数
METHOD_NOT_SUPPORTED：方法名称拼写错误 → 参考 BTC 标准方法名
UNKNOWN_ERROR：网络或参数异常 → 用 catch() 打印完整日志并加入待命重试
USER_REJECTS_ERROR：用户拒绝签名 → 友好弹窗提示

👉 遇到未知错误？发送日志并获取官方即时支持

小结

通过本文即可用最少代码完成 Bitcoin 兼容链 在 OKX 钱包与 Telegram Mini App 的无缝集成：

安装一行指令
初始化一行配置
连接一次钱包
签名、转账、批签一步到位

提前升级版本、用 180×180 PNG 图标，再搭配 UI 统一主题，你的 DApps 就已具备“小程序级”用户体验。现在就开始构建吧！