OKX Connect：五分钟让 DApp 无缝接入 Bitcoin 及 EVM 钱包

想让现有应用优雅地支持 Bitcoin 兼容链、并在 Telegram 与移动 App 环境中一键唤起钱包吗？OKX Connect 把它浓缩成三段代码：安装、连钱包、发交易。本文用 1000+ 字深度拆解每个参数，再给出真实可运行的片段，助你在 Web3 阵地快人一步。

👉 直达最新版 OKX Connect 接入现场，跟着示例跑通主网发送比特币

核心关键词：OKX Connect、Bitcoin 钱包、Web3 钱包接入、DEX API、Mini App 钱包、PSBT、BTC 签名、Telegram DApp、EOA 地址、去中心化应用开发

一、环境准备与最低版本

OKX App ≥ 6.92.0
Node/npm ≥ 16
终端支持 deep link（iOS/Android）或 Telegram Mini App

二、npm 安装 OKX Connect

npm install @okconnect/web3-sdk

三、初始化 UI 实例

OKXUniversalConnectUI 是入口对象，后续什么都靠它。

import { OKXUniversalConnectUI, THEME } from '@okconnect/web3-sdk';

const ui = await OKXUniversalConnectUI.init({
  dappMetaData: {
    name: 'My BTC DEX',
    icon: 'https://my-dex.com/icon180.png' // PNG 180×180 效果最佳
  },
  actionsConfiguration: {
    modals: 'all',                       // 在交易前、成功、失败阶段均弹窗
    returnStrategy: 'none',              // App 环境退回策略
    tmaReturnUrl: 'back'                 // Telegram Mini Wallet 默认返回上级
  },
  uiPreferences: { theme: THEME.DARK },
  language: 'zh_CN'
});

四、连接钱包并聚合规整

4.1 简单连接 (EVM + BTC)

const session = await ui.connectWallet({
  namespaces: {
    btc: { chains: ['btc:mainnet'], defaultChain: 'btc:mainnet' },
    eip155: { chains: ['eip155:1'], defaultChain: 'eip155:1' }
  },
  sessionConfig: { redirect: 'tg://resolve' }
});
console.log('已连接地址:', session.accounts);

4.2 连接同时签名

await ui.connectAndSign({
  connectParams: { ... },                       // 同上
  signRequest: [{
    method: 'btc_signMessage',
    chainId: 'btc:mainnet',
    params: ['Hello Web3']
  }]
});
ui.on('connect_signResponse', e => {
  console.log('签名结果', e.signature);
});

五、判断连接状态

ui.isWalletConnected();   // => true / false

六、Bitcoin 交易示例

6.1 获取账户信息

const btcProvider = new OKXBtcProvider(ui);
const acc = await btcProvider.getAccounts('btc:mainnet');

6.2 普通转账

const txid = await btcProvider.sendBitcoin({
  chainId: 'btc:mainnet',
  toAddress: '3F...',
  satoshis: 100_000,
  options: { feeRate: 5 }
});

6.3 签名单条 PSBT

const signedPsbt = await btcProvider.signPsbt('0200...', {
  autoFinalized: false,
  toSignInputs: [{ index: 0, address: acc.address }]
});

6.4 批量签名并广播

const { txhash, signature } = await btcProvider.signAndPushPsbt(
  '70736274ff...', { ... }
);

👉 通过完整的交互式 DEMO，体验 30 秒完成 BTC 和一键返回 Telegram

七、断开连接

await ui.disconnectWallet();

八、事件监听与常见错误

错误码	典型场景
NOT_CONNECTED_ERROR	未调用 connectWallet 直接发送交易
CHAIN_NOT_SUPPORTED	请求了 fractal:mainnet，而钱包未同步支持
USER_REJECTS_ERROR	用户点击“拒绝”导致签名中断

监听全局：

ui.on('session_delete', () => console.log('用户主动断开'));

九、开发者常见问答 FAQ

Q1：Telegram Mini Wallet 返回后页面被刷新，如何避免？
A：设置 tmaReturnUrl: 'back'，并且在 Telegram 打开 Web App 时使用 attachToWindow 模式，可保持数据不丢。

Q2：SVG 图标为什么被强制不通过？
A：目前仅支持主流位图格式（PNG/ICO），SVG 在多端兼容解析差异大，后续会考虑支持。

Q3：能否一次签名多笔 PSBT？
A：可调用 signPsbts 批量数组签名，但交易所广播仍需逐笔请求节点，目前无 Rollup 型 API。

Q4：监听不到 connect_signResponse？
A：确保调用 connectAndSign() 之前先注册监听器；否则事件会在注册前触发完毕。

Q5：连接成功后跳转白屏怎么办？
A：检查 sessionConfig.redirect 是否与当前 deep link 协议一致；iOS 没有上架的 scheme 将直接跳转到 Safari。

Q6：自定义费率过高会被拒绝吗？
A：费率参数由节点验证，最大为动态上限的 1000 sat/vbyte；超过时节点会返回 “min relay fee not met”。

全文到此结束。把示例代码直接搬进项目，你就拥有了目前正热门的 Bitcoin 钱包连接 与 DEX API 调用 方案，快去部署体验吧！