Cosmos 钱包连接指南：OKX Connect SDK 接入 DApp 全流程

关键词：OKX Connect、Cosmos SDK、DApp、Web3 钱包、Cosmos 钱包连接、钱包集成、链交易签名、Mini App、DApp 示例

想 5 分钟让你的 Web3 DApp 升级为 Cosmos 生态入口？本文手把手拆解 OKX Connect SDK 从安装到签名的每一个细节，照着做即可安全、高效地完成钱包集成。

1. 安装与初始化

1.1 确认版本

确保使用 OKX Connect ≥ 6.94.0，才能完整支持 Cosmos 网络。

1.2 安装

npm install @okx/connect

1.3 创建实例

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

const provider = new OKXUniversalProvider({
  dappMetaData: {
    name: 'CosmoSwap',        // 应用名称
    icon: 'https://yourcdn.com/icon180.png' // 180×180 PNG / ICO
  }
});

保留好 provider，后续所有操作——连接、交易、断开——都由它完成。

2. 连接 Cosmos 钱包

钱包连接是获取用户地址与权限的第一步，支持 指定链、可选链 两种模式。

2.1 核心参数

chains: 必填，链 ID 数组，如 ['cosmos:cosmoshub-4', 'cosmos:osmosis-1']
optionalNamespaces: 选填，不受支持时可继续连接
redirect: 建议 Telegram Mini App 传 tg://resolve

2.2 调用示例

const connectParams = {
  namespaces: {
    cosmos: {
      chains: ['cosmos:cosmoshub-4'],
      defaultChain: 'cosmos:cosmoshub-4'
    }
  },
  optionalNamespaces: {
    cosmos: {
      chains: ['cosmos:osmosis-1']
    }
  },
  sessionConfig: {
    redirect: window.location.href // 或 deeplink
  }
};

const session = await provider.connect(connectParams);
console.log(session.accounts); // 钱包地址

返回值字段

topic: 会话 ID（断开会话需用到）
namespaces: 含 Cosmos 对象的 Network 详情
defaultChain: 钱包默认链 ID

3. 检测连接状态

const isConnected = provider.isConnected(); // true | false

场景小贴士：页面加载后先检查状态，若已连接可直接进入主界面，减少重复授权弹窗。

4. 获取账户信息

在 signAmino 或 signDirect 之前，先拿到公共地址与公钥。

const cosmosProvider = new OKXCosmosProvider(provider);
const account = await cosmosProvider.getAccount('cosmos:cosmoshub-4');
/*
{
  address: '0x123...',
  bech32Address: 'cosmos1abcdef...',
  pubKey: Uint8Array(...),
  algo: 'secp256k1'
}
*/

👉 想了解 Cosmos 钱包登录逻辑？这里有一套可复制的实战代码。

5. 消息与交易的签名方法

5.1 签名普通消息

const signature = await cosmosProvider.signMessage({
  chain: 'cosmos:cosmoshub-4',
  signerAddress: account.bech32Address,
  message: '欢迎登录 CosmoSwap'
});

5.2 signAmino（手写 amino 交易）

适用于需要人类可读交易体的业务。

const aminoRes = await cosmosProvider.signAmino({
  chainId: 'cosmos:cosmoshub-4',
  signerAddress: account.bech32Address,
  signDoc: {
    chain_id: 'cosmoshub-4',
    account_number: '1234',
    sequence: '5',
    fee: { gas: '200000', amount: [{ denom: 'uatom', amount: '1000' }] },
    msgs: [...],
    memo: ''
  }
});

5.3 signDirect（二进制 protobuf 交易）

链上协议级交互最安全、最少带宽。
bodyBytes / authInfoBytes / chainId / accountNumber 四大字段需全部对齐节点当前值。

const directRes = await cosmosProvider.signDirect({
  chainId: 'cosmos:cosmoshub-4',
  signerAddress: account.bech32Address,
  signDoc: {
    bodyBytes: Buffer.from(...),
    authInfoBytes: Buffer.from(...),
    chainId: 'cosmoshub-4',
    accountNumber: '1234'
  }
});

6. 断开连接 & 会话管理

场景：用户想切换钱包，需要彻底释放当前会话。

await provider.disconnect();

断链后页码无需刷新，直接重新触发 provider.connect 即可新授权。

7. Event 监听概览

SDK 内置事件：connect, disconnect, accountsChanged, chainChanged。
样式范例：

provider.on('accountsChanged', ([newAddress]) => {
  console.log('用户已切换地址', newAddress);
});

8. 常见错误码速查

错误码	场景描述
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR	用户取消授权
CHAIN_NOT_SUPPORTED	请求链未开放
ALREADY_CONNECTED_ERROR	重复连接同一钱包
METHOD_NOT_SUPPORTED	未实现的方法
CONNECTION_ERROR	网络超时

9. FAQ

Q1：为何必须提供 180×180 PNG 图标？
A：Cosmos 钱包内置安全策略，拒绝 SVG 以避免 XSS；官方指南建议大尺寸提高识别度。

Q2：DApp 内无法识别 Telegram Mini App 跳转？
A：将 redirect 参数设为 tg://resolve 并且确保域名已配置 ALLOWED_TG_DOMAINS。

Q3：重复连接弹窗太频繁？
A：在页面加载时先调用 provider.isConnected() 检查，若已授权就跳过 connect。

Q4：signDirect 的 accountNumber 哪里拿？
A：通过 RPC /auth/accounts/ 接口或第三方索引服务查询链上公共信息，注意缓存 60 秒后失效。

Q5：错误码中出现 UNKNOWN_ERROR，怎么办？
A：记录 error.message 与 error.stack，联系 OKX Connect 开发者支持或在社区论坛发帖，附上日志与代码片段。

Q6：钱包地址格式不是 hex？
A：Cosmos 生态采用 Bech32 地址，以 cosmos1, osmo1 等前缀开头，SDK 同时返回 address 与 bech32Address 供选择。

下一步：实战模板

👉 一键获取可复制的 DApp 钱包连接模板，直接在本地跑起来。

完成以上步骤，你就拥有了支持 Cosmos 链及 Mini App 的完整钱包接入能力。保持 SDK 更新、合理使用事件监听，你的 DApp 将获得更流畅、安全的用户体验。