A conformance linter for the x402 agent-payments protocol.
Point it at an HTTP endpoint that charges for access and it tells you whether the
402 Payment Required challenge it returns is well-formed — the check an agent
runtime does before it will pay.
Lint an HTTP endpoint's x402 402 conformance; decode X-PAYMENT blobs; inspect a facilitator.
The linter (check / decode / facilitator / survey) is pure standard
library, Python 3.12+. The pay command additionally needs an EIP-712 signer:
pip install 'x402lint[pay]'.
Commands
x402lint check <url>
Fetches <url> with no payment header, expects a 402, and checks the payment
challenge:
status is exactly 402
wire format — v2 (payment-required base64 header, the common case today)
or v1 (x402Version: 1 JSON body). Reports which.
the challenge document decodes / parses
x402Version is an integer, error is a human-readable string
accepts is a non-empty array, and for every entry:
scheme in a known set (exact, upto, batch-settlement) — unknown warns
network is CAIP-2 shaped (v2) or a recognised name (v1) — unknown warns
amount is a base-10 string of a positive integer (atomic units)
asset / payTo are valid 0x… addresses on EVM networks
exact/EVM entries carry extra.name + extra.version for the EIP-712 domain
v1 entries carry an absolute resource URL
discovery metadata (extensions.bazaar / v1 outputSchema) — reported, not required
--json emits a machine-readable report (for CI). Exit code: 0 conformant
(warnings allowed), 1 any failure, 2 tool error.
For a POST endpoint that validates its request body before returning the 402
(most LLM gateways), pass a body with --data (implies POST; @file or -
reads a file / stdin):
Fetches GET <url>/supported and lists every (x402Version, scheme, network)
triple the facilitator can verify / settle, plus its advertised extensions.
Warns on unknown schemes or non-CAIP-2 v2 networks. url defaults to
https://x402.org/facilitator (the public testnet facilitator). --json.
Pulls a discovery catalogue (catalogue defaults to the Coinbase CDP
.../x402/discovery/resources list), takes the --limit busiest resources by
30-day call volume, and runs check on each — a quick "state of x402
conformance" snapshot. It replays each resource's advertised bazaar input
method and example query params so the request actually reaches the paywall
(--no-hints to force a plain 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
Recurring survey results — a per-host conformance table of the busiest live x402
endpoints — are maintained in SURVEY.md, with dated snapshots in
data/.
x402lint pay <url>
Fetches the endpoint's 402, picks the first exact-scheme accepts[] entry
(or --accept-index N), and signs an EIP-3009 TransferWithAuthorization
payment offline — no transaction, no gas, just an EIP-712 signature. Prints
the X-PAYMENT header value a client would send back. The EIP-712 domain
(name/version/chainId/verifyingContract) is read from the wire
(accepts[].extra + network + asset), never hardcoded.
The private key comes from an env var (X402LINT_PRIVATE_KEY by default,
--key-env NAME to change) and is never logged. Needs the pay extra:
--json emits the payer, authorization tuple, signature, full PaymentPayload,
and header.
x402lint roundtrip <url>
pay, then resend the request with the X-PAYMENT header and report what the
server did with it. Decodes the X-PAYMENT-RESPONSE header (success,
transaction, network); falls back to the response body's error string when
the payment is rejected. Exits 0 only if the payment settled, 1 otherwise.
Needs the pay extra and a funded key for a real settlement; without funds it
reports NOT SETTLED (insufficient_funds) after exercising the full path.
--facilitator <url>
Settle directly against a facilitator's /verify + /settle rather than
re-sending to the resource server. Useful when the resource server builds its own
(CAIP-2) paymentRequirements and self-fails against a facilitator that only
accepts v1 friendly names there. x402lint translates the challenge into the v1
settle envelope (base-sepolia, maxAmountRequired, x402Version: 1) and stops
before /settle if /verify rejects the payment.
Run the linter in CI so a deploy that breaks your 402 challenge fails the
build. The repo ships a composite action at its root, also listed on the
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
The step exits non-zero (failing the job) if any endpoint returns a
non-conformant 402, annotating the run with the specific findings.
A runnable worked example lives at
.github/workflows/x402.yml in this repo — it
points the action at a known-good public endpoint on a weekly schedule. Copy it
and swap in your own URL(s).
MCP server
pip install 'x402lint[mcp]' adds an x402lint mcp subcommand (also installed
as x402lint-mcp), a Model Context Protocol
server (stdio transport) so an agent or IDE assistant can lint an x402 endpoint
without shelling out. It exposes three tools:
tool
what it does
lint_endpoint
fetch a URL unpaid, expect a 402, return the conformance report
decode_payment
decode + classify a base64 X-PAYMENT / accepts blob
check_facilitator
summarise a facilitator's settleable scheme/network pairs
// 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"] }
}
}
Protocol notes
Two wire formats exist. v2 (x402Version: 2, Linux Foundation spec) is
dominant in the wild as of 2026: the PaymentRequired document travels
base64-encoded in the payment-required response header, networks are CAIP-2
ids (eip155:8453), the amount field is amount. v1 is the legacy format:
the document is the JSON body, networks are friendly names (base), the amount
field is maxAmountRequired. x402lint handles both.
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
X402lint nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
X402lint için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
X402lint hangi aktarımı kullanıyor?
X402lint yerel olarak stdio üzerinden çalışır.
X402lint en son ne zaman kontrol edildi?
Son kontrol: 2026-11-09. Lint an HTTP endpoint's x402 402 conformance; decode X-PAYMENT blobs; inspect a facilitator.