开发者指南：如何在 DApp 中集成 OKX Connect，支持 EVM 兼容链的签名与交易

关键词：SDK、EVM 兼容链、钱包连接、签名、交易、RPC 配置、OKX Connect
适用读者：前端 / Web3 开发者、DApp 架构师、小程序工程师

快速上手：安装与初始化

升级到最新 OKX App 6.88.0 及以上版本，即可调用开放能力。
通过 npm 安装 SDK，一行命令完成依赖：

npm install @okxconnect/sdk-js

在项目中引入并初始化：

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

const provider = await OKXUniversalProvider.init({
  DAppMetaData: {
    name: '我的 NFT 市场',
    icon: 'https://example.com/icon-180x180.png' // PNG/ICO，180×180 像素
  }
})

📌 上传的 icon 需为 180×180px 的 PNG 或 ICO；SVG 暂不支持。

连接钱包：获取用户地址

一旦 provider 就绪，调用 connect() 即可弹出授权页。支持主链 / 自定义链、重定向配置。

await provider.connect({
  namespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:56'],     // ETH 主网 + BNB Chain
      defaultChain: 'eip155:1',              // 默认链
      rpcMap: {
        '1': 'https://mainnet.infura.io/...',
        '56': 'https://bsc-dataseed.binance.org/'
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:137'],                // 可做可选链
      rpcMap: { '137': 'https://polygon-rpc.com/' }
    }
  },
  sessionConfig: {
    redirect: isTelegramMiniApp ? 'tg://resolve' : 'none'
  }
})

连接成功后 SDK 返回：

accounts: 用户可用地址
defaultChain: 默认链 ID
namespaces: 支持的方法列表

快速检查：钱包是否已连接

在页面渲染前刷新连接状态，避免重复弹窗：

const connected = await provider.isConnected()     // ⇒ boolean
connected && console.log('已连接：', provider.session.accounts)

发起签名与交易

provider 内置常用异步方法，覆盖 99% EVM 签名 / 交易 场景：

场景	方法示例	返回值
个人签名	`personal_sign`	`string` 签名结果
签名数据结构化	`eth_signTypedData_v4`	`string` 签名结果
转账 & 合约调用	`eth_sendTransaction`	`string` 交易 hash
获取地址列表	`eth_accounts` / `eth_requestAccounts`	`string[]` 地址列表
切换链	`wallet_switchEthereumChain`	`null`
添加自定义链	`wallet_addEthereumChain`	`null`
添加代币观察	`wallet_watchAsset`	`boolean`

示例：一键发起交易

const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0x...',
    to: '0x...',
    value: '0x5af3107a4000',
    data: '0x...'
  }],
  chain: 'eip155:1',
  redirect: 'none'  // 如需回到 App，可设置为深度链接
})

RPC 拓展：更高级的功能

当内置方法无法满足复杂需求（如读取合约 Apollo，监听区块事件），可直接通过已配置的 rpcMap 走任何支持 JSON-RPC 的节点。

在 connect() 时为对应链填入 rpcMap
用 provider.request({ method: 'eth_call', params: [...] }) 自由读写链上数据

多网络处理：设置默认网络

如果当前 DApp 跨越主网、测试网、L2，请明确指定操作链，减少用户手动切换。

provider.setDefaultChain('eip155:100') // 切到 Gnosis Chain

断开会话：安全退出

小贴士：在切换钱包、用户登出页面或刷新 TOKEN 时，先断开原会话可防止权限泄露：

await provider.disconnect()

监听事件：链切换 / 账户变更

订阅 provider EventEmitter，可在 UI 无刷新时同步钱包状态：

provider.on('accountsChanged', accounts => {
  console.log('地址变化：', accounts)
})

provider.on('chainChanged', chainId => {
  console.log('链已切到：', chainId)
})

FAQ｜常见疑问一次读懂

Q1：如何处理用户拒绝授权？
A：SDK 会抛出 USER_REJECTS_ERROR；向用户友好提示，引导其返回应用。

Q2：支持哪些 EVM 链？
A：只要你在 eip155.namespaces 中配置的 chainId/节点可被钱包识别，任何 EVM 兼容链均可接入，包括 ETH、BNB、Polygon、Optimism、Arbitrum 等。

Q3：为什么我设置了自定义链却无法连接？
A：确认 wallet_addEthereumChain 方法未被拒绝；并检查 RPC URL 是否正常可达。

Q4：Telegram Mini App 必须使用深度链接吗？
A：是的，设置 redirect 为 tg://resolve 可避免授权后意外停留在外部浏览器。

Q5：能否一次请求多条链？
A：可以，把多个 chainId 拼入 namespaces.eip155.chains，但需保证钱包已添加这些链，或 fallback 使用 optionalNamespaces。

Q6：并发请求是否会冲突？
A：provider.request 内部队列化，并发调用会根据钱包响应顺序逐个返回，不必担心竞态。

踩坑锦囊

PNG icon：< 200 KB，可大幅降低加载失败率
链 ID 需要 eip155:56 的完整前缀，而非 56
👉 想一探究竟？立即体验完整示例代码与线上钱包直连
错误码对照表
- OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED → 钱包未实现对应方法
- OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED → 链未添加，需先 wallet_addEthereumChain

上线检查清单

✅ App 版本 ≥ 6.88.0
✅ 更新 icon & name 确保安全域名
✅ 多测试链配置 + 主网异常兜底
✅ 收集匿名地址 / session 日志用于无日志回滚场景
👉 查看完整 Dev Console 控制台与调试播放器

恭喜你已通关全套流程！用 OKX Connect 打通 SDK、EVM 兼容链与用户钱包，三步完成签名、交易和 Web3 身份认证。祝你的 DApp 早日上线，与全球千万用户早一点互动。