接入 Bitcoin 兼容链的 Web3 钱包：SDK 全流程指南

无论是开发 比特币链应用，还是想让自己的 Mini App 或 DApp 实现一键 连接 Web3 钱包、顺畅调用 DEX API，这篇指南都能帮你从零走完集成路径。全文以 简洁代码示例 + 关键坑位提醒 方式，帮你十分钟完成上线准备。

1. 快速安装与环境初始化

先把 SDK 6.92.0 及以上版本 拉下来，一行命令即可：

npm install @okxconnect/web3-sdk

接着创建全局的根对象 OKXUniversalProvider，你需要告诉钱包「我是谁」：

import { OKXUniversalProvider } from "@okxconnect/web3-sdk";

const okxUniversalProvider = await OKXUniversalProvider.init({
  dappMetaData: {
    name: "闪电红包",          // 应用名称，钱包会展示
    icon: "https://mycdn.com/icon.png" // png 图标，180 x 180 透明像素为佳
  }
});

🔍 核心关键词：SDK、Bitcoin 兼容链、Web3 钱包、初始化、DApp

2. 连接钱包：一步到位获取用户地址

调用 connect 方法发起会话请求，所有参数按需裁剪即可。

const session = await okxUniversalProvider.connect({
  namespaces: {
    eip155: {                      // EVM 兼容链
      chains: ["eip155:1"],
      defaultChain: "eip155:1"
    },
    btc: {                         // Bitcoin 主网
      chains: ["btc:mainnet"],
      defaultChain: "btc:mainnet"
    }
  },
  sessionConfig: {
    redirect: "https://myapp.com/auth/callback" // 成功回调
  }
});

console.log(session.accounts);     // 钱包地址列表

没有看到弹窗？记得检查浏览器或 Mini App 的环境权限 🔐。

3. 状态检测：判断用户是否已经授权

const connected = okxUniversalProvider.isWalletConnected();

返回值是布尔量，页面可根据该结果动态展示「立即连接」或「更换钱包」按钮。

4. 账户信息 & 签名

拿到地址还不够，很多场景需要公钥或 离线签名：

const btcProvider = new OKXBtcProvider(okxUniversalProvider);

const { address, publicKey } = await btcProvider.getAccountInfo("btc:mainnet");

// 请求签名
const sig = await btcProvider.signMessage({
  chain: "btc:mainnet",
  signStr: "Welcome to闪电红包!",
  type: "ecdsa"  // 也可选 bip322-simple
});

常见问题解答（FAQ）

Q1：只能连接 Bitcoin 吗？
✅ 支持多条 Bitcoin 兼容链（Fractal、BEVM、B2 等），只需替换 chains 字段 id。
Q2：如何区分签名类型？
普通消息用 ecdsa；涉及 Taproot 资产验证时用 bip322-simple 兼容性更高。

5. 发送 Bitcoin

发起链上转账，空口无凭，代码为证：

const txId = await btcProvider.sendBitcoin({
  chainId: "btc:mainnet",
  toAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  satoshis: 1_000_000,     // 1 BTC = 1亿聪
  options: { feeRate: 10 } // 设置费率，防止网络拥堵
});

👉 查看实时费率并模拟发送，避免高昂矿工费！

6. PSBT 签名进阶玩法

当你想做 Ordinals、Runes 甚至跨链桥，99% 的情况绕不开 PSBT。

6.1 单 PSBT 签名

const signed = await btcProvider.signPsbt({
  chain: "btc:mainnet",
  psbtHex: "70736274ff0100...",
  options: {
    autoFinalized: true,
    toSignInputs: [{ index: 0, address }]
  }
});

6.2 批量签名

const batchSigned = await btcProvider.signPsbts({
  chainId: "btc:mainnet",
  psbtHex: [
    "70736274ff0100...",
    "70736274ff0100..."
  ]
});

6.3 签名并广播一步到位

若 App 版本 ≥ 6.93.0，可直接执行：

const { txhash } = await btcProvider.signAndPushPsbt({
  chain: "btc:mainnet",
  psbtHex: "70736274ff0100...",
  // options 同上
});

FAQ 补充

Q3：Psbt 报 “输入签名不匹配” 怎么办？
检查 toSignInputs 里的 address 与转账输入是否一致；Taproot 地址需手动关闭 tweakSigner。
Q4：如何在 Telegram Mini App 里回退？
将 sessionConfig.redirect 设为 "tg://resolve"，钱包将自动重定向回 Mini App。

7. 优雅断开连接

await okxUniversalProvider.disconnectWallet();

断开后，所有会话缓存清除；建议做链切换前必定执行一次，避免白屏。

8. 错误码速查表

OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR – 用户点 “拒绝”
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED – 链不被当前钱包支持
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED – 钱包客户端版本过低

出现以上异常，只需捕获并弹出人性化提示，页内引导检查环境即可，无敏感内容请安心上报。

9. 场景小结 & 下一步

到今天，你已经掌握从 Bitcoin 网络接入、钱包连接、账户信息、签名转账，到 PSBT 高级用法 的完整链路。接着只需：

根据品牌色按需重写 UI；
把审批逻辑接入自家后端风控；
👉 在线测试主网到账速度，一文读懂费率模型并上线。

愿你早日把 Web3 体验 带给每一位用户！