x402 Payment Protocol for TRON Agents

Invoke x402-enabled AI agent endpoints with automatic TRC20 token payments on TRON.
Currently recommended tokens: USDT, USDD.

Quick Start

The tool x402_tron_invoke is implemented by the compiled script dist/x402_tron_invoke.js.

The script is pre-built and ready to run. You can execute it directly from the command line:

CODEBLOCK0

How It Works

The x402_tron_invoke tool:

1. Constructs the endpoint URL:

- If entrypoint is provided: {url}/entrypoints/{entrypoint}/invoke (v2) - Otherwise: Uses {url} as-is (v1 / Discovery)

2. Makes a request (POST for v2, GET default for v1)
If 402 Payment Required is returned:

- Parses payment requirements - Checks wallet balance and allowance - Performs an infinite approval if allowance is insufficient - Signs the payment permit (EIP-712 / TRON Typed Data) - Retries the request with X-PAYMENT header

4. Returns the response

Prerequisites

- Wallet: A TRON private key must be available. The skill automatically looks for it in:

1. TRON_PRIVATE_KEY environment variable. 2. ~/.mcporter/mcporter.json (AIBank standard). 3. x402-config.json in the current/home directory.

- Tokens: Wallet needs USDT/USDD and some TRX for gas.
TronGrid API Key: Required for Mainnet to avoid rate limits (TRON_GRID_API_KEY).

Tool Reference

x402troninvoke

Invokes an HTTP endpoint with automatic payment handling.

Modes:

1. v2 Agent Invoke (Recommended): Provide url (Base URL) + entrypoint.

* Constructs: {url}/entrypoints/{entrypoint}/invoke
* Wraps input: {"input": <input>}
* Method: POST

2. v1 / Direct / Discovery: Provide url (Full URL) without entrypoint.

* Uses the URL as-is.
* Method: GET (default) or specified via method.
* Agent Advice: Use this mode for discovery. If url returns 404, try appending /.well-known/agent.json or /entrypoints.

3. Status Check: Provide --check or --status.

* Verifies if TRON_PRIVATE_KEY is correctly configured and outputs the associated wallet address.
* Checks if TRON_GRID_API_KEY is present (Required for Mainnet).
* Agent Advice: ALWAYS use this instead of env or echo $TRON_PRIVATE_KEY.

Parameter	Type	Required	Description
INLINECODE29	string	Yes	Base URL (v2) or Full URL (v1/Discovery). Not required for `--check`.
INLINECODE31

Example: Chat with Agent (v2 Invoke)

CODEBLOCK1
(Sends POST https://api.example.com/entrypoints/chat/invoke)

Example: Agent Discovery (Direct)

1. Manifest: Fetch agent metadata.

CODEBLOCK2

2. List Entrypoints: List available functions.

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

Each entrypoint typically returns: - Path: /entrypoints/{name}/invoke - Pricing: Cost in tokens (e.g., 1000 units) - Network: Usually nile or mainnet - Input Schema: Expected JSON format for the input parameter

Example: Raw URL (Legacy)

CODEBLOCK4

Cost Reference (USDT/USDD)

Token	Network	Contract Address	Decimals
USDT	Mainnet	INLINECODE47	6
USDT

Amount (raw)	Value (USDT, 6 dec)	Typical Use
1000	$0.001	Single API call
5000

$0.005 | Multiple results |
| 10000 | $0.01 | Premium request |
| 1000000 | $1.00 | Large batch |

Understanding 402 Responses

When payment is required, agents return:

CODEBLOCK5

The tool handles this automatically.

Supported Tokens

This tool supports TRC20 tokens compatible with the x402 protocol.
Recommended:

- USDT (Tether)
USDD (Decentralized USD)

Security Rules for Agents

- No Private Key Output: The Agent MUST NOT print, echo, or output the TRON_PRIVATE_KEY or any other signing secret to the dialogue context.
Internal Loading Only: The Agent should rely on the skill or underlying scripts to load the key internally.
No Export Commands: The Agent MUST NOT execute shell commands that contain the private key as a literal string.
Sanitized Logs: Ensure that logs or error messages do not leak the key.
Silent Environment Checks: If you need to verify if an environment variable is set, use a "Silent Check".

- Correct: [[ -n $TRON_PRIVATE_KEY ]] && echo "Configured" || echo "Missing" - Forbidden: echo $TRON_PRIVATE_KEY, env, printenv, set, export.

- Disabled Commands List: Do NOT use the following commands in any environment containing sensitive keys:

- env / printenv - echo $VARIABLE_NAME - set / export (without arguments)

- Use the Check Tool: To safely verify wallet status, use node dist/x402_tron_invoke.js --check.

❌ Negative Example (CRITICAL FAILURE)

"I will check your private key now: echo $TRON_PRIVATE_KEY" -> STOP! This leaks the secret to the logs and UI.

✅ Positive Example

"I will verify the wallet configuration: node dist/x402_tron_invoke.js --check" -> SAFE. Only the public address is shown.

Troubleshooting

"Private key not found"

Ensure the TRON_PRIVATE_KEY environment variable is set or a valid x402-config.json exists in the expected locations.

"Insufficient Allowance"

The tool will attempt to broadcast an infinite approve transaction. This requires TRX for gas. Ensure your wallet has TRX.

"Transaction Failed"

Check if you have enough Token balance (USDT/USDD) and TRX for gas.

Binary and Image Handling

If the endpoint returns an image (Content-Type: image/*) or binary data (application/octet-stream):

1. The data is automatically saved to a temporary file (e.g., /tmp/x402_image_...).
The tool returns a JSON object with:

- file_path: Path to the temporary file.
- content_type: The MIME type of the content.
- bytes: File size in bytes.

3. Important: The Agent is responsible for deleting the temporary file after it has been used.

Network Reference

Network	Chain ID	CAIP-2	USDT Contract	USDD Contract
TRON Mainnet	0x2b6653dc	INLINECODE75, INLINECODE76	INLINECODE77	INLINECODE78
TRON Nile

TRON 代理的 x402 支付协议

在 TRON 网络上通过自动 TRC20 代币支付调用支持 x402 的 AI 代理端点。
当前推荐代币：USDT、USDD。

快速开始

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

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

bash

v2 调用

node dist/x402troninvoke.js --url https://api.example.com --entrypoint chat --input {prompt: hi}

直接/发现

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

工作原理

x402troninvoke 工具：

1. 构建端点 URL：

- 如果提供了 entrypoint：{url}/entrypoints/{entrypoint}/invoke（v2） - 否则：直接使用 {url}（v1 / 发现）

2. 发起请求（v2 为 POST，v1 默认为 GET）
如果返回 402 需要支付：

- 解析支付要求 - 检查钱包余额和授权额度 - 如果授权额度不足，执行无限授权 - 签署支付许可（EIP-712 / TRON 类型数据） - 使用 X-PAYMENT 标头重试请求

4. 返回响应

前置条件

- 钱包：必须提供 TRON 私钥。该技能会自动在以下位置查找：

1. TRONPRIVATEKEY 环境变量。 2. ~/.mcporter/mcporter.json（AIBank 标准）。 3. 当前/主目录下的 x402-config.json。

- 代币：钱包需要 USDT/USDD 以及用于燃料费的 TRX。
TronGrid API 密钥：主网需要此密钥以避免速率限制（TRONGRIDAPI_KEY）。

工具参考

x402troninvoke

调用 HTTP 端点并自动处理支付。

模式：

1. v2 代理调用（推荐）：提供 url（基础 URL）+ entrypoint。

* 构建：{url}/entrypoints/{entrypoint}/invoke
* 包装输入：{input: }
* 方法：POST

2. v1 / 直接 / 发现：提供 url（完整 URL），不提供 entrypoint。

* 直接使用该 URL。
* 方法：GET（默认）或通过 method 指定。
* 代理建议：使用此模式进行发现。如果 url 返回 404，请尝试附加 /.well-known/agent.json 或 /entrypoints。

3. 状态检查：提供 --check 或 --status。

* 验证 TRONPRIVATEKEY 是否正确配置并输出关联的钱包地址。
* 检查 TRONGRIDAPI_KEY 是否存在（主网必需）。
* 代理建议：始终使用此方法，而不是 env 或 echo $TRONPRIVATEKEY。

参数	类型	必需	描述
url	字符串	是	基础 URL（v2）或完整 URL（v1/发现）。--check 模式不需要。
entrypoint

字符串 | 否 | 入口点名称。v2 调用必需。 |
| input | 对象 | 否 | 输入数据。 |
| method | 字符串 | 否 | HTTP 方法。默认：POST（v2），GET（直接）。 |
| network | 字符串 | 否 | mainnet、nile、shasta（默认：nile）。 |
| check | 布尔值 | 否 | 验证钱包配置并输出地址。 |

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

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

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

示例：代理发现（直接）

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

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

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

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

每个入口点通常返回：
- 路径：/entrypoints/{name}/invoke
- 定价：代币成本（例如 1000 单位）
- 网络：通常为 nile 或 mainnet
- 输入模式：input 参数的预期 JSON 格式

示例：原始 URL（旧版）

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

费用参考（USDT/USDD）

代币	网络	合约地址	小数位
USDT	主网	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t	6
USDT

数量（原始）	价值（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（泰达币）
USDD（去中心化美元）

代理安全规则

- 不输出私钥：代理不得打印、回显或输出 TRONPRIVATEKEY 或任何其他签名密钥到对话上下文。
仅内部加载：代理应依赖技能或底层脚本在内部加载密钥。
不执行导出命令：代理不得执行包含私钥字面字符串的 shell 命令。
清理日志：确保日志或错误消息不泄露密钥。
静默环境检查：如果需要验证环境变量是否已设置，请使用静默检查。

- 正确：[[ -n $TRONPRIVATEKEY ]] && echo Configured || echo Missing - 禁止：echo $TRONPRIVATEKEY、env、printenv、set、export。

- 禁用命令列表：在任何包含敏感密钥的环境中，请勿使用以下命令：

- env / printenv - echo $VARIABLE_NAME - set / export（不带参数）

- 使用检查工具：要安全验证钱包状态，请使用 node dist/x402troninvoke.js --check。

❌ 负面示例（严重失败）

我现在检查您的私钥：echo $TRONPRIVATEKEY -> 停止！这会将密钥泄露到日志和 UI 中。

tron-x402-paymentTRON x402支付

tron-x402-payment

x402 Payment Protocol for TRON Agents

Quick Start

How It Works

Prerequisites

Tool Reference

x402troninvoke

Example: Chat with Agent (v2 Invoke)

Example: Agent Discovery (Direct)

Example: Raw URL (Legacy)

Cost Reference (USDT/USDD)

Understanding 402 Responses

Supported Tokens

Security Rules for Agents

❌ Negative Example (CRITICAL FAILURE)

✅ Positive Example

Troubleshooting

"Private key not found"

"Insufficient Allowance"

"Transaction Failed"

Binary and Image Handling

Network Reference

TRON 代理的 x402 支付协议

快速开始

v2 调用

直接/发现

工作原理

前置条件

工具参考

x402troninvoke

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

示例：代理发现（直接）

示例：原始 URL（旧版）

费用参考（USDT/USDD）

理解 402 响应

支持的代币

代理安全规则

❌ 负面示例（严重失败）

✅ 正面示例

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement