介绍
# x402 Payment Protocol for TRON Agents
调用启用 x402 的 AI 智能体端点，并在 TRON 上自动完成 USDT 微支付。
## 快速开始
### 选项 1：运行预构建版本（推荐用于智能体） 该技能已预打包为单个文件。无需安装。 ```bash node dist/index.js --url <URL> [options] ```
### 选项 2：开发 ```bash npm install npm start -- --url <URL> ```
## 工具参考
- **钱包**: 必须提供 TRON 私钥。该技能会自动在以下位置查找： 1. `TRON_PRIVATE_KEY` 环境变量。 2. `~/.mcporter/mcporter.json` (AIBank 标准配置)。 3. 当前目录下的 `x402-config.json`。 4. 主目录下的 `~/.x402-config.json`。 - **TRON 上的 USDT**: 钱包需要持有 USDT 以及用于支付 Gas 费的少量 TRX。
---
## 工具参考
### x402_tron_invoke
调用 HTTP 端点。如果需要付款 (402)，它将自动执行以下操作： 1. 协商支付要求。 2. 检查 USDT 授权额度。如果不足，它将执行**无限授权** (MAX_UINT256) 以最大程度减少未来的交易。 3. 签署支付许可 (EIP-712)。 4. 使用支付签名重试请求。
| 参数 | 类型 | 必填 | 描述 | |-----------|------|----------|-------------| | `url` | string | 是 | 要调用的完整 URL | | `method` | string | 否 | HTTP 方法 (GET, POST 等) 默认值：GET | | `body` | object | 否 | 请求的 JSON 主体 | | `network` | string | 否 | `mainnet`, `nile`, `shasta` (默认值：`nile`) |
### 示例：与智能体对话
```tool:x402_tron_invoke url: https://api.example.com/chat method: POST body: {"prompt": "Tell me a joke"} ```
---
## 智能体发现
您可以通过检查智能体的清单来发现可用的端点及其定价。
### 获取智能体清单
```tool:x402_tron_invoke url: https://api.example.com/.well-known/agent.json method: GET ```
---
## 智能体安全规则
- **禁止输出私钥**: 智能体绝不能打印、回显或输出 `TRON_PRIVATE_KEY` 或任何其他签名机密到对话上下文中。 - **仅供内部加载**: 智能体应依赖该技能或底层脚本在内部加载密钥。 - **禁止导出命令**: 智能体绝不能执行将私钥作为字符串字面量的 Shell 命令（例如 `export TRON_PRIVATE_KEY=...`）。 - **清理日志**: 确保日志或错误消息不会泄露密钥。
## 故障排除
### "Private key not found" (未找到私钥) 确保已设置 `TRON_PRIVATE_KEY` 环境变量，或在预期位置存在有效的 `x402-config.json`。 **智能体注意**: 如果发生此错误，只需告知用户环境未配置。切勿尝试自行搜索或读取文件中的私钥。
### "Insufficient Allowance" (授权额度不足) 该工具将尝试广播**无限授权** 交易。这需要 TRX 作为 Gas 费。请确保您的钱包中有 TRX。
### "Transaction Failed" (交易失败) 请检查您是否有足够的 USDT 和 TRX。
---
## 二进制文件和图像处理
如果端点返回图像 (Content-Type: `image/*`) 或二进制数据 (`application/octet-stream`)： 1. 数据将自动保存到临时文件（例如 `/tmp/x402_image_...` 或 `/tmp/x402_binary_...`）。 2. 该工具返回一个 JSON 对象，包含： - `file_path`: 临时文件的路径。 - `content_type`: 内容的 MIME 类型。 - `bytes`: 文件大小（字节）。 3. **重要**: 智能体负责在使用或处理完临时文件后将其删除。
---
## 网络参考
| 网络 | Chain ID | CAIP-2 | USDT 合约 | |---------|----------|--------|---------------| | TRON Mainnet | 0x2b6653dc | `eip155:728126428`, `tron:mainnet` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | | TRON Nile | 0xcd8690dc | `eip155:3448148188`, `tron:nile` | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | | TRON Shasta | 0x94a9059e | `eip155:2494104990`, `tron:shasta` | - |