Onchain OS x402 支付

签署 x402 支付授权并返回支付证明，用于访问受支付保护的资源。支持 TEE 签名（通过钱包会话）或本地签名（使用用户自己的私钥）。

前置检查

在运行任何 onchainos 命令之前，请始终按顺序执行以下步骤。不要向用户回显常规命令输出；仅在安装、更新或处理失败时提供简短的状态更新。

1. 获取最新稳定版本：从 GitHub API 获取最新的稳定版本标签：

   curl -sSL "https://api.github.com/repos/okx/onchainos-skills/releases/latest"
   

   提取 tag_name 字段（例如 v1.0.5）作为 LATEST_TAG。
   如果 API 调用失败且 onchainos 已安装在本地，则跳过步骤 2-3 并继续运行命令（用户可能处于离线状态或受到速率限制；使用旧二进制文件总比阻塞要好）。如果 onchainos 未安装，则停止并告知用户检查其网络连接或从 https://github.com/okx/onchainos-skills 手动安装。

2. 安装或更新：如果未找到 onchainos，或者缓存 ~/.onchainos/last_check（Windows 上为 $env:USERPROFILE\.onchainos\last_check）超过 12 小时：
   • 从最新发布标签下载安装程序及其校验和文件：
     • macOS/Linux：
       curl -sSL "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" -o /tmp/onchainos-install.sh
curl -sSL "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -o /tmp/installer-checksums.txt
     • Windows：
       Invoke-WebRequest -Uri "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.ps1" -OutFile "$env:TEMP\onchainos-install.ps1"
Invoke-WebRequest -Uri "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -OutFile "$env:TEMP\installer-checksums.txt"
   • 根据 installer-checksums.txt 验证安装程序的 SHA256。如果不匹配，停止并发出警告——安装程序可能已被篡改。
   • 执行：sh /tmp/onchainos-install.sh（Windows 上为 & "$env:TEMP\onchainos-install.ps1"）。
     安装程序内部处理版本比较，仅在需要时下载二进制文件。
   • 如果出现其他故障，请指向 https://github.com/okx/onchainos-skills。
3. 验证二进制文件完整性（每个会话一次）：运行 onchainos --version 获取已安装的版本（例如 1.0.5 或 2.0.0-beta.0）。将安装的标签构造为 v<version>。
   为已安装版本的标签（不一定是 LATEST_TAG）下载 checksums.txt：
   curl -sSL "https://github.com/okx/onchainos-skills/releases/download/v<version>/checksums.txt" -o /tmp/onchainos-checksums.txt
   查找平台目标并将已安装二进制文件的 SHA256 与校验和进行比较。
   如果不匹配，则重新安装（步骤 2）并重新验证。如果仍然不匹配，停止并发出警告。
   • 平台目标 —— macOS：arm64->aarch64-apple-darwin，x86_64->x86_64-apple-darwin；Linux：x86_64->x86_64-unknown-linux-gnu，aarch64->aarch64-unknown-linux-gnu，i686->i686-unknown-linux-gnu，armv7l->armv7-unknown-linux-gnueabihf；Windows：AMD64->x86_64-pc-windows-msvc，x86->i686-pc-windows-msvc，ARM64->aarch64-pc-windows-msvc
   • 哈希命令 —— macOS/Linux：shasum -a 256 ~/.local/bin/onchainos；Windows：(Get-FileHash "$env:USERPROFILE\.local\bin\onchainos.exe" -Algorithm SHA256).Hash.ToLower()
4. 检查技能版本漂移（每个会话一次）：如果 onchainos --version 比此技能的 metadata.version 更新，则显示一次性通知，说明技能可能已过时，并建议用户通过其平台方法重新安装技能。不要阻塞。
5. 不要因命令失败而自动重新安装。 报告错误并建议使用 onchainos --version 或从 https://github.com/okx/onchainos-skills 手动重新安装。
6. 速率限制错误。 如果命令遇到速率限制，共享 API 密钥可能已被限制。建议在 OKX 开发者门户 创建个人密钥。如果用户创建了 .env 文件，提醒他们将 .env 添加到 .gitignore。

技能路由

• 查询认证钱包余额 / 发送代币 / 交易历史 → 使用 okx-agentic-wallet
• 查询公开钱包余额（按地址） → 使用 okx-wallet-portfolio
• 代币兑换 / 交易 / 买入 / 卖出 → 使用 okx-dex-swap
• 代币搜索 / 元数据 / 排名 / 持有者信息 / 集群分析 → 使用 okx-dex-token
• 代币价格 / K线图 / 钱包盈亏 / 地址追踪活动 → 使用 okx-dex-market
• 聪明钱 / 巨鲸 / KOL 信号 / 排行榜 → 使用 okx-dex-signal
• Meme / pump.fun 代币扫描 → 使用 okx-dex-trenches
• 交易广播 / Gas 估算 → 使用 okx-onchain-gateway
• 安全扫描（代币 / DApp / 交易 / 签名） → 使用 okx-security

链名称支持

--network 使用 CAIP-2 格式：eip155:<realChainIndex>。onchainos wallet chains 返回的所有 EVM 链均受支持。链列表中的 realChainIndex 字段对应于 CAIP-2 标识符的 <chainId> 部分。

常见示例：

要获取支持的 EVM 链及其 realChainIndex 的完整列表，请运行：

onchainos wallet chains

非 EVM 链（例如 Solana、Tron、Ton、Sui）不支持 x402 支付 —— 仅接受 eip155:* 标识符。

背景：x402 协议

x402 是一种 HTTP 支付协议。当服务器返回 HTTP 402 Payment Required 时，它包含一个 base64 编码的 JSON 有效负载，描述所需的支付。完整流程为：

1. 发送请求 → 收到带有 base64 编码支付有效负载的 HTTP 402
2. 解码有效负载，从 accepts[0] 中提取支付参数
3. 通过 TEE 签名 → onchainos payment x402-pay → 获取 { signature, authorization }
4. 组装支付标头并重放原始请求

此技能端到端负责步骤 2–4。

快速开始

# 为 X Layer USDG 保护的资源签署 x402 支付
onchainos payment x402-pay \
  --network eip155:196 \
  --amount 1000000 \
  --pay-to 0xRecipientAddress \
  --asset 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8 \
  --max-timeout-seconds 300

命令索引

操作流程

步骤 1：发送原始请求

发出用户要求的 HTTP 请求。如果响应状态不是 402，则直接返回结果 —— 无需支付，不要检查钱包或尝试登录。

重要：在发送请求之前，不要检查钱包状态或尝试登录。仅当响应为 HTTP 402 时，才继续进行支付步骤。

步骤 2：解码 402 有效负载

如果响应为 HTTP 402，则正文是 base64 编码的 JSON 字符串。解码：

rawBody  = response.body          // base64 字符串
decoded  = JSON.parse(atob(rawBody))
option   = decoded.accepts[0]

从 option 中提取这些字段：

⚠️ 强制：显示支付详情并停止等待用户确认。在用户明确确认之前，不要检查钱包状态、运行 onchainos wallet status、尝试登录或调用任何其他工具。

向用户呈现以下信息：

此资源需要 x402 支付：

• 网络：<链名称> (<network>)
• 代币：<代币符号> (<asset>)
• 金额：<人类可读金额>（使用代币小数从最小单位转换）
• 支付至：<payTo>

是否继续支付？（是 / 否）

然后停止并等待用户的回应。不要在同一个回合中继续。

• 用户确认 → 继续步骤 3。
• 用户拒绝 → 立即停止，不进行支付，不检查钱包。

步骤 3：检查钱包状态（仅在用户明确确认支付后）

现在需要支付，检查用户是否有钱包会话：

onchainos wallet status

• 已登录 → 继续步骤 4（签名）。
• 未登录 → 询问用户：

“此资源需要支付（x402）。您需要一个钱包来签署支付。您想创建一个吗？（免费，大约需要 30 秒。）”

• 用户同意 → 运行 onchainos wallet login（AK 登录，无邮箱）或 onchainos wallet login <email>（OTP 登录），然后继续步骤 4。
• 用户拒绝 → 切换到本地签名后备方案（见下文）。

步骤 4：签名

使用提取的参数运行 onchainos payment x402-pay。返回 { signature, authorization }。

如果签名失败（例如，会话过期、未登录、AK 重新登录失败）：

• 不要简单地取消或放弃。
• 询问用户：“签名失败，因为没有活动钱包会话。您想现在登录，还是使用您自己的私钥在本地签名？”
  • 用户想要登录 → 运行 onchainos wallet login 或 onchainos wallet login <email>，然后重试此步骤。
  • 用户想要本地签名 → 切换到本地签名后备方案（见下文）。
  • 用户想要取消 → 此时才取消请求。

步骤 5：组装标头并重放

从 decoded.x402Version 确定标头名称：

• x402Version >= 2 → PAYMENT-SIGNATURE
• x402Version < 2（或不存在） → X-PAYMENT

构建标头值：

paymentPayload = { ...decoded, payload: { signature, authorization } }
headerValue    = btoa(JSON.stringify(paymentPayload))

重放附加了标头的原始请求：

GET/POST <original-url>
<header-name>: <headerValue>

向用户返回最终的响应正文。

步骤 6：建议后续步骤

成功支付并得到响应后，建议：

以对话形式呈现，例如：“完成！资源返回了以下结果。您想检查您更新后的余额吗？” —— 切勿向用户暴露技能名称或内部字段名称。

跨技能工作流

工作流 A：为受 402 保护的 API 资源支付（最常见）

用户：“获取 https://api.example.com/data —— 它需要 x402 支付”

1. 发送 GET https://api.example.com/data                              → HTTP 402 带有 base64 有效负载
       ↓ 解码有效负载，提取 accepts[0]
2. okx-x402-payment   onchainos payment x402-pay \
                        --network eip155:196 --amount 1000000 \
                        --pay-to 0xAbC... \
                        --asset 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8   → { signature, authorization }
       ↓ 组装支付标头
3. 使用 PAYMENT-SIGNATURE 标头重放 GET https://api.example.com/data  → HTTP 200

数据交接：

• accepts[0].network → --network
• accepts[0].amount（或 maxAmountRequired） → --amount
• accepts[0].payTo → --pay-to
• accepts[0].asset → --asset

工作流 B：支付后检查余额

用户：“访问这个付费 API，然后显示我花了多少钱”

1. okx-x402-payment   （上述工作流 A）                              → 支付证明 + 成功响应
2. okx-agentic-wallet  onchainos wallet balance --chain 196            → 支付后的当前余额

工作流 C：支付前的安全检查

用户：“这个 x402 支付安全吗？资产是 0x4ae46a…”

1. okx-security        onchainos security token-scan \
                        --address 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8 \
                        --chain 196                                        → 代币风险报告
       ↓ 如果安全
2. okx-x402-payment   （上述工作流 A）                              → 签名并支付

CLI 命令参考

1. onchainos payment x402-pay

签署 x402 支付并返回 EIP-3009 支付证明。

onchainos payment x402-pay \
  --network <network> \
  --amount <amount> \
  --pay-to <address> \
  --asset <address> \
  [--from <address>] \
  [--max-timeout-seconds <seconds>]

返回字段：

输入 / 输出示例

用户说： “获取 https://api.example.com/data —— 它需要 x402 支付”

步骤 1 —— 原始请求返回 402：

HTTP 402
Body: "eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W3s..."  ← base64

解码后的有效负载：

{
  "x402Version": 2,
  "accepts": [{
    "network": "eip155:196",
    "amount": "1000000",
    "payTo": "0xAbC...",
    "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "maxTimeoutSeconds": 300
  }]
}

步骤 3–4 —— 检查钱包 + 签名：

onchainos payment x402-pay \
  --network eip155:196 \
  --amount 1000000 \
  --pay-to 0xAbC... \
  --asset 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8 \
  --max-timeout-seconds 300
# → { "signature": "0x...", "authorization": { ... } }

步骤 5 —— 组装标头并重放：

paymentPayload = { ...decoded, payload: { signature, authorization } }
headerValue    = btoa(JSON.stringify(paymentPayload))

GET https://api.example.com/data
PAYMENT-SIGNATURE: <headerValue>

→ HTTP 200  { "result": "..." }

本地签名后备方案（无钱包）

如果用户没有钱包并选择不创建，则引导他们使用自己的私钥进行本地 EIP-3009 签名。

前提条件

• 用户拥有本地私钥（例如，在 .env 文件中、硬件钱包或 MetaMask 导出中）
• 付款人地址必须在目标链上持有足够数量的 asset 代币 ERC-20 余额
• asset 代币合约必须支持 EIP-3009 transferWithAuthorization

步骤 1：解码 402 有效负载

与主流程相同 —— 解码 base64 正文并提取 accepts[0]：

rawBody  = response.body
decoded  = JSON.parse(atob(rawBody))
option   = decoded.accepts[0]

提取：network、amount（或 maxAmountRequired）、payTo、asset、maxTimeoutSeconds。

步骤 2：构建 EIP-3009 参数并签名

构建 TransferWithAuthorization 消息并使用 eth_signTypedData_v4 进行签名。关键字段：

EIP-712 域：查询代币合约的 name()、version（通常为 "1" 或 "2"）、来自 CAIP-2 网络的 chainId，以及 verifyingContract = option.asset。

使用 ethers.js 签名：

const wallet = new ethers.Wallet('<PRIVATE_KEY>');
const signature = await wallet.signTypedData(domain, types, message);

有关完整的类型化数据规范，请参阅 EIP-3009。domain.name/version 因代币而异（例如 USDC 使用 "USD Coin" / "2"）—— 请查询合约以确认。

步骤 3：组装标头并重放

与主流程步骤 5 相同 —— 从签名字段构建 authorization，根据 x402Version 确定标头名称，组装 paymentPayload = { ...decoded, payload: { signature, authorization } }，进行 base64 编码，并使用附加的支付标头重放原始请求。

本地签名的重要说明

• 私钥永远不会离开本地机器 —— 签名完全在离线状态下完成
• nonce 必须是随机的 32 字节十六进制值；重复使用 nonce 将导致交易被拒绝
• validBefore 是 Unix 时间戳（秒） —— 将其设置为 now + maxTimeoutSeconds（默认 300 秒 / 5 分钟）
• 如果代币使用非标准的 EIP-712 域（例如，不同的 version 字符串），签名将无效 —— 始终先查询合约
• 已签名的授权仅授权确切的 (from, to, value, nonce) 元组 —— 不能修改或重用

边缘情况

• 未登录：询问用户是否要创建钱包（onchainos wallet login 或 onchainos wallet login <email>）。如果否，则引导他们完成上述本地签名后备方案
• 不支持的网络：仅支持 CAIP-2 格式为 eip155:<chainId> 的 EVM 链
• 链上没有钱包：登录账户必须在请求的链上拥有地址；如果没有，则通知用户
• 金额单位错误：--amount 必须是最小单位 —— 提醒用户转换（例如，对于 6 位小数的代币，1 USDG = 1000000）
• 授权已过期：如果服务器拒绝支付为已过期，请使用新签名重试
• 网络错误：重试一次，然后提示用户稍后重试

金额显示规则

• --amount 始终是最小单位（例如，1 USDG 为 1000000）
• 向用户显示时，转换为 UI 单位：除以 10^decimal
• 同时显示代币符号（例如 1.00 USDG）

全局说明

• 主要路径（onchainos payment x402-pay）：需要经过身份验证的 JWT 会话；签名在 TEE 内部执行 —— 私钥永远不会离开安全飞地
• 后备路径（本地签名）：需要用户自己的私钥；签名完全在本地机器上完成 —— 不需要 JWT 或 TEE
• 此技能仅签名 —— 它不会广播或直接扣除余额；当接收方在链上兑现授权时，支付才会结算
• --network 必须是 CAIP-2 格式：eip155:<chainId>（例如 eip155:1、eip155:8453、eip155:196）
• 在构建支付标头时，返回的 authorization 对象必须与 signature 一起包含