x402lint

x402lint

用于 x402 Agent 支付协议的合规性检查工具。 将它指向一个需要付费访问的 HTTP 端点，它会告诉你该端点返回的 402 Payment Required 挑战是否格式正确——Agent 运行时会在付款前进行这项检查。

$ x402lint check https://riddlex402.vercel.app/api/riddle
PASS  status: HTTP 402 Payment Required
INFO  format: x402 v2 (payment-required header)
PASS  header-decode: payment-required header is base64 JSON
PASS  x402Version: 2
PASS  error: 'Payment required'
PASS  resource.url: https://riddlex402.vercel.app/api/riddle
PASS  accepts: 1 payment option(s)
PASS  accepts[0].required: all required fields present
PASS  accepts[0].scheme: 'exact'
PASS  accepts[0].network: eip155:8453 (CAIP-2)
PASS  accepts[0].amount: 2000 atomic units
PASS  accepts[0].asset: valid EVM address
PASS  accepts[0].payTo: valid EVM address
PASS  accepts[0].maxTimeoutSeconds: 300
PASS  accepts[0].extra: EIP-712 domain: name='USD Coin' version='2'
INFO  discovery: advertises the 'bazaar' discovery extension

14 pass, 0 warn, 0 fail  (CONFORMANT)

安装

pip install x402lint

检查器（check / decode / facilitator / survey）只使用 Python 标准 库，要求 Python 3.12+。pay 命令还需要 EIP-712 签名器： pip install 'x402lint[pay]'。

命令

x402lint check <url>

不带支付标头获取 <url>，预期收到 402，并检查支付 挑战：

• 状态码是否恰好为 402
• 传输格式——v2（payment-required base64 标头，目前最常见的格式） 或 v1（x402Version: 1 JSON 正文）。报告所用格式。
• 挑战文档能否解码／解析
• x402Version 是否为整数，error 是否为易于理解的字符串
• accepts 是否为非空数组，且其中每个条目是否都满足：
  • 是否包含必需字段（scheme、network、amount、asset、payTo、 maxTimeoutSeconds）
  • scheme 是否属于已知集合（exact、upto、batch-settlement）——未知值会发出警告
  • network 是否采用 CAIP-2 格式（v2）或可识别名称（v1）——未知值会发出警告
  • amount 是否为正整数的十进制字符串（原子单位）
  • asset / payTo 是否为 EVM 网络上的有效 0x… 地址
  • exact／EVM 条目是否包含 EIP-712 域所需的 extra.name + extra.version
  • v1 条目是否包含绝对 resource URL
• 发现元数据（extensions.bazaar / v1 outputSchema）——报告但不要求

--json 会输出机器可读的报告（用于 CI）。退出码：0 表示合规 （允许有警告），1 表示存在任何失败，2 表示工具错误。

对于会在返回 402 前先验证请求正文的 POST 端点（大多数 LLM 网关），请使用 --data 传入正文（隐含 POST；@file 或 - 表示从文件／stdin 读取）：

$ x402lint check https://x402.telnyx.com/v1/chat/completions \
    --data '{"model":"google/gemma-2b-it","messages":[{"role":"user","content":"hi"}]}'

x402lint decode <blob>

美化输出任意 base64 x402 标头 blob——payment-required、X-PAYMENT、 payment-response——并标明文档类型。- 表示从 stdin 读取。

curl -sD - https://weather.payapi.market/current \
  | grep -i ^payment-required: | cut -d' ' -f2 \
  | x402lint decode -

x402lint facilitator [url]

获取 GET <url>/supported，并列出 facilitator 能够 verify／settle 的每个 (x402Version, scheme, network) 三元组，以及其声明的扩展。 对于未知方案或非 CAIP-2 v2 网络会发出警告。url 默认为 https://x402.org/facilitator（公共测试网 facilitator）。支持 --json。

$ x402lint facilitator
  v2  exact              eip155:84532
  v2  upto               eip155:84532 +extra
  v2  batch-settlement   eip155:84532
  ...
11 kind(s): schemes batch-settlement, exact, upto; 9 network(s); versions 1, 2

x402lint survey [catalogue]

获取发现目录（catalogue 默认为 Coinbase CDP 的 .../x402/discovery/resources 列表），选取按 30 天调用量排序最繁忙的 --limit 个资源，并对每个资源运行 check——快速生成一份“x402 合规状态”快照。它会重放每个资源声明的 bazaar 输入方法和示例查询参数， 确保请求实际到达付费墙（使用 --no-hints 强制执行普通 GET）。支持 --json。

$ x402lint survey --limit 8
ok   v2  https://x402.twit.sh/tweets/search?from=elonmusk&minLikes=100&words=bitcoin
FAIL v2  https://x402.tavily.com/search
       - accepts[1].amount: 'amount' must be a base-10 string of a positive integer, got '0.016'
...
7/8 endpoints conformant

持续调查结果——按主机汇总的最繁忙在线 x402 端点合规情况表——维护于 SURVEY.md，带日期的快照位于 data/。

x402lint pay <url>

获取端点的 402 响应，选择第一个 exact 方案的 accepts[] 条目（或使用 --accept-index N），并离线签署 EIP-3009 TransferWithAuthorization 付款——不发起交易、不消耗 gas，只生成 EIP-712 签名。输出客户端会发送的 X-PAYMENT 标头值。EIP-712 域（name/version/chainId/verifyingContract）从传输内容中读取（accepts[].extra + network + asset），绝不硬编码。

私钥从环境变量读取（默认为 X402LINT_PRIVATE_KEY，可使用 --key-env NAME 修改），绝不会记录到日志中。需要安装 pay 附加依赖：

pip install 'x402lint[pay]'
export X402LINT_PRIVATE_KEY=0x...
$ x402lint pay https://api.example.com/data
# payer     0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A
# asset     0x036CbD53842c5426634e7929541eC2318f3dCF7e  (USDC v2, chain 84532)
# payTo     0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value     1000 atomic units
# expires   validBefore=1756431600

X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3Qi...

--json 会输出付款方、授权元组、签名、完整的 PaymentPayload 和标头。

x402lint roundtrip <url>

先执行 pay，再使用 X-PAYMENT 标头重新发送请求，并报告服务器如何处理该付款。解码 X-PAYMENT-RESPONSE 标头（success、transaction、network）；如果付款被拒绝，则回退到响应正文中的 error 字符串。只有付款已结算时才以状态码 0 退出，否则以状态码 1 退出。

export X402LINT_PRIVATE_KEY=0x...
$ x402lint roundtrip https://api.example.com/data
# payer     0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A
# payTo     0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value     1000 atomic units  (chain 84532)
# retry     HTTP 200

SETTLED  tx 0xabc123...

需要安装 pay 附加依赖，并使用有余额的密钥才能完成实际结算；如果余额不足，它仍会执行完整流程，然后报告 NOT SETTLED (insufficient_funds)。

--facilitator <url>

直接与 facilitator 的 /verify + /settle 交互以完成结算，而不是重新向资源服务器发送请求。当资源服务器构建自己的（CAIP-2）paymentRequirements，并且 facilitator 仅接受其中的 v1 友好名称时，这种方式很有用。x402lint 会将质询转换为 v1 结算信封（base-sepolia、maxAmountRequired、x402Version: 1）；如果 /verify 拒绝付款，则不会继续调用 /settle。

$ x402lint roundtrip --facilitator https://x402.org/facilitator https://x402.org/protected
# payer        0xc838ED72fd5905C30801515DdC7B5cc13F36E88D
# payTo        0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value        10000 atomic units  (base-sepolia)
# facilitator  https://x402.org/facilitator
# verify       HTTP 200  -> valid

SETTLED  tx 0x188066d0...

GitHub Action

在 CI 中运行 lint 检查，这样部署导致 402 质询失效时就会构建失败。仓库根目录提供了一个复合 Action，也列于 GitHub Marketplace：

# .github/workflows/x402.yml
name: x402 conformance
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: arden-instance/[email protected]
        with:
          url: https://your-endpoint.example/api
          # url: |               # multiple endpoints, one per line
          #   https://a.example/x
          #   https://b.example/y
          # version: 0.5.2        # pin the linter (default: latest)
          # strict: "true"        # also fail on WARN-level findings

如果任何端点返回不符合规范的 402，该步骤会以非零状态码退出（使作业失败），并在运行记录中标注具体问题。

本仓库的 .github/workflows/x402.yml 中提供了可运行的示例——它会按每周计划，让该 Action 检查一个已知正常的公开端点。复制该文件并替换为你自己的 URL。

MCP 服务

pip install 'x402lint[mcp]' 会添加 x402lint mcp 子命令（也会安装为 x402lint-mcp），这是一个 Model Context Protocol 服务（stdio 传输），Agent 或 IDE 助手无需调用 shell 即可对 x402 端点执行 lint 检查。它提供三个工具：

工具	功能
lint_endpoint	不带付款凭据地获取 URL，预期收到 402，并返回合规性报告
decode_payment	解码并分类 base64 编码的 X-PAYMENT / accepts 数据
check_facilitator	汇总 facilitator 支持结算的方案／网络组合

// claude_desktop_config.json / any MCP client
{
  "mcpServers": {
    // installed on PATH:
    "x402lint": { "command": "x402lint-mcp" }
    // or zero-install via uv:
    // "x402lint": { "command": "uvx", "args": ["--from", "x402lint[mcp]", "x402lint", "mcp"] }
  }
}

协议说明

目前存在两种传输格式。截至 2026 年，v2（x402Version: 2，Linux Foundation 规范）在实际应用中占主导地位：PaymentRequired 文档以 base64 编码后放在 payment-required 响应标头中，网络使用 CAIP-2 ID（eip155:8453），金额字段为 amount。v1 是旧版格式：文档位于 JSON 正文中，网络使用友好名称（base），金额字段为 maxAmountRequired。x402lint 两种格式都支持。

许可证

MIT