x402-conformance-mcp
io.github.DrVelvetFog/x402-conformance-mcp
Non-custodial x402 checks: decode 402s, verify settlements on-chain, lint specs, test facilitators.
Documentation
x402-pilot
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.
What's inside
| Piece | Status |
|---|---|
Bundled spec corpus — 86 files: protocol v1/v2, transports (http/mcp/a2a), exact scheme across 17 chains (EVM, Sui, SVM, Aptos, TON, NEAR, Stellar, Hedera, Algorand, Concordium, Cardano, Keeta, Canton, Casper, LN-BTC, Starknet, XRPL), other scheme families, extension specs, authoring templates, SDK READMEs | ✅ Phase 0 |
Routing agent (agents/x402-pilot-agent.md) — routes a topic to the right corpus; carries the contribution rules + facilitator-implementation lessons | ✅ Phase 0 |
llms.txt — AI entry-point manifest | ✅ Phase 0 |
Commands / skills — /x402-pilot, /x402-gate, /x402-facilitator, /x402-scheme, /x402-extension, /x402-review, /x402-verify, /x402-spend-limit | ✅ Phase 1 |
Conformance MCP (mcp/x402-conformance-mcp) — decode_402, inspect_payment_response (with on-chain net-balance truth check), check_compliance, lint_scheme_spec, validate_extension, run_conformance. Non-custodial: holds no keys. | ✅ Phase 2 |
Evals (evals/) — 7 stale-training tasks, baseline vs pilot A/B, auto-scored to HTML. Built & validated; run with budget. | ✅ Phase 3 |
See SCOPE.md for the full plan.
Quick start
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-studios
Or try it for one session without installing — clone the repo and launch:
claude --plugin-dir ./x402-pilot
Other agents:
| Agent | Install |
|---|---|
Any agent with the skills CLI (Cursor, Codex, Copilot and more) | npx skills add DrVelvetFog/x402-pilot |
| Gemini CLI | gemini extensions install https://github.com/DrVelvetFog/x402-pilot |
| Cursor | the repo ships a .cursor-plugin/plugin.json |
| Any MCP client, conformance tools only | npx -y @uigstudios/x402-conformance-mcp (details) |
Use it. The plugin adds these commands (namespaced under x402-pilot:):
| You want to… | Command |
|---|---|
| Charge for an HTTP endpoint | /x402-pilot:x402-gate |
| Build or audit a facilitator | /x402-pilot:x402-facilitator |
| Author a new-chain / new scheme spec | /x402-pilot:x402-scheme |
| Work with an extension (offers/receipts, gas-sponsoring) | /x402-pilot:x402-extension |
| Review x402 code for spec-compliance | /x402-pilot:x402-review |
| Run verify→settle→idempotency against a facilitator | /x402-pilot:x402-verify |
| Cap what an agent can spend, or make a facilitator honour a payer's limit (draft, not spec) | /x402-pilot:x402-spend-limit |
| Get oriented / route a question | /x402-pilot:x402-pilot |
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-verifyand 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.
Under the hood: the bundled corpus is searched directly (no precomputed index)
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 defined
Ecosystem
x402-pilot is the build/learn/verify layer of a larger x402-on-Sui stack — all built by the same author:
| Repo | What it is |
|---|---|
| sui-x402-facilitator | An independent x402 facilitator on Sui — non-custodial, live on mainnet. The runtime x402-pilot teaches you to build. |
| x402-sui-stack | The builder front door: facilitator + tooling + a one-command demo that settles a real payment on Sui mainnet. |
| x402-charging-agent | A reference agent — an EV that pays for its own charge over x402 with usage-metered upto billing and on-chain settlement receipts. |
What it runs and connects to
- 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 insrc/). 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_402fetches a resource URL to read its 402 response (or decodes one you paste, offline),run_conformancecalls the facilitator URL and optional resource URL you give it, andinspect_payment_responsecalls 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.
Contributing & security
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.
Provenance & license
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.
@uigstudios/x402-conformance-mcpnpm install @uigstudios/x402-conformance-mcp