Cosmos 钱包集成与 DEX API 连接指南

本文将详细介绍如何将您的 DApp 与 Cosmos 生态钱包（包括 App 钱包和 Mini 钱包）进行集成，并利用 DEX API 实现完整的区块链交互功能。无论您是开发者还是技术爱好者，本指南都将为您提供清晰的操作步骤和最佳实践。

准备工作与初始化

在开始集成前，请确保您的 OKX 应用已更新至 6.94.0 或更高版本。以下是初始化所需的步骤和参数说明。

安装方式

推荐使用 npm 进行依赖管理，通过以下命令安装必要的库：

npm install @okx/web3-connect

初始化配置

在连接钱包之前，需要创建一个提供 UI 接口的对象，用于后续的钱包连接和交易发送操作。

请求参数说明

dappMetaData（对象类型）
- name（字符串）：应用名称，不会用作唯一标识。
- icon（字符串）：应用图标的 URL 地址，支持 PNG、ICO 格式，不支持 SVG。建议使用 180x180px 的 PNG 图标。
actionsConfiguration（对象类型）
- modals（数组或字符串）：交易过程中弹窗的显示模式，可选 'before'、'success'、'error' 或 'all'，默认为 'before'。
- returnStrategy（字符串）：用于 App 钱包，指定用户签名/拒绝请求后的深度链接返回策略。例如在 Telegram 中可配置为 tg://resolve。
- tmaReturnUrl（字符串）：用于 Telegram Mini Wallet，指定用户签名/拒绝请求后的深度链接返回策略。可选 'back'、'none' 或自定义链接，默认为 'back'。
uiPreferences（对象类型）
- theme（主题选项）：可选择 THEME.DARK、THEME.LIGHT 或 'SYSTEM'。
- language（语言选项）：支持多种语言，包括 'zh_CN'（简体中文）、'en_US'（英语）等，默认为 'en_US'。

返回值

返回 OKXUniversalConnectUI 对象实例

代码示例

const connectUI = new OKXUniversalConnectUI({
  dappMetaData: {
    name: "My DApp",
    icon: "https://example.com/icon.png"
  },
  actionsConfiguration: {
    modals: ['before', 'success', 'error'],
    returnStrategy: 'none'
  },
  uiPreferences: {
    theme: THEME.DARK,
    language: 'zh_CN'
  }
});

钱包连接流程

连接到钱包

连接到钱包以获取钱包地址作为标识符，以及签名交易所需的必要参数。

请求参数

connectParams（ConnectParams 类型）
- namespaces（对象）：请求连接的必需信息，键为命名空间（如 'eip155' 表示 EVM，'cosmos' 表示 COSMOS）。如果钱包不支持任何请求的链，连接将被拒绝。
  - chains（字符串数组）：链 ID 信息
  - defaultChain（可选字符串）：默认链
- optionalNamespaces（对象）：请求连接的可选信息。即使钱包不支持相应链信息，仍可连接。
  - chains（字符串数组）：链 ID 信息
  - defaultChain（可选字符串）：默认链
- sessionConfig（对象）
  - redirect（字符串）：连接成功后的跳转参数。如果是 Telegram 中的迷你应用，可设置为 Telegram 的深度链接：'tg://resolve'

返回值

Promise 对象，包含：
- topic（字符串）：会话标识符
- namespaces（记录对象）：成功连接的命名空间信息
- chains（字符串数组）：连接的链信息
- accounts（字符串数组）：连接的账户信息
- methods（字符串数组）：钱包在当前命名空间中支持的方法
- defaultChain（可选字符串）：当前会话的默认链
- sessionConfig（可选 SessionConfig）：会话配置
- dappInfo（对象）：DApp 信息
  - name（字符串）：名称
  - icon（字符串）：图标
  - redirect（可选字符串）：连接成功后的重定向参数

👉 获取完整的钱包连接示例代码

连接并签名

连接到钱包获取钱包地址并签名数据；结果将在 'connect_signResponse' 事件中回调。

请求参数

connectParams：同上文连接参数
signRequest（RequestParams[] 数组）：请求连接并签名的方法，最多同时支持一个方法
- method（字符串）：请求的方法名称，COSMOS 支持的方法包括：'cosmos_signArbitrary'
- chainId（字符串）：方法执行所在链的 ID，必须包含在上述命名空间中
- params（多种类型）：请求方法对应的参数

返回值

Promise 对象，包含与普通连接相似的返回值结构

钱包状态管理

检查钱包连接状态

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

返回值

boolean（布尔值）：true 表示已连接，false 表示未连接

断开钱包连接

断开已连接的钱包并删除当前会话。如需切换连接的钱包，请先断开当前钱包连接。

交易操作

准备交易

首先创建 OKXCosmosProvider 对象，构造函数中传入 OKXUniversalConnectUI 实例。

获取账户信息

请求参数

chainId（字符串）：请求的链，例如 cosmos:cosmoshub-4, cosmos:osmosis-1

返回值

对象，包含：
- algo：'secp256k1'
- address（字符串）：钱包地址
- bech32Address（字符串）：bech32 格式的钱包地址
- pubKey（Uint8Array）：公钥

消息签名

请求参数

chain（字符串）：请求执行方法的链
signerAddress（字符串）：签名钱包的地址
message（字符串）：要签名的消息

返回值

Promise 对象，包含：
- pub_key（对象）：公钥信息
  - type（字符串）：公钥类型
  - value（字符串）：公钥值
- signature（字符串）：签名结果

SignAmino 签名

请求参数

chainId（字符串）：请求签名执行的链，必需参数
signerAddress（字符串）：钱包地址
signDoc（对象）：固定格式的要签名的交易信息，类似于 cosmjs OfflineSigner 的 signAmino 方法

返回值

Promise 对象，包含：
- signed（对象）：交易信息
- signature（对象）：签名结果

SignDirect 签名

请求参数

chainId（字符串）：请求签名执行的链，必需参数
signerAddress（字符串）：钱包地址
signDoc（对象）：交易数据
- bodyBytes（Uint8Array）
- authInfoBytes（Uint8Array）
- chainId（字符串）
- accountNumber（字符串）

返回值

Promise 对象，包含：
- signed（对象）：交易信息
- signature（对象）：签名结果

事件处理

集成过程中需要监听和处理各种事件，包括连接状态变化、交易结果返回等。确保您的应用能够妥善处理这些事件以提供流畅的用户体验。

错误代码说明

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

错误代码	描述
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	连接错误

常见问题

如何选择合适的签名方法？

Cosmos 生态支持多种签名方法，包括 SignAmino 和 SignDirect。SignAmino 更适合与旧版钱包兼容，而 SignDirect 提供更高效的交易处理。选择时需考虑您的具体应用场景和目标用户使用的钱包类型。

连接过程中最常见的错误是什么？

用户拒绝错误（USER_REJECTS_ERROR）是最常见的情况，通常发生在用户取消授权操作时。建议在UI中提供清晰的引导，说明连接钱包的必要性和安全性。

如何处理不同的链ID格式？

Cosmos 生态使用特定格式的链ID，如 "cosmoshub-4" 或 "osmosis-1"。在请求时需要确保使用正确的链ID格式，否则会导致链不支持错误（CHAIN_NOT_SUPPORTED）。

是否支持多链同时连接？

是的，通过合理配置 namespaces 和 optionalNamespaces 参数，可以支持多链同时连接。这在DeFi应用和跨链操作场景中特别有用。

如何优化移动端用户体验？

对于移动端应用，建议合理配置 returnStrategy 和 tmaReturnUrl 参数，确保在完成操作后能够正确返回到您的应用界面。

签名失败该如何排查？

首先检查错误代码，确认是用户拒绝、方法不支持还是链不支持。然后验证参数格式是否正确，特别是 chainId 和 signerAddress 的格式是否符合要求。

👉 查看实时钱包连接状态监测工具

通过本指南，您应该已经掌握了 Cosmos 钱包集成的基本流程和关键操作。在实际开发过程中，建议先进行充分的测试，确保各种边界情况都能得到妥善处理，从而为用户提供安全可靠的钱包集成体验。