OKX Connect 集成全指南：EVM 链钱包一站式对接 SDK

快速上手：三分钟完成安装与初始化

要把你的 DApp 无缝接入 OKX 生态，第一步是让 OKX 钱包 SDK 真正跑起来。请先确认用户已将 OKX App 升级到 6.88.0 及以上版本。随后只需一条 npm 命令即可封装备用：

npm install @okxconnect/web3-sdk

完成安装后，在入口文件中创建 OKXUniversalProvider 实例。该实例将在后续 钱包连接、链上签名、交易广播 等场景中充当桥梁角色。

import { OKXUniversalProvider } from '@okxconnect/web3-sdk'

const provider = await OKXUniversalProvider.init({
  DAppMetaData: {
    name: 'My DeFi Game',       // 应用名称，不限格式但建议简短
    icon: 'https://mygame.com/icon180.png' // 180x180 PNG，勿用 SVG
  }
})

核心关键词：钱包集成、EVM 链、OKX SDK、交易签名、Web3 开发。

👉 跳过重复踩坑，直接参考生产级示例

建立连接：精准获取用户链上地址

connect 方法负责拉起钱包授权页面，回传用户默认链 ID 与账户地址。下面的配置足够覆盖主流 EVM 网络（含自定义链）：

const session = await provider.connect({
  namespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:56', 'eip155:137'], // ETH、BSC、Polygon
      defaultChain: 'eip155:56',
      rpcMap: {
        '56': 'https://bsc-dataseed.binance.org/'
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:42161', 'eip155:8453'] // Arbitrum、Base（可选项）
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve' // 在 Telegram Mini App 中有效
  }
})

console.log(session.namespaces.eip155.accounts)   // ['0x...', ...]
console.log(session.topic)                        // 会话会话 ID

通过 session.namespaces 可以读取当前已连接的链、默认链与支持的方法列表，方便后续权限校验。

常见问题与解答
Q1：必须要列出所有链吗？
A：不是。只写需要的链即可，其余链可置 optionalNamespaces，钱包端会提示添加。

Q2：用户拒绝授权会怎样？
A：会抛出 USER_REJECTS_ERROR 异常，记得用 try/catch 包裹，提升用户体验。

就绪检查：判断钱包连接状态

在发送交易之前，建议先利用布尔型返回值确认连接：

const isConnected = provider.connected
if (!isConnected) {
  // 如果已过期，可弹出重新授权弹窗
}

该属性侦听器实时同步，无需再发起额外 RPC 请求。

发送签名与交易：精简五步完成

一旦确认已连接，可用 request 方法执行 任意 EVM RPC 指令。常用场景示例：

1. 个人消息签名

const signature = await provider.request({
  method: 'personal_sign',
  params: ['0x48656c6c6f', '0xabcd...'], // 数据、地址
  chain: 'eip155:56'
})

2. EIP-712 结构化签名

const typedSig = await provider.request({
  method: 'eth_signTypedData_v4',
  params: ['0xabcd...', JSON.stringify(typedMessage)]
})

3. 交易广播

const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{ from, to, data, value, gasLimit, gasPrice }],
  chain: 'eip155:137' // 指定链
})

👉 想要一行代码更优雅？这里有高级脚本技巧

自定义 RPC：覆盖钱包未内置的链

假如你的项目调用了一条新 EVM 侧链，而钱包尚未公开支持，可在初始化连接时把 RPC 写在 rpcMap 里：

rpcMap: {
  'eip155:12345': 'https://rpc.my-chain.io'
}

若用户本地并未添加该网络，还可通过 wallet_addEthereumChain 方法动态写入：

await provider.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x23456',
    chainName: 'MyChain',
    nativeCurrency: { name: 'MYC', symbol: 'MYC', decimals: 18 },
    rpcUrls: ['https://rpc.my-chain.io'],
    blockExplorerUrls: ['https://scan.my-chain.io']
  }]
})

切换默认网络：游刃有余地跨链操作

多链 DApp 常见需求：把默认环境从 BSC 切换到 Polygon，只需一条指令即可：

await provider.request({
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: '0x89' }] // 137
})

所有未显式传 chain 的 request 都会默认指向 Polygon。

优雅登出：清理会话重新授权

如果用户想更换账号或完全断开，调用：

await provider.disconnect()

执行后 session 对象会被销毁，下一次任何操作都会回退到授权流程。

监听事件：实时捕获状态变更

在 React/Vue 场景下，可订阅 session_update、session_delete 事件实现响应式 UI：

provider.on('session_delete', () => {
  // 重设 UI 或回退登录页
})

错误对照表：排查指南

在捕获异常的同时，友好地提示用户刷新、升级或切换网络，能显著降低流失率。

FAQ：高频疑问一次性解决

Q3：如何检测某条链是否已添加？
A：先尝试 eth_chainId，若返回的 chainId 不符即可认为是未添加，可引导 wallet_addEthereumChain。

Q4：交易广播后如何查看状态？
A：SDK 不内置浏览器，建议使用对应区块浏览器的 watch API 或自建节点轮询。

Q5：Mini App/内嵌 H5 与独立网页有何区别？
A：主要在于 redirect 参数需改成 tg://resolve，其余 API 调用路径一致。

Q6：SDK 是否支持硬件钱包？
A：只要 OKX 钱包端已对接（Ledger、Keystone），你无需额外处理，直接用 eth_signTransaction 即可。

Q7：能否监听网络自动切换？
A：监听 session_update 事件中的 namespaces 变更，当 defaultChain 发生变化即可刷新 DApp 状态。

小结

借助 OKX Connect SDK 的简洁接口，你可在极短时间内完成 EVM 链 DApp 钱包集成。从初始化、网络检测到交易签名，仅需调用数条 API 就能全面兼容多链、低延迟、高安全保障。
快去试试吧，下一轮爆款 DApp，或许就从此起步。