TRON 代理的 x402 支付协议

调用支持 x402 的 AI 代理端点，并在 TRON 上自动完成 TRC20 代币支付。 目前推荐的代币：USDT、USDD。

快速开始

工具x402_tron_invoke由编译后的脚本dist/x402_tron_invoke.js实现。

该脚本已预先构建完成，可直接运行。您可以从命令行直接执行：

# v2 Invoke
node dist/x402_tron_invoke.js --url https://api.example.com --entrypoint chat --input '{"prompt": "hi"}'

# Direct/Discovery
node dist/x402_tron_invoke.js --url https://api.example.com/.well-known/agent.json

工作原理

工具x402_tron_invoke：

1. 构建端点 URL：
   • 如果提供了entrypoint：{url}/entrypoints/{entrypoint}/invoke(v2)
   • 否则：直接使用{url}（v1版 / 发现）
2. 发起请求（v2版使用POST，v1版默认使用GET）
3. 如果返回402付款要求：
   • 解析付款要求
   • 检查钱包余额和授权额度
   • 执行无限授权如果授权额度不足
   • 签署付款许可（EIP-712 / TRON 类型化数据）
   • 使用X-PAYMENT头部
4. 重试请求

返回响应

• 前提条件钱包
  1. ：必须有一个TRON私钥可用。该技能会自动在以下位置查找：TRON_PRIVATE_KEY
  2. 环境变量。~/.mcporter/mcporter.json
  3. x402-config.json位于当前/主目录。
• 代币：钱包需要 USDT/USDD 以及一些 TRX 作为燃料费。
• TronGrid API 密钥：主网需要，以避免速率限制（TRON_GRID_API_KEY）。工具参考x402_tron_invoke

调用一个具有自动支付处理功能的 HTTP 端点。

模式：

v2 代理调用

（推荐）：提供

1. url（基础 URL）+entrypoint。构建：{url}/entrypoints/{entrypoint}/invoke
   • 包装输入：{"input": <input>}
   • Wraps input:{"input": <input>}
   • 方法：POST
2. v1 / 直接 / 发现：提供url（完整URL），无需入口点。
   • 直接使用该URL。
   • 方法：GET（默认）或通过method指定。
   • 代理建议：将此模式用于发现。如果url返回404，请尝试附加/.well-known/agent.json或/entrypoints。
3. 状态检查：提供--check或--status.
   • 验证TRON_PRIVATE_KEY是否正确配置，并输出关联的钱包地址。
   • 检查TRON_GRID_API_KEY是否存在（主网必需）。
   • 代理建议：务必使用此命令，而非env或echo $TRON_PRIVATE_KEY。

示例：与代理聊天（v2 调用）

node dist/x402_tron_invoke.js --url https://api.example.com --entrypoint chat --input '{"prompt": "Tell me a joke"}'

（发送POST https://api.example.com/entrypoints/chat/invoke）

示例：代理发现（直接）

1. 清单：获取代理元数据。

   node dist/x402_tron_invoke.js --url https://api.example.com/.well-known/agent.json
   

2. 列出入口点：列出可用功能。

   node dist/x402_tron_invoke.js --url https://api.example.com/entrypoints
   

   每个入口点通常返回：

   • 路径：/entrypoints/{name}/invoke
   • 定价：代币成本（例如，1000单位）
   • 网络：通常是尼罗河或主网
   • 输入模式：预期的JSON格式用于输入参数

示例：原始URL（旧版）

node dist/x402_tron_invoke.js --url https://api.example.com/chat --method POST --input '{"prompt": "Tell me a joke"}'

成本参考（USDT/USDD）

理解402响应

当需要支付时，代理会返回：

{
  "error": "X-PAYMENT header is required",
  "accepts": [{
    "scheme": "exact",
    "network": "nile",
    "maxAmountRequired": "1000",
    "payTo": "T...",
    "asset": "T..."
  }],
  "x402Version": 1
}

该工具会自动处理此情况。

支持的代币

本工具支持兼容x402协议的TRC20代币。推荐使用：

• USDT（泰达币）
• USDD（去中心化美元）

代理安全规则

• 禁止输出私钥：代理不得在对话上下文中打印、回显或输出TRON_PRIVATE_KEY或任何其他签名密钥。
• 仅限内部加载：代理应依赖技能或底层脚本在内部加载密钥。
• 禁止导出命令：代理不得执行包含私钥作为字面字符串的shell命令。
• 日志脱敏：确保日志或错误消息不会泄露密钥。
• 静默环境检查：如果需要验证环境变量是否已设置，请使用“静默检查”。
  • 正确示例：[[ -n $TRON_PRIVATE_KEY ]] && echo "已配置" || echo "缺失"
  • 禁止示例：echo $TRON_PRIVATE_KEY,env,printenv,set,export.
• 禁用命令列表：在任何包含敏感密钥的环境中，请勿使用以下命令：
  • env/printenv
  • echo $VARIABLE_NAME
  • set/export（不带参数）
• 使用检查工具：要安全地验证钱包状态，请使用node dist/x402_tron_invoke.js --check.

❌ 反面示例（严重失败）

"我现在要检查你的私钥：echo $TRON_PRIVATE_KEY" ->停止！这会导致密钥泄露到日志和用户界面中。

✅ 正面示例

"我将验证钱包配置：node dist/x402_tron_invoke.js --check" ->安全。仅显示公共地址。

故障排除

"未找到私钥"

请确保TRON_PRIVATE_KEY环境变量已设置，或在预期路径中存在有效的x402-config.json配置文件。

"授权额度不足"

该工具将尝试广播一个无限授权交易。这需要TRX作为燃料费。请确保你的钱包中有TRX。

"交易失败"

检查您是否有足够的代币余额（USDT/USDD）以及用于Gas费的TRX。

二进制与图像处理

若端点返回图像（内容类型：image/*）或二进制数据（application/octet-stream）：

1. 数据将自动保存至临时文件（例如：/tmp/x402_image_...）。
2. 工具会返回包含以下字段的JSON对象：
   • file_path：临时文件的路径。
   • content_type：内容的MIME类型。
   • bytes：文件大小（字节）。
3. 重要提示：代理在使用后需负责删除临时文件。

网络参考