x402-payment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

x402 Payment Skill

x402 支付 Skill

Invoke x402-enabled AI agent endpoints with automatic token payments on both TRON (TRC20) and EVM-compatible (ERC20) chains.

在TRON（TRC20）和兼容EVM（ERC20）的链上，通过自动代币支付调用支持x402的AI Agent端点。

Overview

概述

The

x402-payment

skill enables agents to interact with paid API endpoints. When an agent receives a

402 Payment Required

response, this skill handles the negotiation, signing, and execution of the payment using the

x402_invoke

tool.

x402-payment

skill 允许Agent与付费API端点交互。当Agent收到

402 Payment Required

（需要支付）响应时，该skill会通过

x402_invoke

工具处理协商、签名和支付执行流程。

Prerequisites

前置条件

Wallet Configuration (agent-wallet):
- Local mode (recommended): set
```
AGENT_WALLET_PASSWORD
```
  (required),
```
AGENT_WALLET_DIR
```
  (optional).
- Static mode (env): set exactly one of
```
AGENT_WALLET_PRIVATE_KEY
```
  /
```
AGENT_WALLET_MNEMONIC
```
  .
- Optional for mnemonic mode:
```
AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX
```
  .
- Configure a TRON wallet for TRC20 payments (USDT/USDD) and/or an EVM wallet for ERC20 payments (USDT/USDC).
TronGrid API Key (optional):
```
TRON_GRID_API_KEY
```
is optional. Recommended on Mainnet to reduce rate-limit issues.
GasFree (optional):
```
GASFREE_API_KEY
```
and
```
GASFREE_API_SECRET
```
are only needed when using GasFree-related commands/flows. When configured, the tool will prefer the
```
exact_gasfree
```
scheme over
```
exact_permit
```
. GasFree also requires an account that is activated with sufficient token balance in the GasFree wallet.
Dependencies: Run
```
npm install
```
in the
```
x402-payment/
```
directory before first use.

TRON_GRID_API_KEY

GASFREE_API_KEY

, and

GASFREE_API_SECRET

can also be set in

x402-config.json

钱包配置（agent-wallet）:
- 本地模式（推荐）: 设置
```
AGENT_WALLET_PASSWORD
```
  （必填）、
```
AGENT_WALLET_DIR
```
  （可选）。
- 静态模式（环境变量）: 必须设置
```
AGENT_WALLET_PRIVATE_KEY
```
  /
```
AGENT_WALLET_MNEMONIC
```
  中的其中一个。
- 助记词模式可选配置:
```
AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX
```
  。
- 为TRC20支付（USDT/USDD）配置TRON钱包，和/或为ERC20支付（USDT/USDC）配置EVM钱包。
TronGrid API密钥（可选）:
```
TRON_GRID_API_KEY
```
为可选配置。在主网中推荐配置，以减少请求频率限制问题。
GasFree（可选）: 仅在使用GasFree相关命令/流程时需要
```
GASFREE_API_KEY
```
和
```
GASFREE_API_SECRET
```
。配置后，工具会优先使用
```
exact_gasfree
```
方案而非
```
exact_permit
```
。GasFree还要求账户已激活且GasFree钱包中有足够的代币余额。
依赖安装: 首次使用前，在
```
x402-payment/
```
目录下运行
```
npm install
```
。

TRON_GRID_API_KEY

、

GASFREE_API_KEY

和

GASFREE_API_SECRET

也可在

x402-config.json

中设置。

Usage Instructions

使用说明

1. Verification

1. 验证

Before making payments, verify your wallet status:

bash

npx tsx x402-payment/src/x402_invoke.ts --check

在支付前，先验证钱包状态：

bash

npx tsx x402-payment/src/x402_invoke.ts --check

2. Invoking an Agent (v2)

2. 调用Agent（v2版本）

Most modern x402 agents use the v2 "invoke" pattern:

bash

npx tsx x402-payment/src/x402_invoke.ts \
  --url https://api.example.com \
  --entrypoint chat \
  --input '{"prompt": "Your query here"}' \
  --network nile

大多数现代x402 Agent采用v2版本的"invoke"调用模式：

bash

npx tsx x402-payment/src/x402_invoke.ts \
  --url https://api.example.com \
  --entrypoint chat \
  --input '{"prompt": "Your query here"}' \
  --network nile

3. Agent Discovery (Direct)

3. Agent 发现（直接方式）

Manifest: Fetch agent metadata.

bash

npx tsx x402-payment/src/x402_invoke.ts --url https://api.example.com/.well-known/agent.json

List Entrypoints: List available functions.

bash

npx tsx x402-payment/src/x402_invoke.ts --url https://api.example.com/entrypoints

清单文件: 获取Agent元数据。

bash

npx tsx x402-payment/src/x402_invoke.ts --url https://api.example.com/.well-known/agent.json

列出入口点: 查看可用功能。

bash

npx tsx x402-payment/src/x402_invoke.ts --url https://api.example.com/entrypoints

4. GasFree Wallet Info

4. GasFree 钱包信息

Query GasFree wallet information (address, activation status, balance, nonce). Defaults: network=mainnet, wallet=agent-wallet active TRON wallet.

bash

undefined

查询GasFree钱包信息（地址、激活状态、余额、随机数）。默认配置：网络=主网，钱包=agent-wallet中激活的TRON钱包。

bash

undefined

Default: mainnet + active TRON wallet

默认：主网 + 激活的TRON钱包

npx tsx x402-payment/src/x402_invoke.ts --gasfree-info

Specify wallet address

指定钱包地址

npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --wallet <YOUR_WALLET_ADDRESS>

Specify network

指定网络

npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --network nile

Both

同时指定两者

npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --wallet <YOUR_WALLET_ADDRESS> --network nile

Requires: `GASFREE_API_KEY`, `GASFREE_API_SECRET`. Without `--wallet`, requires a configured TRON wallet from agent-wallet. Returns JSON with `gasFreeAddress`, `active`, `allowSubmit`, `nonce`, and per-token `assets` (balance, fees).

npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --wallet <YOUR_WALLET_ADDRESS> --network nile

依赖要求：`GASFREE_API_KEY`、`GASFREE_API_SECRET`。如果未指定`--wallet`，则需要在agent-wallet中配置TRON钱包。返回包含`gasFreeAddress`、`active`、`allowSubmit`、`nonce`以及各代币`assets`（余额、手续费）的JSON数据。

5. GasFree Account Activation

5. GasFree 账户激活

Activate a GasFree account that has not been activated yet. Use

--gasfree-info

first to check activation status. Defaults: network=nile, token=USDT.

bash

undefined

激活尚未激活的GasFree账户。请先使用

--gasfree-info

检查激活状态。默认配置：网络=nile测试网，代币=USDT。

bash

undefined

Default: nile + USDT

默认：nile测试网 + USDT

npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate

Specify network

指定网络

npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network mainnet

Specify network and token

指定网络和代币

npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --token USDT

Requires: TRON wallet configured in agent-wallet, `GASFREE_API_KEY`, `GASFREE_API_SECRET`. Wallet must have enough tokens to cover activation fees (~3.05 USDT on nile). If the account is already activated, returns `{"status": "already_active"}` immediately.

**Activation process:**
1. Queries GasFree account info and checks activation status
2. Transfers `activateFee + transferFee + 1 token` from wallet to gasFreeAddress (on-chain TRC20)
3. Polls for on-chain confirmation (up to 60s)
4. Submits a GasFree signed transaction to transfer tokens back to wallet (triggers activation)
5. Polls until the GasFree transaction completes

Returns JSON with `status`, `depositTxId`, `gasFreeTraceId`, `gasFreeState`, `gasFreeTxHash`, and final `active` status.

npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --token USDT

依赖要求：agent-wallet中已配置TRON钱包，且拥有`GASFREE_API_KEY`、`GASFREE_API_SECRET`。钱包中必须有足够代币覆盖激活手续费（nile测试网约3.05 USDT）。如果账户已激活，会立即返回`{"status": "already_active"}`。

**激活流程：**
1. 查询GasFree账户信息并检查激活状态
2. 从钱包向gasFreeAddress转账`activateFee + transferFee + 1个代币`（链上TRC20转账）
3. 轮询等待链上确认（最多60秒）
4. 提交GasFree签名交易，将代币转回钱包（触发激活）
5. 轮询直到GasFree交易完成

返回包含`status`、`depositTxId`、`gasFreeTraceId`、`gasFreeState`、`gasFreeTxHash`以及最终`active`状态的JSON数据。

6. Cross-Chain Support

6. 跨链支持

TRON (TRC20): Use
```
--network nile
```
(testnet) or
```
mainnet
```
.
BSC (ERC20): Use
```
--network bsc-testnet
```
(testnet) or
```
bsc
```
(mainnet).

TRON（TRC20）: 使用
```
--network nile
```
（测试网）或
```
mainnet
```
（主网）。
BSC（ERC20）: 使用
```
--network bsc-testnet
```
（测试网）或
```
bsc
```
（主网）。

Supported Networks & Tokens

支持的网络与代币

Chain	Network Name	Common Tokens	USDT Contract
TRON	`mainnet`	USDT, USDD	`TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`
TRON	`nile`	USDT, USDD	`TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`
BSC	`bsc`	USDT, USDC	`0x55d398326f99059fF775485246999027B3197955`
BSC	`bsc-testnet`	USDT, USDC, DHLU	`0x337610d27c682E347C9cD60BD4b3b107C9d34dDd`

链	网络名称	常用代币	USDT合约地址
TRON	`mainnet`	USDT, USDD	`TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`
TRON	`nile`	USDT, USDD	`TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`
BSC	`bsc`	USDT, USDC	`0x55d398326f99059fF775485246999027B3197955`
BSC	`bsc-testnet`	USDT, USDC, DHLU	`0x337610d27c682E347C9cD60BD4b3b107C9d34dDd`

Security Considerations & Rules

安全注意事项与规则

[!CAUTION] Wallet Secret Safety: NEVER output wallet private keys or mnemonic phrases to logs or console. Use agent-wallet managed configuration.

[!CAUTION] 钱包密钥安全: 绝对不要将钱包私钥或助记词输出到日志或控制台。请使用agent-wallet托管配置。

Agent Security Rules:

Agent安全规则:

No Private Key Output: The Agent MUST NOT print, echo, or output any private key to the dialogue context.
No Mnemonic Output: The Agent MUST NOT print or expose mnemonic phrases.
Internal Loading Only: Rely on the tool to load wallet credentials internally via agent-wallet.
No Export Commands: DO NOT execute shell commands containing the private key as a literal string.
Silent Environment Checks: Use
```
[[ -n $AGENT_WALLET_PASSWORD ]] && echo "Configured" || echo "Missing"
```
to verify local mode configuration without leaking secrets.
Use the Check Tool: Use
```
npx tsx x402-payment/src/x402_invoke.ts --check
```
to safely verify addresses.

禁止输出私钥: Agent不得在对话上下文里打印、回显或输出任何私钥。
禁止输出助记词: Agent不得打印或泄露助记词。
仅内部加载: 依赖工具通过agent-wallet内部加载钱包凭证。
禁止导出命令: 不要执行包含明文私钥的shell命令。
静默环境检查: 使用
```
[[ -n $AGENT_WALLET_PASSWORD ]] && echo "Configured" || echo "Missing"
```
来验证本地模式配置，避免泄露敏感信息。

使用检查工具: 使用

npx tsx x402-payment/src/x402_invoke.ts --check

安全验证地址。

Binary and Image Handling

二进制与图片处理

If the endpoint returns an image or binary data:

The data is saved to a temporary file (e.g.,
```
/tmp/x402_image_...
```
).
The tool returns JSON with
```
file_path
```
,
```
content_type
```
, and
```
bytes
```
.
Important: The Agent is responsible for deleting the temporary file after use.

如果端点返回图片或二进制数据：

数据会保存到临时文件（例如：
```
/tmp/x402_image_...
```
）。
工具会返回包含
```
file_path
```
、
```
content_type
```
和
```
bytes
```
的JSON数据。
重要提示: Agent需负责在使用后删除临时文件。

Error Handling

错误处理

Insufficient Allowance

授权额度不足

If allowance is insufficient, the tool will automatically attempt an "infinite approval" transaction. Ensure you have native tokens (TRX or BNB/ETH) for gas.

如果授权额度不足，工具会自动尝试发起"无限授权"交易。请确保钱包中有足够的原生代币（TRX或BNB/ETH）用于支付Gas费。

Insufficient Balance

余额不足

Ensure you have enough USDT/USDC/USDD in your wallet on the specified network.

请确保指定网络的钱包中有足够的USDT/USDC/USDD代币。

Debug Stack Trace

调试堆栈跟踪

Set

X402_DEBUG=1

to include full error stack traces in the JSON output when troubleshooting failures.

Last Updated: 2026-03-11

设置

X402_DEBUG=1

，在排查故障时可在JSON输出中包含完整的错误堆栈信息。

最后更新时间: 2026-03-11