Ton链钱包集成指南：快速上手 OKX Ton Connect SDK

关键词：Ton链、钱包集成、TON网络、DApp开发、Ton Connect、SDK接入、交易签名、跨平台连接

如果你曾用 Ton Connect 的老方案，依旧可以沿用本文档，只需简单替换即可继续开发；若你过去使用 OKX Connect，则可以改用 ProviderSDK，一次接入即可支持 TON 及其他网络的多链请求，降低开发成本并统一代码风格。

下文按照“安装 → 初始化 → 连接 → 签名 → 监听” 的顺序，手把手演示 OKX Ton Connect SDK 的核心用法，并穿插实战示例与常见疑问，帮助你快速完成 钱包集成。

一、SDK 安装与初始化

1. CDN 方式

在 HTML <head> 或 <body> 中插入脚本，示例代码将 latest 版本引入：

<script src="https://your-cdn.com/okx-ton-connect-sdk@latest/dist/index.umd.js"></script>

引入后，将获得全局对象 OKXTonConnectSDK，可直接引用：

const connector = new OKXTonConnectSDK.OKXTonConnect();

2. NPM 方式

npm install okx-ton-connect-sdk --save

import { OKXTonConnect } from 'okx-ton-connect-sdk';

3. 初始化配置

创建实例前，需设置 metaData：

const okxTonConnect = new OKXTonConnect({
  metaData: {
    name: '我的DApp',
    icon: 'https://your-app.com/logo-180x180.png'   // 180×180 PNG 最佳
  }
});

二、连接钱包

运行环境	openUniversalLink	下一步动作
移动端浏览器 / Telegram	true	直接唤起 OKX App，无需手动扫码
PC 浏览器	false	生成二维码，等待用户扫码

核心代码

const universalLink = await okxTonConnect.connect({
  openUniversalLink: true,        // 根据上表灵活切换
  tonProof: tonProofFromBackend,  // 可选：携带后端返回的签名
  redirect: 'tg://resolve?domain=yourbot'   // 在 Telegram 场景中可用
});

返回值 universalLink 为一串可被二维码化的 URL，PC 端可展示二维码，移动端可直接深跳。

👉 想要三分钟完成 Demo？看看 10 行代码就能跑通的小示例。

三、断点续连与断开

恢复连接

await okxTonConnect.restoreConnection();

如果用户曾经授权过，调用即可省掉再度扫码的流程。

断开钱包

await okxTonConnect.disconnect();

若想切换钱包，先断后连即可。

四、发送 TON 交易

构造交易消息

const tx = {
  validUntil: Date.now() + 600 * 1000,  // 10 分钟后过期
  messages: [{
    address: '目标地址',
    amount: '100000000',               // 0.1 TON，单位为 nanoton
    payload: '' // 可选：附加消息体
  }]
};

// 事件钩子
const txOptions = {
  onRequestSent: () => console.log('已发送签名请求')
};

const { boc } = await okxTonConnect.sendTransaction(tx, txOptions);

返回值 boc 为 Base64 字符串，可直接广播到 TON 网络完成转账。

监听签名结果

SDK 会自动触发「成功」或「失败」事件，无需轮询。

五、钱包状态实时监听

注册监听即可在连接、断开、交易等重大节点获取通知：

const unlisten = okxTonConnect.onStatusChange(
  (walletInfo) => {
    console.log('钱包信息已更新：', walletInfo.account.address);
  },
  (err) => {
    console.warn('监听异常：', err);
  }
);

// 组件卸载或不再需要监听时
unlisten();

六、常用事件总览

OKX_TON_CONNECTION_STARTED
OKX_TON_CONNECTION_COMPLETED
OKX_TON_CONNECTION_ERROR
OKX_TON_TRANSACTION_SENT_FOR_SIGNATURE
OKX_TON_TRANSACTION_SIGNED
OKX_TON_TRANSACTION_SIGNING_FAILED
OKX_TON_DISCONNECTION

借助事件系统，你可像监听点击事件一样管理钱包生命周期。

七、异常码速查

所有异常以枚举抛出，可用 err.code 进行分支处理：

错误码	场景说明
ALREADY_CONNECTED_ERROR	已连接再次连接
USER_REJECTS_ERROR	用户拒绝授权或签名
WALLET_NOT_SUPPORTED	目标钱包未被识别
UNKNOWN_ERROR	其他未知原因

示例分支：

try {
  await okxTonConnect.connect();
} catch (e) {
  if (e.code === 'USER_REJECTS_ERROR') {
    alert('用户拒绝连接');
  } else {
    alert(`连接错误: ${e.message}`);
  }
}

八、常见问题 FAQ

Q1：我需要额外申请白名单吗？
不需要。直接调用 SDK即可，上线前仅需在 OKX 开放平台注册应用名称与图标。

Q2：钱包连接后如何获取用户地址？
连接成功后会返回 walletInfo.account.address，字段格式为 0:<十六进制>。

Q3：SDK 兼容哪些 Ton 钱包？
目前已确认 OKX App（iOS、Android）与部分社区钱包支持协议。如有更多需求，可提交接入申请。

Q4：连接状态多久失效？
默认 24 小时无交互自动失效；可通过 restoreConnection 续活，或引导用户扫码恢复。

Q5：如何批量发送多条消息？
在 messages 数组中最多存放 4 条消息，SDK 会顺序广播，但网络不保证顺序执行，请务必在业务层面核对校验。

Q6：有没有现成的 React/Vue 组件？
官方 @okxconnect/react 与 @okxconnect/vue3 已在社区开源，一插即用。👇

👉 立刻查看快速开始示例，10 分钟跑通你的第一款 Ton DApp。

九、最佳实践小结

多端自检：发布前请分别在 PC、安卓、Telegram WebApp 中反复测试 openUniversalLink 开关，确保过渡流畅。
图标一致性：metaData.icon 使用 180×180 PNG，能显著降低用户误判风险，提升首次授权率。
错误兜底：所有异步操作需加 try/catch，对用户可见的异常文案务必中文友好。
性能优化：在单页应用(SPA)中，连接一次后若页面未刷新，可缓存 walletInfo 至内存或本地存储，减少多次调用 get account。

现在，你已掌握 OKX Ton Connect SDK 的全部关键脚本与注意事项，剩下的就是在你的 Ton链 新产品中自由发挥。祝开发顺利，早日部署上线！