介绍
# x402 Payment Protocol for TRON Agents
调用支持 x402 的 AI 代理端点，并在 TRON 上自动进行 TRC20 代币支付。 当前推荐的代币：**USDT**、**USDD**。
## 快速开始
工具 `x402_tron_invoke` 由编译脚本 `dist/x402_tron_invoke.js` 实现。
该脚本已预构建并可随时运行。您可以直接从命令行执行它：
```bash # 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 Payment Required： - 解析支付要求 - 检查钱包余额和授权额度 - 如果授权额度不足，执行**无限授权** - 签署支付许可（EIP-712 / TRON Typed Data） - 使用 `X-PAYMENT` 请求头重试请求 4. 返回响应
## 前置条件
- **钱包**：必须有一个 TRON 私钥。该技能会自动在以下位置查找： 1. `TRON_PRIVATE_KEY` 环境变量。 2. `~/.mcporter/mcporter.json` (AIBank 标准)。 3. 当前目录或主目录下的 `x402-config.json`。 - **代币**：钱包需要 USDT/USDD 以及一些用于支付 Gas 费的 TRX。 - **TronGrid API 密钥**：**主网** 必需，以避免速率限制 (`TRON_GRID_API_KEY`)。
---
## 工具参考
### x402_tron_invoke
调用 HTTP 端点并自动处理支付。
**模式：** 1. **v2 代理调用**（推荐）：提供 `url`（基础 URL） + `entrypoint`。 * 构建为：`{url}/entrypoints/{entrypoint}/invoke` * 封装输入：`{"input": <input>}` * 方法：`POST` 2. **v1 / 直连 / 发现**：提供 `url`（完整 URL）且不提供 `entrypoint`。 * 直接使用该 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`。
| 参数 | 类型 | 必填 | 描述 | |-----------|------|----------|-------------| | `url` | string | 是* | 基础 URL (v2) 或完整 URL (v1/Discovery)。*进行 `--check` 时不需要。 | | `entrypoint` | string | 否 | 入口点名称。v2 调用所必需。 | | `input` | object | 否 | 输入数据。 | | `method` | string | 否 | HTTP 方法。默认：`POST` (v2)，`GET` (直连)。 | | `network` | string | 否 | `mainnet`、`nile`、`shasta` (默认：`nile`)。 | | `check` | boolean | 否 | 验证钱包配置并输出地址。 |
### 示例：与代理对话 (v2 调用)
```bash 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. **清单 (Manifest)**：获取代理元数据。 ```bash node dist/x402_tron_invoke.js --url https://api.example.com/.well-known/agent.json ```
2. **列出入口点**：列出可用函数。 ```bash node dist/x402_tron_invoke.js --url https://api.example.com/entrypoints ``` 每个入口点通常返回： - **路径**：`/entrypoints/{name}/invoke` - **定价**：代币成本（例如 1000 单位） - **网络**：通常是 `nile` 或 `mainnet` - **输入模式**：`input` 参数预期的 JSON 格式
### 示例：原始 URL (旧版)
```bash node dist/x402_tron_invoke.js --url https://api.example.com/chat --method POST --input '{"prompt": "Tell me a joke"}' ```
---
## 费用参考 (USDT/USDD)
| 代币 | 网络 | 合约地址 | 精度 | |-------|---------|------------------|----------| | USDT | Mainnet | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | USDT | Nile | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | 6 | | USDT | Shasta | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` | 6 | | USDD | Mainnet | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | USDD | Nile | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` | 18 |
| 数量 (原始值) | 价值 (USDT, 6 位小数) | 典型用途 | |--------------|---------------------|-------------| | 1000 | $0.001 | 单次 API 调用 | | 5000 | $0.005 | 多个结果 | | 10000 | $0.01 | 高级请求 | | 1000000 | $1.00 | 大批量 |
---
## 理解 402 响应
当需要付款时，代理返回：
```json { "error": "X-PAYMENT header is required", "accepts": [{ "scheme": "exact", "network": "nile", "maxAmountRequired": "1000", "payTo": "T...", "asset": "T..." }], "x402Version": 1 } ```
该工具会自动处理此情况。
---
## 支持的代币
此工具支持与 x402 协议兼容的 TRC20 代币。 **推荐：** - **USDT** (Tether) - **USDD** (去中心化 USD)
## 代理的安全规则
- **禁止输出私钥**：代理**严禁**在对话上下文中打印、回显或输出 `TRON_PRIVATE_KEY` 或任何其他签名密钥。 - **仅限内部加载**：代理应依赖该技能或底层脚本来在内部加载密钥。 - **禁止导出命令**：代理**严禁**执行包含私钥作为字面字符串的 shell 命令。 - **清理日志**：确保日志或错误消息不会泄露密钥。 - **静默环境检查**：如果您需要验证环境变量是否已设置，请使用“静默检查”。 - **正确**：`[[ -n $TRON_PRIVATE_KEY ]] && echo "Configured" || echo "Missing"` - **禁止**：`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`” -> **停止！这会将密钥泄露到日志和 UI 中。**
### ✅ 正面示例 > “我将验证钱包配置：`node dist/x402_tron_invoke.js --check`” -> **安全。仅显示公共地址。**
## 故障排除
### “Private key not found” (未找到私钥) 请确保已设置 `TRON_PRIVATE_KEY` 环境变量，或者在预期位置存在有效的 `x402-config.json`。
### “Insufficient Allowance” (授权额度不足) 该工具将尝试广播**无限授权** 交易。这需要 TRX 作为 Gas 费。请确保您的钱包中有 TRX。
### “Transaction Failed” (交易失败) 检查您是否有足够的代币余额 (USDT/USDD) 和用于 Gas 费的 TRX。
---
## 二进制和图像处理
如果端点返回图像（Content-Type: `image/*`）或二进制数据（`application/octet-stream`）： 1. 数据会自动保存到临时文件（例如 `/tmp/x402_image_...`）。 2. 该工具返回一个 JSON 对象，其中包含： - `file_path`：临时文件的路径。 - `content_type`：内容的 MIME 类型。 - `bytes`：文件大小（字节）。 3. **重要**：代理负责在使用完毕后删除该临时文件。
---
## 网络参考
| 网络 | 链 ID | CAIP-2 | USDT 合约 | USDD 合约 | |---------|----------|--------|---------------|---------------| | TRON Mainnet | 0x2b6653dc | `eip155:728126428`, `tron:mainnet` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | | TRON Nile | 0xcd8690dc | `eip155:3448148188`, `tron:nile` | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` | | TRON Shasta | 0x94a9059e | `eip155:2494104990`, `tron:shasta` | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` | - |