OKX Web3 钱包 SDK 集成与使用指南

概述

OKX Web3 钱包 SDK 提供了一套完整的工具，帮助开发者快速集成以太坊虚拟机（EVM）兼容链的钱包功能到去中心化应用（DApp）中。通过该 SDK，用户可以连接钱包、签署交易、发送交易并与智能合约交互，同时支持自定义网络配置和 RPC 调用。

本文将详细介绍 SDK 的安装、初始化、连接钱包、交易签名、错误处理等核心功能，帮助开发者高效完成集成工作。

安装与初始化

在开始集成前，请确保将 OKX App 更新至 6.88.0 或更高版本。

使用 npm 安装 OKX Connect：

npm install @okx/web3-connect

在连接钱包之前，需要初始化一个提供者对象，用于后续的钱包连接、交易发送等操作：

import { OKXUniversalProvider } from '@okx/web3-connect';

const provider = await OKXUniversalProvider.init({
  DAppMetaData: {
    name: 'Your DApp Name',
    icon: 'https://example.com/icon.png'
  }
});

请求参数说明

DAppMetaData：应用元数据对象
- name：字符串类型，应用名称（非唯一标识）
- icon：字符串类型，应用图标 URL。支持 PNG、ICO 等格式（不支持 SVG）。建议提供 180x180px 的 PNG 图标。

返回值

OKXUniversalProvider 实例对象

连接钱包

连接钱包是获取用户钱包地址的必要步骤，该地址将作为用户标识并用于交易签名。

const connectParams = {
  namespaces: {
    eip155: {
      chains: ['1', '137'],
      defaultChain: '1',
      rpcMap: {
        '1': 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
        '137': 'https://polygon-rpc.com'
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['56', '42161'],
      defaultChain: '56'
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve'
  }
};

const session = await provider.connect(connectParams);

请求参数说明

connectParams：连接参数对象
- namespaces：必选命名空间配置
  - eip155：EVM 系统键值
    - chains：字符串数组，链 ID 列表
    - defaultChain：可选，默认链
    - rpcMap：可选，RPC 配置映射（仅支持 EVM 系统）
- optionalNamespaces：可选命名空间配置
  - 配置方式与 namespaces 相同，但允许钱包不支持时仍可连接
- sessionConfig：会话配置
  - redirect：连接成功后的重定向链接（Telegram Mini App 需设置为 tg://resolve）

返回值

Promise<Session> 会话对象
- topic：字符串，会话标识符
- namespaces：记录连接成功的命名空间信息
- accounts：字符串数组，账户信息
- methods：字符串数组，钱包支持的方法列表
- defaultChain：可选，当前会话的默认链
- sessionConfig：可选，会话配置信息
- DAppInfo：DApp 信息对象

检查钱包连接状态

获取当前钱包是否已连接的状态信息。

const isConnected = provider.isConnected();

返回值

boolean：true 表示已连接，false 表示未连接

发送签名与交易

通过此方法可以向钱包发送消息，支持签名、交易等操作。

const requestArguments = {
  method: 'personal_sign',
  params: ['Message to sign', '0x...'],
  chain: '1',
  redirect: 'tg://resolve'
};

const signature = await provider.request(requestArguments);

请求参数说明

requestArguments：请求参数对象
- method：字符串，请求方法名
- params：可选，请求方法参数
- chain：字符串，执行请求的链（建议传递）
- redirect：重定向策略（'none' 或 deeplink）

返回值

根据执行的方法不同，返回结果各异：

personal_sign：返回签名结果字符串
eth_signTypedData_v4：返回签名结果字符串
eth_sendTransaction：返回交易哈希字符串
eth_accounts：返回默认链 ID 的地址数组
eth_requestAccounts：返回默认链 ID 的地址数组
eth_chainId：返回默认链 ID 数值
wallet_switchEthereumChain：返回 null
wallet_addEthereumChain：返回 null
wallet_watchAsset：返回添加是否成功的布尔值

使用 RPC 功能

当标准的 EVM 请求方法无法满足需求时，可以通过配置 RPC 实现更多功能。在连接钱包时，可在 rpcMap 中配置 RPC 信息。

// 在 connect() 方法的 rpcMap 中配置
const rpcMap = {
  '1': 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
  '137': 'https://polygon-rpc.com'
};

// 使用配置的 RPC 发送请求
const blockNumber = await provider.request({
  method: 'eth_blockNumber',
  chain: '1'
});

设置默认网络

在多网络环境下，如果开发者未指定当前操作的网络，交互将通过默认网络进行。

// 在连接时设置默认网络
const connectParams = {
  namespaces: {
    eip155: {
      chains: ['1', '137'],
      defaultChain: '1' // 设置以太坊为主网为默认链
    }
  }
};

断开钱包连接

断开与当前连接钱包的会话。如需切换钱包，请先断开当前连接。

await provider.disconnect();

事件处理

SDK 提供了事件监听机制，可以监听连接状态变化、账户变化等事件。

provider.on('connect', (session) => {
  console.log('Wallet connected', session);
});

provider.on('disconnect', () => {
  console.log('Wallet disconnected');
});

provider.on('accountsChanged', (accounts) => {
  console.log('Accounts changed', accounts);
});

错误代码说明

在连接、交易和断开连接过程中可能抛出的异常。

错误代码	描述
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR	未知错误
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR	钱包已连接
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR	钱包未连接
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR	用户拒绝操作
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED	方法不支持
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED	链不支持
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED	钱包不支持
OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR	连接错误

最佳实践建议

图标优化：提供高质量的 180x180px PNG 图标，确保在不同设备上显示清晰
错误处理：妥善处理用户拒绝连接或签名的情况，提供友好的用户提示
网络切换：实现平滑的网络切换体验，及时更新界面状态
状态管理：合理管理连接状态，在应用重启后保持会话持久性
性能优化：减少不必要的 RPC 调用，合理使用缓存机制

👉 查看实时链上数据工具

常见问题

Q1: 如何判断用户是否安装了 OKX 钱包？
A: 可以通过检查 OKXUniversalProvider 的可用性来判断。如果初始化失败，通常意味着用户未安装钱包或版本过低。

Q2: 支持哪些 EVM 兼容链？
A: SDK 支持所有主流的 EVM 兼容链，包括以太坊、Polygon、BNB Chain、Arbitrum 等，也支持自定义网络的添加。

Q3: 如何处理用户拒绝签名的情况？
A: 当用户拒绝签名时，SDK 会抛出 USER_REJECTS_ERROR 错误。应该捕获这个异常并向用户显示友好的提示信息。

Q4: 是否支持多链同时操作？
A: 是的，SDK 支持多链环境。可以在连接时配置多个链，并通过指定 chain 参数在不同的链上执行操作。

Q5: 如何实现钱包切换功能？
A: 需要先调用 disconnect() 方法断开当前连接，然后重新调用 connect() 方法让用户选择新的钱包。

Q6: 是否支持智能合约交互？
A: 是的，通过 eth_sendTransaction 方法可以发送交易与智能合约进行交互，需要构建正确的交易参数。

通过本指南，您应该已经了解了 OKX Web3 钱包 SDK 的核心功能和集成方法。正确使用这些功能将为您的 DApp 用户提供流畅的钱包体验。