x402-conform

x402-conform

A CLI that hits your x402 (HTTP 402 agentic-payment) endpoint and checks it against the spec, plus two facilitator gotchas that have burned real builders:

• CDP's undocumented minimum-amount threshold. Requests under roughly 1000 atomic units on Base get a generic invalid_payload error with no mention that the amount is the problem — one builder spent three PRs reshaping the payload before finding this. x402-conform flags amounts in that range before you burn the same afternoon.
• The EXTENSION-RESPONSES header that facilitators document but don't send (x402-foundation/x402#2112). If it's missing, that's not necessarily your server's fault.

It also validates the required fields on every entry in your accepts array (scheme, network, maxAmountRequired, resource, description, mimeType, payTo, maxTimeoutSeconds, asset), and, if you pass a payment header, confirms the settlement response carries X-PAYMENT-RESPONSE.

Install

npx x402-conform https://your-api.example.com/paid-endpoint

or install it globally / as a dev dependency:

npm install -g x402-conform

Usage

x402-conform <url> [--payment-header <value>]

Without --payment-header, it expects a 402 and validates the PaymentRequirements body:

$ x402-conform https://api.example.com/paid
WARN    accepts[0]: maxAmountRequired=50 on network "base" is below 1000 atomic units. CDP's
        facilitator has been reported to silently reject amounts in this range with a generic
        "invalid_payload" error rather than a documented minimum-amount error.
INFO    No "EXTENSION-RESPONSES" header on the 402 response. This is optional...

With --payment-header, it checks the settlement path instead — no 402, and an X-PAYMENT-RESPONSE header on the response.

Exit code is 1 if any errors were found, 0 otherwise (warnings/info don't fail the run, so it's safe to script but you may want to grep for WARN in CI).

Scope

This checks spec conformance and the two verified facilitator gotchas above. It is not a security scanner — for exploit/fraud-resistance testing of x402 flows, look at Agent Security Harness, which already CI-gates that surface.

Contributing

Found another facilitator quirk that silently breaks things? Open an issue or PR with a repro — this tool exists to collect exactly those.

Built autonomously by an AI agent as part of an experiment in AI-run software ventures.