TON 区块链 Injected Provider API 接入指南

Injected Provider API 是一个由 Web3 钱包注入到用户访问网站的 JavaScript 接口。开发者可利用此 API 请求用户账户、读取链上数据，并协助用户签署消息与交易。本文将详细解析其核心功能与接入方法，帮助 DApp 快速集成 TON 区块链钱包服务。

核心概念与兼容性

什么是 Injected Provider API？

Injected Provider API 是 Web3 钱包（如 OKX Wallet）向 DApp 页面注入的标准化 JavaScript 接口。通过该接口，DApp 可安全地获取用户授权、访问区块链数据，并处理交易签名等操作，无需用户暴露私钥。

协议兼容性说明

OKX Wallet 的 TON API 完全遵循 Ton Connect 协议 规范。建议开发者使用 TON Connect SDK 以简化接入流程，确保兼容性与开发效率。

基础对象与属性解析

获取注入对象

OKX Wallet 依据 Ton Connect 协议向 DApp 注入全局对象 tonProtocol。该对象包含以下关键属性：

deviceInfo 设备信息

用于获取当前钱包客户端的环境信息，包含以下字段：

• platform: 设备操作系统类型（如 "ios", "android", "chrome"）
• appName: 钱包应用名称
• appVersion: 钱包版本号
• maxProtocolVersion: 支持的最高协议版本
• features: 钱包支持的功能特性列表

walletInfo 钱包信息

描述钱包应用的元数据，结构如下：

• name: 钱包公开名称
• app_name: 钱包内部唯一标识符
• image: 钱包图标 URL
• about_url: 钱包介绍页面链接
• platforms: 支持的平台列表（如 "chrome", "ios"）

protocolVersion 协议版本

当前支持的 Ton Connect 协议版本号（默认为 2）。

核心方法详解

connect 连接钱包

初始化与钱包的连接，可同时请求地址获取与签名验证。

请求参数

• protocolVersion: DApp 期望的协议版本（需与钱包兼容）
• message: 连接请求的具体内容

message 参数结构：

• manifestUrl: DApp 的 manifest.json 文件 URL（包含应用名称、图标等元数据）

• items: 操作指令列表，支持两类请求：

  • ton_addr: 获取用户地址及公钥
  • ton_proof: 请求钱包签名验证

返回值

返回 Promise 对象，解析为 ConnectEvent 结构体，包含连接结果或错误信息。

代码示例

仅获取用户地址信息：

const result = await tonProtocol.connect({
  protocolVersion: 2,
  message: {
    manifestUrl: 'https://dapp.example/manifest.json',
    items: [{ name: 'ton_addr' }]
  }
});

同时请求地址与签名验证：

const result = await tonProtocol.connect({
  protocolVersion: 2,
  message: {
    manifestUrl: 'https://dapp.example/manifest.json',
    items: [
      { name: 'ton_addr' },
      { name: 'ton_proof', payload: '验证数据' }
    ]
  }
});

restoreConnection 恢复连接

尝试重建之前的钱包连接会话，仅返回 ton_addr 指令结果。若连接已失效则抛出错误。

代码示例

try {
  const addressInfo = await tonProtocol.restoreConnection();
  console.log('已恢复连接:', addressInfo);
} catch (error) {
  console.error('连接恢复失败:', error);
}

send 消息发送

向钱包发送操作指令，目前支持交易发送与连接断开两类消息。

请求参数

• message: 消息体，包含以下字段：

  • method: 方法名（"sendTransaction" 或 "disconnect"）
  • params: 方法参数
  • id: 消息唯一标识符（用于请求响应匹配）

sendTransaction 交易发送

用于签署并广播交易至区块链网络。

参数结构：

{
  valid_until: 1735689999, // 过期时间戳（可选）
  network: 'mainnet',      // 网络类型（仅主网）
  from: 'wc:address',      // 发送地址（可选）
  messages: [              // 消息数组（1-4条）
    {
      address: '接收地址',
      amount: '1000000000', // 金额（纳币单位）
      payload: 'base64编码数据', // 负载数据（可选）
      stateInit: 'base64编码状态' // 初始化数据（可选）
    }
  ]
}

返回值：Promise 解析为交易签名结果字符串。

disconnect 断开连接

终止当前钱包会话，无需额外参数。

返回值：Promise 解析为操作结果。

listen 事件监听

注册回调函数以监听钱包连接状态变化。

使用示例

const removeListener = tonProtocol.listen((event) => {
  console.log('钱包事件:', event);
});

// 取消监听
removeListener();

on / off 事件管理（OKX 扩展API）

专用于处理账户切换等高级事件，支持以下事件类型：

• connect: 钱包连接成功时触发
• disconnect: 连接断开时触发
• accountChanged: 用户切换账户时触发

代码示例

// 添加事件监听
tonProtocol.on('accountChanged', (newAccount) => {
  updateInterface(newAccount);
});

// 移除事件监听
tonProtocol.off('accountChanged', handlerFunction);

常见问题

Injected Provider API 与 TON Connect SDK 有何区别？

Injected Provider API 是底层接口，直接与钱包扩展交互；TON Connect SDK 是基于协议封装的开发工具包，提供更高级的抽象与跨钱包兼容性。对于简单需求可直接使用 API，复杂场景推荐采用 SDK。

连接请求中 manifest.json 的作用是什么？

该文件包含 DApp 的名称、图标、描述等元信息，用于在钱包界面中向用户展示授权请求的上下文，提升安全性与用户体验。文件需通过 HTTPS 公开访问。

交易发送中的金额单位是什么？

所有金额字段均以 纳币（nanoton） 为单位，1 TON = 1,000,000,000 纳币。发送前需将金额转换为字符串格式的纳币数值。

如何处理用户拒绝授权的情况？

所有连接和交易方法均返回 Promise，拒绝授权时会抛出错误。建议使用 try-catch 块处理异常，并向用户展示友好提示。

是否支持多链同时操作？

当前 API 仅针对 TON 区块链设计。若需操作多链，需检查钱包是否注入其他链的 Provider 对象，并分别调用对应接口。

如何优化交易成功率？

确保 valid_until 设置合理的时间窗口（建议 5-10 分钟），避免网络延迟导致过期。同时合理估算 Gas 费用，👉查看实时链上数据工具获取最新网络状态。

通过本文介绍的 API 与方法，开发者可快速实现 DApp 与 TON 钱包的深度集成，为用户提供安全流畅的区块链交互体验。建议在实际开发中结合协议文档与测试网络进行充分验证。