x402-pilot

x402-pilot — build, learn, verify the x402 payment protocol in Claude Code

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-verify against? See examples/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.

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 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.

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.

x402-conformance-mcp

Documentation