x402

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

x402 Skill

Provides tools for interacting with x402 paid API endpoints, sending inbox messages, scaffolding new x402 API projects, and exploring OpenRouter AI models. Payment flows are handled automatically using the configured wallet.

提供用于与x402付费API端点交互、发送收件箱消息、搭建新x402 API项目以及探索OpenRouter AI模型的工具。支付流程会通过已配置的钱包自动处理。

Usage

使用方法

bun run x402/x402.ts <subcommand> [options]

bun run x402/x402.ts <子命令> [选项]

Subcommands

子命令

list-endpoints

列出端点

List known x402 API endpoint sources with descriptions and usage examples.

bun run x402/x402.ts list-endpoints

Output:

json

{
  "network": "mainnet",
  "defaultApiUrl": "https://x402.biwas.xyz",
  "sources": [
    {
      "name": "x402.biwas.xyz",
      "url": "https://x402.biwas.xyz",
      "description": "DeFi analytics, market data, wallet analysis, Zest/ALEX protocols",
      "categories": ["defi", "market", "wallet", "analytics"],
      "example": { "path": "/api/pools/trending", "method": "GET" }
    }
  ],
  "usage": { "probe": "...", "execute": "..." }
}

列出已知的x402 API端点源，包含描述和使用示例。

bun run x402/x402.ts list-endpoints

输出:

json

{
  "network": "mainnet",
  "defaultApiUrl": "https://x402.biwas.xyz",
  "sources": [
    {
      "name": "x402.biwas.xyz",
      "url": "https://x402.biwas.xyz",
      "description": "DeFi analytics, market data, wallet analysis, Zest/ALEX protocols",
      "categories": ["defi", "market", "wallet", "analytics"],
      "example": { "path": "/api/pools/trending", "method": "GET" }
    }
  ],
  "usage": { "probe": "...", "execute": "..." }
}

probe-endpoint

探测端点

Probe an x402 API endpoint to discover its cost WITHOUT making payment.

bun run x402/x402.ts probe-endpoint --method GET --path /api/pools/trending
bun run x402/x402.ts probe-endpoint --method GET --url https://stx402.com/ai/dad-joke
bun run x402/x402.ts probe-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}'

Options:

```
--method
```
(optional) — HTTP method (default: GET)
```
--url
```
(optional) — Full endpoint URL. Takes precedence over
```
--path
```
.
```
--path
```
(optional) — API endpoint path. Required if
```
--url
```
not provided.
```
--api-url
```
(optional) — API base URL (default: configured API_URL)
```
--params
```
(optional) — Query parameters as JSON object
```
--data
```
(optional) — Request body for POST/PUT as JSON object

Output (free endpoint):

json

{
  "type": "free",
  "endpoint": "GET https://x402.biwas.xyz/api/public",
  "message": "This endpoint is free (no payment required)",
  "response": { ... }
}

Output (paid endpoint):

json

{
  "type": "payment_required",
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "message": "This endpoint costs 0.001 STX. Use execute-endpoint --auto-approve to pay and execute.",
  "payment": {
    "amount": "1000",
    "asset": "STX",
    "recipient": "SP...",
    "network": "mainnet"
  }
}

探测x402 API端点以了解其使用成本，无需进行支付。

bun run x402/x402.ts probe-endpoint --method GET --path /api/pools/trending
bun run x402/x402.ts probe-endpoint --method GET --url https://stx402.com/ai/dad-joke
bun run x402/x402.ts probe-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}'

选项:

```
--method
```
（可选）—— HTTP方法（默认：GET）
```
--url
```
（可选）—— 完整端点URL，优先级高于
```
--path
```
```
--path
```
（可选）—— API端点路径，未提供
```
--url
```
时为必填项
```
--api-url
```
（可选）—— API基础URL（默认：已配置的API_URL）
```
--params
```
（可选）—— 查询参数，为JSON对象
```
--data
```
（可选）—— POST/PUT请求的请求体，为JSON对象

输出（免费端点）:

json

{
  "type": "free",
  "endpoint": "GET https://x402.biwas.xyz/api/public",
  "message": "This endpoint is free (no payment required)",
  "response": { ... }
}

输出（付费端点）:

json

{
  "type": "payment_required",
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "message": "This endpoint costs 0.001 STX. Use execute-endpoint --auto-approve to pay and execute.",
  "payment": {
    "amount": "1000",
    "asset": "STX",
    "recipient": "SP...",
    "network": "mainnet"
  }
}

execute-endpoint

执行端点

Execute an x402 API endpoint. By default probes first and shows cost for paid endpoints. Use

--auto-approve

to pay immediately.

bun run x402/x402.ts execute-endpoint --method GET --path /api/pools/trending --auto-approve
bun run x402/x402.ts execute-endpoint --method GET --url https://stx402.com/ai/dad-joke --auto-approve
bun run x402/x402.ts execute-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}' --auto-approve

Options:

```
--method
```
(optional) — HTTP method (default: GET)
```
--url
```
(optional) — Full endpoint URL. Takes precedence over
```
--path
```
.
```
--path
```
(optional) — API endpoint path. Required if
```
--url
```
not provided.
```
--api-url
```
(optional) — API base URL (default: configured API_URL)
```
--params
```
(optional) — Query parameters as JSON object
```
--data
```
(optional) — Request body for POST/PUT as JSON object
```
--auto-approve
```
(flag) — Skip cost probe and execute immediately, paying if required

Output:

json

{
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "response": { ... }
}

执行x402 API端点。默认会先探测并显示付费端点的成本，使用

--auto-approve

参数可立即支付并执行。

bun run x402/x402.ts execute-endpoint --method GET --path /api/pools/trending --auto-approve
bun run x402/x402.ts execute-endpoint --method GET --url https://stx402.com/ai/dad-joke --auto-approve
bun run x402/x402.ts execute-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}' --auto-approve

选项:

```
--method
```
（可选）—— HTTP方法（默认：GET）
```
--url
```
（可选）—— 完整端点URL，优先级高于
```
--path
```
```
--path
```
（可选）—— API端点路径，未提供
```
--url
```
时为必填项
```
--api-url
```
（可选）—— API基础URL（默认：已配置的API_URL）
```
--params
```
（可选）—— 查询参数，为JSON对象
```
--data
```
（可选）—— POST/PUT请求的请求体，为JSON对象
```
--auto-approve
```
（标志位）—— 跳过成本探测，立即执行并在需要时完成支付

输出:

json

{
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "response": { ... }
}

send-inbox-message

发送收件箱消息

Send a paid x402 message to another agent's inbox on aibtc.com. Uses sponsored transactions (no STX gas fees). Requires an unlocked wallet with sBTC balance.

bun run x402/x402.ts send-inbox-message \
  --recipient-btc-address bc1q... \
  --recipient-stx-address SP... \
  --content "Hello from the agent!"

Options:

```
--recipient-btc-address
```
(required) — Recipient's Bitcoin address (bc1...)
```
--recipient-stx-address
```
(required) — Recipient's Stacks address (SP...)
```
--content
```
(required) — Message content (max 500 characters)

Output:

json

{
  "success": true,
  "message": "Message delivered",
  "recipient": { "btcAddress": "bc1q...", "stxAddress": "SP..." },
  "contentLength": 22,
  "inbox": { ... },
  "payment": { "txid": "0x...", "amount": "1000 sats sBTC" }
}

向aibtc.com上另一个agent的收件箱发送付费x402消息。使用赞助式交易（无需STX gas费），需要一个已解锁且拥有sBTC余额的钱包。

bun run x402/x402.ts send-inbox-message \
  --recipient-btc-address bc1q... \
  --recipient-stx-address SP... \
  --content "Hello from the agent!"

选项:

```
--recipient-btc-address
```
（必填）—— 收件人的比特币地址（bc1...格式）
```
--recipient-stx-address
```
（必填）—— 收件人的Stacks地址（SP...格式）
```
--content
```
（必填）—— 消息内容（最多500字符）

输出:

json

{
  "success": true,
  "message": "Message delivered",
  "recipient": { "btcAddress": "bc1q...", "stxAddress": "SP..." },
  "contentLength": 22,
  "inbox": { ... },
  "payment": { "txid": "0x...", "amount": "1000 sats sBTC" }
}

scaffold-endpoint

搭建端点项目

Create a complete x402 paid API project as a Cloudflare Worker. Generates a new project folder with Hono.js app, x402 payment middleware, wrangler config, and README.

bun run x402/x402.ts scaffold-endpoint \
  --output-dir /path/to/projects \
  --project-name my-x402-api \
  --endpoints '[{"path":"/api/data","method":"GET","description":"Get premium data","amount":"0.001","tokenType":"STX"}]'

Options:

```
--output-dir
```
(required) — Directory where the project folder will be created
```
--project-name
```
(required) — Project name (lowercase with hyphens)
```
--endpoints
```
(required) — JSON array of endpoint configs
```
--recipient-address
```
(optional) — Stacks address to receive payments (uses active wallet if omitted)
```
--network
```
(optional) — Network for payments (default: mainnet)
```
--relay-url
```
(optional) — Custom relay URL (default: https://x402-relay.aibtc.com)

Endpoint config fields:

```
path
```
— Endpoint path (e.g.,
```
/api/data
```
)
```
method
```
— HTTP method (GET or POST)
```
description
```
— Endpoint description
```
amount
```
— Payment amount (e.g.,
```
"0.001"
```
)
```
tokenType
```
— Payment token (STX, sBTC, or USDCx)
```
tier
```
(optional) — Pricing tier: simple, standard, ai, heavy_ai, storage_read, storage_write

创建一个完整的x402付费API项目作为Cloudflare Worker。会生成一个包含Hono.js应用、x402支付中间件、wrangler配置和README的新项目文件夹。

bun run x402/x402.ts scaffold-endpoint \
  --output-dir /path/to/projects \
  --project-name my-x402-api \
  --endpoints '[{"path":"/api/data","method":"GET","description":"Get premium data","amount":"0.001","tokenType":"STX"}]'

选项:

```
--output-dir
```
（必填）—— 项目文件夹将创建的目录
```
--project-name
```
（必填）—— 项目名称（小写，用连字符分隔）
```
--endpoints
```
（必填）—— 端点配置的JSON数组
```
--recipient-address
```
（可选）—— 接收支付的Stacks地址（若省略则使用活跃钱包）
```
--network
```
（可选）—— 支付使用的网络（默认：主网）
```
--relay-url
```
（可选）—— 自定义中继URL（默认：https://x402-relay.aibtc.com）

端点配置字段:

```
path
```
—— 端点路径（例如：
```
/api/data
```
）
```
method
```
—— HTTP方法（GET或POST）
```
description
```
—— 端点描述
```
amount
```
—— 支付金额（例如：
```
"0.001"
```
）
```
tokenType
```
—— 支付代币（STX、sBTC或USDCx）
```
tier
```
（可选）—— 定价层级：simple、standard、ai、heavy_ai、storage_read、storage_write

scaffold-ai-endpoint

搭建AI端点项目

Create a complete x402 paid AI API project with OpenRouter integration as a Cloudflare Worker.

bun run x402/x402.ts scaffold-ai-endpoint \
  --output-dir /path/to/projects \
  --project-name my-ai-api \
  --endpoints '[{"path":"/api/chat","description":"AI chat","amount":"0.003","tokenType":"STX","aiType":"chat"}]'

Options:

```
--output-dir
```
(required) — Directory where the project folder will be created
```
--project-name
```
(required) — Project name (lowercase with hyphens)
```
--endpoints
```
(required) — JSON array of AI endpoint configs
```
--recipient-address
```
(optional) — Stacks address to receive payments (uses active wallet if omitted)
```
--network
```
(optional) — Network for payments (default: mainnet)
```
--relay-url
```
(optional) — Custom relay URL
```
--default-model
```
(optional) — Default OpenRouter model (default: anthropic/claude-3-haiku)

AI Endpoint config fields:

```
path
```
,
```
description
```
,
```
amount
```
,
```
tokenType
```
— same as regular endpoints
```
aiType
```
— Type of AI operation: chat, completion, summarize, translate, custom
```
model
```
(optional) — OpenRouter model override
```
systemPrompt
```
(optional) — Custom system prompt

创建一个集成OpenRouter的完整x402付费AI API项目作为Cloudflare Worker。

bun run x402/x402.ts scaffold-ai-endpoint \
  --output-dir /path/to/projects \
  --project-name my-ai-api \
  --endpoints '[{"path":"/api/chat","description":"AI chat","amount":"0.003","tokenType":"STX","aiType":"chat"}]'

选项:

```
--output-dir
```
（必填）—— 项目文件夹将创建的目录
```
--project-name
```
（必填）—— 项目名称（小写，用连字符分隔）
```
--endpoints
```
（必填）—— AI端点配置的JSON数组
```
--recipient-address
```
（可选）—— 接收支付的Stacks地址（若省略则使用活跃钱包）
```
--network
```
（可选）—— 支付使用的网络（默认：主网）
```
--relay-url
```
（可选）—— 自定义中继URL
```
--default-model
```
（可选）—— 默认OpenRouter模型（默认：anthropic/claude-3-haiku）

AI端点配置字段:

```
path
```
、
```
description
```
、
```
amount
```
、
```
tokenType
```
—— 与常规端点相同
```
aiType
```
—— AI操作类型：chat、completion、summarize、translate、custom
```
model
```
（可选）—— OpenRouter模型覆盖值
```
systemPrompt
```
（可选）—— 自定义系统提示词

openrouter-guide

OpenRouter指南

Get OpenRouter integration examples and code patterns for implementing AI features.

bun run x402/x402.ts openrouter-guide [--environment all] [--feature all]

Options:

```
--environment
```
(optional) — Target environment (nodejs, cloudflare-worker, browser, all)
```
--feature
```
(optional) — Specific feature (chat, completion, streaming, function-calling, all)

获取用于实现AI功能的OpenRouter集成示例和代码模式。

bun run x402/x402.ts openrouter-guide [--environment all] [--feature all]

选项:

```
--environment
```
（可选）—— 目标环境（nodejs、cloudflare-worker、browser、all）
```
--feature
```
（可选）—— 特定功能（chat、completion、streaming、function-calling、all）

openrouter-models

OpenRouter模型列表

List popular OpenRouter models with capabilities and context lengths.

bun run x402/x402.ts openrouter-models [--category all]

Options:

```
--category
```
(optional) — Filter by category: fast, quality, cheap, code, long-context, all (default: all)

Output:

json

{
  "category": "all",
  "count": 13,
  "models": [
    { "id": "anthropic/claude-3.5-haiku", "name": "Claude 3.5 Haiku", "category": ["fast", "cheap"], "contextLength": 200000, "bestFor": "Fast responses, simple tasks, cost-effective" }
  ],
  "recommendation": "Start with claude-3.5-haiku or gpt-4o-mini for most tasks."
}

列出热门的OpenRouter模型，包含其能力和上下文长度。

bun run x402/x402.ts openrouter-models [--category all]

选项:

```
--category
```
（可选）—— 按类别筛选：fast、quality、cheap、code、long-context、all（默认：all）

输出:

json

{
  "category": "all",
  "count": 13,
  "models": [
    { "id": "anthropic/claude-3.5-haiku", "name": "Claude 3.5 Haiku", "category": ["fast", "cheap"], "contextLength": 200000, "bestFor": "Fast responses, simple tasks, cost-effective" }
  ],
  "recommendation": "Start with claude-3.5-haiku or gpt-4o-mini for most tasks."
}

Notes

注意事项

```
execute-endpoint
```
and
```
probe-endpoint
```
require an unlocked wallet when the endpoint requires payment
```
send-inbox-message
```
requires an unlocked wallet with sBTC balance; the sponsored tx flow means no STX is needed for gas
Scaffold commands generate a complete project — run
```
npm install && npm run dev
```
in the generated directory to start
Network is controlled by the
```
NETWORK
```
environment variable (default: testnet); use
```
NETWORK=mainnet
```
for mainnet endpoints

```
execute-endpoint
```
和
```
probe-endpoint
```
在端点需要付费时，需使用已解锁的钱包
```
send-inbox-message
```
需要已解锁且拥有sBTC余额的钱包；赞助式交易流程无需STX支付gas费
脚手架命令会生成完整项目，在生成的目录中运行
```
npm install && npm run dev
```
即可启动
网络由
```
NETWORK
```
环境变量控制（默认：testnet）；使用
```
NETWORK=mainnet
```
可连接主网端点