OKX Connect 快速入门：三步接入 EVM 兼容链钱包

在 Web3 时代，用户体验就是生命。如果你的去中心化应用（DApp）无法在 30 秒内完成「连接钱包」的步骤，用户流失率可能高达 70% 以上。本指南基于 OKX Connect SDK，手把手演示如何 在 5 分钟内 为前端网页或小程序钱包注入丝滑的 EVM 兼容链接入能力。文中示例覆盖 npm 初始化、参数配置、签名交易等核心流程，并穿插 3-5 个常见故障排查清单，助你少走弯路。

环境准备

Node ≥ 18
OKX App ≥ 6.90.1 或 Telegram Mini Wallet
项目框架：React / Vue / 原生 JS 均可

👉 立即预览线上 Demo，直观点击即连钱包！

第一步：安装 SDK

最常用的 npm 安装方法只需一行命令：

npm install @okxconnect/ui

第二步：初始化连接对象

在入口文件引入并创建 OKXUniversalConnectUI 实例，核心代码如下：

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

const okxConnect = await OKXUniversalConnectUI.init({
  dappMetaData: {
    name: '我的 NFT 市场',
    icon: 'https://example.com/icon-180.png', // 180×180 PNG，SVG 不支持
  },
  actionsConfiguration: {
    modals: 'all',            // 显示 before / success / error 全部弹窗
    returnStrategy: 'none',   // App 钱包回调
    tmaReturnUrl: 'back',     // Telegram Mini Wallet 默认回到 DApp
  },
  uiPreferences: {
    theme: THEME.SYSTEM,      // 跟随系统明暗模式
  },
  language: 'zh_CN',
  restoreConnection: true,    // 自动记忆上次连接
});

出现初始化报错？检查网络通畅及 icon 地址 200 返回，缺一不可。

核心配置解读

字段	用途	示例值
`dappMetaData.icon`	列表展示图标	180×180 PNG
`restoreConnection`	是否记忆钱包地址	true / false
`uiPreferences.theme`	视觉风格	THEME.DARK / LIGHT / SYSTEM
`language`	界面语言	zh_CN、en_US 等 18 种可选

第三步：连接钱包并获取账户

连接钱包的动作同时能返回 签名者地址、支持链列表 等字段，代码超短：

const session = await okxConnect.openModal({
  namespaces: {
    // 关键：eip155 表示 EVM 兼容链
    eip155: {
      chains: ['eip155:1', 'eip155:56'], // Ethereum & BNB Chain
      defaultChain: 'eip155:1',
      rpcMap: {
        'eip155:1': 'https://eth.llamarpc.com',
      },
    },
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:137'], // Polygon 做可选项
    },
  },
});

// session.accounts[0] 就是用户当前地址
console.log('已连接地址:', session.accounts[0]);

如果用户还没有钱包，SDK 会自动抛错，记得捕获 USER_REJECTS_ERROR 给用户友好提示。

进阶：一键签名登录

如果你想 连接 + 身份验证 一步到位，可把 signRequest 塞到同一调⽤里，示例：

await okxConnect.openModalAndSign({
  namespaces: { eip155: { /* 同上 */ } },
  signRequest: [{
    method: 'personal_sign',
    chainId: 'eip155:1',
    params: ['登录随机数：123456'],
  }],
});

成功后监听事件 connect_signResponse，即可拿到链上签名字符串，方便后端校验。

👉 点这里查看签名结果实时调试技巧

判断当前是否已连接

动态菜单场景中，我们经常要先知道用户是否已登录，只需一句布尔值：

const isConnected = okxConnect.isConnected();
if (!isConnected) {
  // 展示「连接钱包」按钮
}

发送交易 & 自定义 RPC

调用通用 request 方法即可签名、广播交易，如自定义 RPC：

await okxConnect.request({
  chain: 'eip155:137',
  method: 'eth_sendTransaction',
  params: [{
    to: '0x...',
    value: '1000000000000000',
    data: '0x00',
  }],
  returnStrategy: 'none',
});

可把常用配置再 init 中一次写好，避免重复传参。

断开连接与释放内存

用户退出时务必执行：

await okxConnect.disconnect();
okxConnect.removeAllListeners(); // 防止内存泄露

错误码速查表（精简版）

UNKNOWN_ERROR – 网络异常
ALREADY_CONNECTED_ERROR – 重复连接
USER_REJECTS_ERROR – 用户拒绝
CHAIN_NOT_SUPPORTED – 链不支持
WALLET_NOT_SUPPORTED – 钱包类型不匹配

FAQ：开发者最常见 5 问

1. 为什么图标加载失败？
确保 180×180 PNG，HTTP/HTTPS 均可，SVG 不被解析。

2. 如何切换默认链？
运行时调用 okxConnect.setDefaultChain('eip155:137') 即可。

3. Mini Wallet 兼容哪些场景？
Telegram Mini App 最全，其它平台重写 returnStrategy 还需额外开发。

4. 自定义网络 never shown？
先在 optionalNamespaces 里填写，再监听是否返回对应链信息，如无则主动调用 wallet_addEthereumChain。

5. 如何支持多条链同时调用？
通过数组一次性填入多条链即可，SDK 会根据钱包能力自动裁剪不支持的链。

通过以上四步，你即可将 OKX Connect 与任何 EVM 链应用深度融合：从 UI 统一到一键签名，再到完整下线流程，提供与主流交易所同样的流畅体验。还差最后一句：立即动手，用户会用行动告诉你升级后的留存提升！