Lints HTTP endpoint conformance for the x402 agent-payments protocol and decodes payment blobs.
Also known as arden-instance/x402lint
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 153
- Latest version
- 0.5.2
- Last commit
- Sep 6, 2026
- License
- MIT
What is x402lint MCP?
x402lint lints HTTP endpoint conformance for the x402 agent-payments protocol and decodes payment blobs.
Summary generated from the project's README
About x402lint MCP server
Developers building agent-payments infrastructure can use this tool to verify that HTTP endpoints correctly implement the x402 protocol. It checks if a 402 Payment Required challenge is well-formed, ensuring that agent runtimes can successfully process payments. The server operates via stdio transport and can be integrated into IDE assistants or agentic workflows using the Model Context Protocol.
Users can perform conformance checks on specific URLs, decode base64 payment blobs to inspect their contents, or summarize the supported schemes and networks of a facilitator. The tool handles both v1 legacy JSON bodies and the dominant v2 base64 encoded headers. It validates critical fields such as CAIP-2 network identifiers, EVM addresses, and EIP-712 domain data to ensure complete protocol compliance.
Written from the project's README. Every use case is checked against a quote from it.
How to install x402lint MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall x402lint MCP in Claude Code
$ claude mcp add x402lint -- uvx x402lintInstall x402lint MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"x402lint": {
"command": "uvx",
"args": [
"x402lint"
]
}
}
}Install x402lint MCP in VS Code
.vscode/mcp.json
{
"servers": {
"x402lint": {
"type": "stdio",
"command": "uvx",
"args": [
"x402lint"
]
}
}
}Install x402lint MCP in VS Code CLI
$ code --add-mcp '{"name":"x402lint","type":"stdio","command":"uvx","args":["x402lint"]}'Install x402lint MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"x402lint": {
"command": "uvx",
"args": [
"x402lint"
]
}
}
}Install x402lint MCP in Codex
$ codex mcp add x402lint -- uvx x402lintInstall x402lint MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.x402lint] command = "uvx" args = ["x402lint"]
Install x402lint MCP in Gemini CLI
$ gemini mcp add -s user x402lint uvx -- x402lintInstall x402lint MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"x402lint": {
"command": "uvx",
"args": [
"x402lint"
]
}
}
}Configuration
X402LINT_PRIVATE_KEY
| Name | Description | |
|---|---|---|
| X402LINT_PRIVATE_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablearden-instance/x402lint is public and reachablegithub.com/arden-instance/x402lint ↗Pass
- Package names this repository as its sourcex402lint names arden-instance/x402lint as sourcepypi.org/project/x402lint/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-06github.com/arden-instance/x402lint ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from x402lintPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubx402lint
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.
$ 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)
Install
pip install x402lint
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-requiredbase64 header, the common case today) or v1 (x402Version: 1JSON body). Reports which. - the challenge document decodes / parses
x402Versionis an integer,erroris a human-readable stringacceptsis a non-empty array, and for every entry:- required fields present (
scheme,network, amount,asset,payTo,maxTimeoutSeconds) schemein a known set (exact,upto,batch-settlement) — unknown warnsnetworkis CAIP-2 shaped (v2) or a recognised name (v1) — unknown warns- amount is a base-10 string of a positive integer (atomic units)
asset/payToare valid0x…addresses on EVM networksexact/EVM entries carryextra.name+extra.versionfor the EIP-712 domain- v1 entries carry an absolute
resourceURL
- required fields present (
- discovery metadata (
extensions.bazaar/ v1outputSchema) — 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):
$ x402lint check https://x402.telnyx.com/v1/chat/completions \
--data '{"model":"google/gemma-2b-it","messages":[{"role":"user","content":"hi"}]}'
x402lint decode <blob>
Pretty-prints any base64 x402 header blob — payment-required, X-PAYMENT,
payment-response — and labels what kind of document it is. - reads stdin.
curl -sD - https://weather.payapi.market/current \
| grep -i ^payment-required: | cut -d' ' -f2 \
| x402lint decode -
x402lint facilitator [url]
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.
$ 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]
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:
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 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.
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...
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.
$ 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
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/x402lint@v0.5.2
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.
License
MIT
x402lint MCP questions
How do I add x402lint MCP to Claude Code?
Run claude mcp add x402lint -- uvx x402lint in your terminal. Add --scope user to make it available in every project.
How do I add x402lint MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use x402lint in my CI/CD pipeline?
Yes, you can use the provided GitHub Action to run the linter in your CI so that deployments breaking your 402 challenge fail the build.