Provides x402 exact scheme specification coverage and conformance/verification support for Algorand, including checking payment responses against on-chain settlement data via a supplied Algorand RPC endpoint.
Provides x402 exact scheme specification coverage and conformance/verification support for Cardano, enabling agents to build, review, and verify Cardano-based x402 payment flows.
Provides x402 exact scheme specification coverage and conformance/verification support for Hedera, including settlement checks against on-chain data through a supplied Hedera RPC endpoint.
Provides x402 exact scheme specification coverage and conformance/verification support for NEAR, helping agents build and validate NEAR-based x402 payment integrations.
Provides x402 exact scheme specification coverage and conformance/verification support for Stellar, including checking x402 payment responses against on-chain settlement data.
Provides x402 exact scheme specification coverage and conformance/verification support for Sui, enabling agents to build, review, and verify Sui-based x402 payment flows and settlements.
Provides x402 exact scheme specification coverage and conformance/verification support for TON, helping agents create and validate TON-based x402 integrations.
Provides x402 exact scheme specification coverage and conformance/verification support for the XRP Ledger (XRPL), including checking payment responses against on-chain settlement data.
8 commands · 6 conformance MCP tools · offline spec corpus across 17 chains · non-custodial (holds no keys, signs nothing).
The developer-assistant for the x402 payment protocol — a Claude Code plugin that bundles the x402 spec surface and gives your agent the context and workflows to build, learn, and verify x402 code.
x402-pilot is the build/learn/verify companion to the official runtime package @x402/mcp. It does not move money or pay for tools — it helps you write x402 integrations, facilitators, schemes, and extensions, and check them against the spec.
Why this exists: x402 settles real value, and a capable model already knows much of the protocol — but "the model probably remembers" isn't good enough when money moves. x402-pilot makes the spec the source of truth (offline, version-pinned) and adds executable, non-custodial conformance tools that verify rather than recall — recompute a settlement against the on-chain balance change, run verify→settle→idempotency against a facilitator, lint a codebase for hardcoded chain/decimals. The corpus keeps you current as the protocol moves; the tools are right regardless of what any model remembers.
Piece | Status |
Bundled spec corpus — 86 files: protocol v1/v2, transports (http/mcp/a2a), | ✅ Phase 0 |
Routing agent ( | ✅ Phase 0 |
| ✅ Phase 0 |
Commands / skills — | ✅ Phase 1 |
Conformance MCP ( | ✅ Phase 2 |
Evals ( | ✅ Phase 3 |
See SCOPE.md for the full plan.
Related MCP server: x402lint
Install it (Claude Code v2.1+) — add this repo as a marketplace, then install the plugin:
/plugin marketplace add DrVelvetFog/x402-pilot
/plugin install x402-pilot@uig-studiosOr try it for one session without installing — clone the repo and launch:
claude --plugin-dir ./x402-pilotOther agents:
Agent | Install |
Any agent with the |
|
Gemini CLI |
|
Cursor | the repo ships a |
Any MCP client, conformance tools only |
|
Use it. The plugin adds these commands (namespaced under x402-pilot:):
You want to… | Command |
Charge for an HTTP endpoint |
|
Build or audit a facilitator |
|
Author a new-chain / new scheme spec |
|
Work with an extension (offers/receipts, gas-sponsoring) |
|
Review x402 code for spec-compliance |
|
Run verify→settle→idempotency against a facilitator |
|
Cap what an agent can spend, or make a facilitator honour a payer's limit (draft, not spec) |
|
Get oriented / route a question |
|
Need a real endpoint to run
/x402-pilot:x402-verifyagainst? Seeexamples/live-evm-verify-target.md— a known-good live Base (EVM) x402 v2 seller with a free, no-wallet preview, so you can inspect the response shape before wiring up a paid call.
Worked example — charge for your API in 3 steps:
In your project, run /x402-pilot:x402-gate.
Answer the prompts (framework, chain, asset, price, facilitator). It reads the live spec and scaffolds a compliant paywall — the price goes in as atomic units, never a hardcoded decimal.
Run /x402-pilot:x402-verify and give it your facilitator URL to prove the flow end-to-end.
The conformance MCP (mcp__x402-conformance__*) loads automatically with the plugin — your agent can decode a 402, recompute a settlement against the on-chain balance change, or lint a codebase for hardcoded chain/decimals with no extra setup.
The agent searches the bundled specs before generating code:
Glob .x402-specs/schemes/exact/scheme_exact_*.md # find the chain specs
Grep "PAYMENT-RESPONSE" .x402-specs/ # find where a concept is definedx402-pilot is the build/learn/verify layer of a larger x402-on-Sui stack — all built by the same author:
Repo | What it is |
An independent x402 facilitator on Sui — non-custodial, live on mainnet. The runtime x402-pilot teaches you to build. | |
The builder front door: facilitator + tooling + a one-command demo that settles a real payment on Sui mainnet. | |
A reference agent — an EV that pays for its own charge over x402 with usage-metered |
A SessionStart hook (hooks/session-start.sh) reads your project's dependency manifests (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml) and root filenames to check whether the project uses x402. If it does, it adds a short reminder to Claude's context. It reads nothing else and sends nothing anywhere.
The conformance MCP server runs locally with Node (mcp/x402-conformance-mcp/dist/index.js, bundled from the TypeScript in src/). It holds no keys and signs nothing. Three tools are fully offline (check_compliance, lint_scheme_spec, validate_extension). Three can make network requests, and only to URLs you pass in: decode_402 fetches a resource URL to read its 402 response (or decodes one you paste, offline), run_conformance calls the facilitator URL and optional resource URL you give it, and inspect_payment_response calls the chain RPC URL you give it. Requests go straight from your machine to that endpoint.
No telemetry, no accounts, no analytics. See PRIVACY.md.
PRs welcome — see CONTRIBUTING.md for the contribution rules (the corpus is synced from upstream, never hand-edited) and SECURITY.md for how to report a vulnerability. All conduct is governed by the Code of Conduct.
x402-pilot (agent, commands, skills, MCP, scripts) is original work by UIG Studios LLC, Apache-2.0.
The bundled .x402-specs/, .x402-docs/, and .x402-sdk-docs/ are copied from the x402 project (© Coinbase, Apache-2.0) for local developer assistance — see NOTICE. Refresh them with sync-specs.sh.
Built by the author of an independent x402 facilitator on Sui.
Heuristically scan x402 code (a file or directory) for the high-severity classes: hardcoded chain id, hardcoded decimals, magic-number decimal scaling (10**N, 1eN, *1_000_000), human-decimal/float amounts, and literal asset/token addresses. Returns findings with file:line and severity. Heuristic — a documented default may be a false positive; every finding cites a location for human judgement. No network.
Inputs: path (required), maxFiles, maxFindings.
Parse and validate an x402 PaymentRequired (HTTP 402) response and explain every field. Flags missing economic fields (scheme/network/asset/payTo/amount), number-typed or human-decimal amounts (must be atomic-integer strings), and missing explicit decimals. Provide ONE of: url (does an unpaid GET and decodes the 402), raw (a JSON or base64-encoded-JSON body string), or json (an object). Deterministic; the only network is the optional unpaid GET.
Inputs: raw, url, json.
Decode and validate an x402 PAYMENT-RESPONSE, surfacing success, settlement id, payer, network, and amount. Optionally recomputes the on-chain truth: pass rpcUrl + expectedPayTo for a sui:* network (queries sui_getTransactionBlock balanceChanges), or observedBalanceChanges + expectedPayTo for any chain, and it confirms the net balance change to payTo equals the advertised atomic amount (the "recomputed, not trust-the-operator" check). Provide the response via raw (JSON/base64) or json.
Inputs: raw, json, rpcUrl, expectedAsset, +3 more.
Lint a draft scheme spec (markdown) against the bundled scheme_template.md: reports missing/extra template sections and whether the draft pins down the load-bearing concepts a scheme must specify (value/recipient assertion, settlement identifier, replay protection, atomic+decimals amount encoding, verify/settle flow). Reads the bundled corpus; no network.
Inputs: path (required), template.
Drive the x402 conformance sequence against a facilitator. Holds NO keys: automates the 402 negotiation (with resourceUrl), facilitator reachability (GET /supported), and malformed-verify rejection. The keyed steps (verify happy-path, tampered-reject, settle, idempotent re-settle) run ONLY when you supply a pre-signed paymentPayload + paymentRequirements; settle additionally requires allowSettle: true (it settles real testnet value). Assumes the standard facilitator API (POST /verify, POST /settle). Returns a pass/fail/skip line per step.
Inputs: facilitatorUrl (required), allowSettle, resourceUrl, paymentPayload, +1 more.
Structurally validate an x402 extension payload: checks the typed { info, schema } envelope and runs light known-extension field checks (offer-and-receipt, payment_identifier, gas-sponsoring, sign-in-with-x, builder_code). Pass payload as a single entry (with name), an extensions map keyed by name, or an array. Full JSON-schema validation needs the extension’s published schema; this is the structural gate plus a spec pointer. No network.
Inputs: payload (required), name.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool targets a distinct artifact: PaymentRequired decoding, PAYMENT-RESPONSE inspection, code compliance scanning, spec linting, extension validation, and end-to-end conformance runs. The decode_402 vs inspect_payment_response pair could be momentarily confused, but descriptions clearly split request-side vs response-side, and run_conformance is clearly an orchestrator over the others.
All tools follow a consistent snake_case verb_noun pattern (check_compliance, lint_scheme_spec, validate_extension, run_conformance). decode_402 is the only minor deviation, embedding a number instead of a noun, but it remains readable and predictable.
Six tools is well-scoped for an x402 validation/compliance toolkit, with each tool covering a distinct stage of the protocol surface. No bloat and no obviously missing companion tool given the read-only, no-keys design.
The surface covers parsing 402 requests, inspecting responses with on-chain recomputation, spec linting, extension validation, code compliance, and conformance sequencing—a broad lifecycle. Minor gaps exist (no payment construction/signing), but that omission is deliberate given the server holds no keys.
Check an x402 endpoint before you pay it, then test a payment and follow it to settlement.
Free x402 endpoint linter: unpaid 402 challenge, payTo/asset/amount, CORS, directory readiness.
Diagnose x402 seller endpoints: what is wrong with your 402 challenge, and how to fix it.
Read-only on-chain receipt check for x402 payments; confirm settlement before trusting a tx.