x402

x402 技能

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

用法

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

子命令

list-endpoints

列出已知的 x402 API 端点来源，并附上说明和用法示例。

bun run x402/x402.ts list-endpoints

输出：

{
  "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

探测 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 对象格式请求正文

输出（免费端点）：

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

输出（付费端点）：

{
  "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

执行 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（标志）— 跳过费用探测并立即执行；如有需要则支付

输出：

{
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "response": { ... },
  "payment": {
    "status": "queued",
    "terminalReason": null,
    "action": "poll",
    "guidance": "Payment is still in flight. Keep polling this paymentId and do not rebuild or re-sign.",
    "paymentId": "relay_pay_123",
    "checkUrl": "https://relay.example/rpc/payment-check/relay_pay_123",
    "txid": null
  }
}

说明：

• 只有在实际已知规范支付元数据时，才会包含 payment。
• 客户端的 payment-identifier 扩展是用于中继去重的幂等键，不是面向调用方的规范 paymentId。

send-inbox-message

向 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（必需）— 接收方的 Bitcoin 地址（bc1...）
• --recipient-stx-address（必需）— 接收方的 Stacks 地址（SP...）
• --content（必需）— 消息内容（最多 500 个字符）

输出：

{
  "success": false,
  "message": "Payment is still in flight. Keep polling the same paymentId; do not rebuild or re-sign.",
  "recipient": { "btcAddress": "bc1q...", "stxAddress": "SP..." },
  "contentLength": 22,
  "inbox": { ... },
  "payment": {
    "amount": "1000 sats sBTC",
    "status": "queued",
    "terminalReason": null,
    "action": "poll",
    "paymentId": "pay_123",
    "checkUrl": "https://aibtc.com/rpc/payment-check/pay_123",
    "txid": null
  }
}

说明：

• 面向调用方的支付状态会将旧版 submitted 归并为 queued。
• send-inbox-message 仅在确认送达后才会向调用方报告 success: true。内部重试助手的 success 标志仅表示工作流完成时未抛出异常；messageDelivered 才是送达确认位。
• 如果支付仍在进行中，请继续轮询同一个 payment.paymentId。仅当服务器返回规范提示时才使用 payment.checkUrl；不要假设每个 x402 端点都提供本地 /api/payment-status/:paymentId 路由。x402-api 仍是按次即时支付的例外情况，不会建立通用的本地轮询约定。
• 支付进入终态时，terminalReason 是规范化后的终态信号。

scaffold-endpoint

创建完整的 x402 付费 API 项目，并将其构建为 Cloudflare Worker。生成包含 Hono.js 应用、x402 支付中间件、wrangler.jsonc 配置和 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（可选）— 付款使用的网络（默认值：mainnet）
• --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

创建集成 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（可选）— 付款使用的网络（默认值：mainnet）
• --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

获取用于实现 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 模型及其功能和上下文长度。

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

选项：

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

输出：

{
  "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."
}

付款模式

execute-endpoint 会根据 X402_PAYMENT_MODE 构建付款交易：

模式	交易	钱包需求	适用场景
sponsored（默认）	赞助交易，手续费为 0 — 服务端或 aibtc 中继会联署交易并支付 Gas	仅需支付价格所需的 sBTC 或 STX	端点通过 aibtc 赞助中继结算
direct	仅由钱包签名的标准转账，手续费由钱包支付	价格 加上 用于 Gas 的 STX（sBTC 不超过 0.1 STX，STX 不超过 0.003 STX，并设有上限）	端点自行验证并广播付款，并以 422 sponsored_unsupported 响应赞助交易字节

X402_PAYMENT_MODE=direct NETWORK=mainnet bun run x402/x402.ts execute-endpoint --url https://api.example.com/paid --auto-approve

直接模式采用失败时默认拒绝的策略：仅为当前网络的原生 STX 或规范 sBTC 代币签名；拒绝超过 X402_MAX_SATS_PER_PAYMENT（默认值：10000）/ X402_MAX_USTX_PER_PAYMENT（默认值：1000000）的金额；将手续费限制在 X402_MAX_FEE_USTX（默认值：100000）以内（如果上限低于对应类型的最低手续费，则直接拒绝，不会向上取整）；拒绝字节级不完全匹配的挑战条款（补零金额、地址或资产 ID、无法解析的链 ID、非正数 maxTimeoutSeconds）；若无法从 Stacks API 读取内存池手续费、nonce 或余额，则拒绝付款。所有这些设置都会在创建客户端时解析，因此拼写错误会在响应任何 402 之前导致失败。 由于调用方会为每次调用创建一个客户端，而且在结果不明确的失败后重试可能导致重复付款，因此除了每笔付款上限外，还设置了两道持久化防护：

• 重复请求防护 — 当先前付款的结果未知时，如果请求完全相同（方法、URL、参数、请求体、付款方、收款方、金额、资产），系统会返回之前的 txid，而不会再次签名。结果未知的情况包括：已发送付费请求后失败或超时、进程在处理过程中崩溃、链上状态报告失败，或之前的调用仍在进行中。系统会在发送已签名字节之前写入记录，并在 X402_DEDUP_TTL_SECONDS（默认值为 900）后使记录过期。服务器对付费请求返回 2xx 后，记录会被清除，因此重复购买同一端点（例如轮询价格源）会正常付款。如果付费请求根本没有到达服务器（DNS 故障、连接被拒绝、TLS 验证失败），系统会同时释放记录和账本条目，因为没有发送请求。状态文件：~/.aibtc/x402-dedup.json（仅包含摘要和 txid；可通过 X402_DEDUP_STATE_FILE 覆盖）。
• 每日支出账本 — 按钱包、按 UTC 日分别以两种单位记录：SPEND_LIMIT_DAILY_SATS（默认值为 50000）和 SPEND_LIMIT_DAILY_USTX（默认值为 10000000，即 10 STX；sBTC 付款的 Gas 计入此项）。这是 aibtc MCP 服务自己的账本——使用同一文件（~/.aibtc/spend-state.json）、相同结构和相同环境变量名称——因此，同一钱包同时用于两种工具时，共用一个每日上限，而不是两个。只有 SPEND_LIMIT_ENABLED=false 才会禁用此功能（MCP 服务的测试方式；其他写法均无效）。可通过 X402_SPEND_STATE_FILE 覆盖此文件。在 MCP 服务对该文件执行自身的读-改-写操作时也采用相同锁之前，如果两个工具同时付款，可能会丢失一次更新；因此，在这段时间内，共用上限属于尽力防护，而非严格限制。

检查 → 签名 → 记录的流程在跨进程锁（~/.aibtc/x402-guards.lock）下运行，因此，同时启动的两个直接客户端无法为同一请求重复付款。锁的持有进程每 10 s 刷新一次锁。只有在能确认持有进程已不存在时，才会自动回收 60 s 未更新心跳的锁（该进程的 pid 在此主机上已不存在，或是容器重启后遗留的本进程 pid）；回收操作本身通过 x402-guards.lock.reclaim 串行化。否则，付款会被拒绝，并指出持有者的 pid 和路径；只有确认该进程已退出后，才可自行删除该目录。如果防护文件存在但无法信任（无法解析、结构错误或条目格式错误），付款也会被拒绝；请先将其移至其他位置，而不要删除可能记录先前付款的证据。

直接模式从 Stacks API 获取其 nonce（possible_next_nonce），不会查询其他写入技能使用的共享 nonce 跟踪器。避免在同一钱包的另一笔写入操作（例如已预留 nonce 但尚未广播的转账或合约调用）进行时执行直接 x402 付款：两者可能选用相同 nonce，导致其中一笔交易被拒绝。

即使服务器未提供付款状态路由，输出中的 payment 对象仍会包含 mode、txid、txStatus 和 settlementState（submitted → confirmed | failed）。此设置不影响 send-inbox-message。

说明

• 如果端点要求付款，execute-endpoint 和 probe-endpoint 需要已解锁的钱包
• send-inbox-message 需要有 sBTC 余额的已解锁钱包；赞助交易流程意味着 Gas 无需 STX
• 脚手架命令会生成完整项目——在生成的目录中运行 npm install && npm run dev 即可启动
• 网络由 NETWORK 环境变量控制（默认值：testnet）；主网端点请使用 NETWORK=mainnet