x402-reconcile

A read-only x402 payment challenge inspector. One inspect command shows exactly what an x402 endpoint demands before it serves — and records response evidence. Never pays.

What it is

x402-reconcile is a command-line tool that inspects an x402 endpoint's HTTP 402 payment challenge. It detects the 402, locates the payment document, and parses the required payment fields — scheme, network, asset, amount, payTo — plus response latency and a SHA-256 hash of the raw response bytes. It is a challenge inspector, not a wallet, not a payer, not a settlement monitor.

The problem it solves

Before an agent (or a human) points an x402 buyer at an endpoint, you want to know: what exactly does this endpoint demand before serving? x402 endpoints advertise their payment requirement in a 402 document that can live in several HTTP locations and two schema shapes. x402-reconcile answers the question read-only — it never signs or submits a payment, so you can reconcile an endpoint's stated requirement without spending anything.

When to use it

• You are integrating against an x402-protected API and want to see its payment requirement before writing buyer code.
• You want to verify an x402 endpoint advertises its payment requirements without paying.
• You are debugging why an x402 client does or does not react to a challenge.
• You need a tamper-evident SHA-256 of the raw 402 response for later comparison.

When NOT to use it

• You want to pay an endpoint — this tool never signs or submits a payment. Use an x402 client/buyer for that.
• You want settlement, delivery, refund, or retry verification — those are out of scope (see What it does NOT check).
• You want a live cross-chain or on-chain trace — see wallet-evidence and crosschain-incident for different jobs.

Installation

npm install -g x402-reconcile     # or run without installing:
npx x402-reconcile inspect <url> --method=POST --json

Real command

npx x402-reconcile inspect https://api.example.com/paid --method=POST --json

Real example (documented live inspection)

The published README records a real public endpoint inspection (2026-09-24): https://notary.forgemesh.io/api/notarize returned HTTP 402 with exact / USDC / amount 1000 — the challenge was parsed, nothing was paid.

Example output

Representative output from the documented live inspection above. The exact SHA-256 and latency are computed by the tool at runtime against the live endpoint; the payment fields shown are the values the README documents.

{
  "endpoint": "https://notary.forgemesh.io/api/notarize",
  "method": "POST",
  "status": 402,
  "payment": {
    "scheme": "exact",
    "network": "eip155:1",
    "asset": "USDC",
    "amount": "1000",
    "payTo": "(address from the 402 document)"
  },
  "evidence": { "elapsedMs": "(measured)", "bodySha256": "(computed at runtime)" }
}

What it checks

• HTTP 402 detection — and location of the payment document (from headers or the response body).
• Payment document parsing — accepts[]: scheme (exact / base …), network (CAIP-2), asset, amount, payTo, timeout.
• Response evidence — latency and a SHA-256 of the raw response bytes, for later comparison.
• Exit behaviour — 0 on successful parse, 1 on FAIL with machine-readable findings[].

What it does NOT check

• No payment is ever signed or submitted. x402-reconcile never spends.
• No settlement, delivery, refund, or retry verification — those remain NOT_TESTED.
• It is a challenge inspector, not a settlement monitor (yet).

Limitations

• Read-only by design: it observes and parses, it does not transact.
• It trusts the endpoint's published 402 document; it does not prove the endpoint will actually serve after payment.
• Experimental (0.1.0): local smoke tests pass (402 challenge, non-402, missing payment document) and one real public x402 endpoint has been inspected read-only.

Status

Experimental (0.1.0). Local smoke tests pass (402 challenge, non-402, missing payment document) and one real public x402 endpoint has been inspected read-only.

npm

Package: x402-reconcile — published by npm user eidonze, version 0.1.0, MIT.

GitHub

Source: xka0085-byte/x402-reconcile — issues and the full README live there.

Related tools

• mcpdoctor — a broader endpoint inspector (402 document + /.well-known discovery manifests) covering MCP and x402; x402-reconcile is its x402-focused sibling.
• ReceiptRail — after an x402 settlement, ReceiptRail anchors a delivery receipt on Solana; the two tools sit on the same x402 pipeline (inspect challenge → pay → receipt).
• oauthdoctor — the suite's MCP OAuth discovery diagnostic.

Part of the Agent / Chain Evidence Tools suite · MIT · Node ≥ 18 · read-only, no keys, no payments