x402-recon

Reconciliation and customer analytics for agent-initiated x402/USDC stablecoin payments on Base.

Point it at a seller's endpoint or receiving address and it turns a wall of tiny automated payments into a summary: how much came in, and who actually came back versus who just tried it once. It never holds or moves funds, and it is not tax or accounting advice.

Stdlib-only. Zero runtime dependencies. Python 3.11+.

Install

uvx x402-recon --url https://api.example.com/search --last 30d

or install it properly:

pip install x402-recon

Quick start

$ x402-recon --url https://api.exa.ai/search --last 30d

x402-recon - 0x6d6E695b...0B9192
Base mainnet - 2026-07-28 to 2026-08-27 - payTo discovered from api.exa.ai

  Net received          $34.296    from 5349 payments
  Distinct payers            140    38.2 payments each

Who actually came back
----------------------
                    payers   payments         revenue    share
  Returning (3+)        69      5,255         $33.699    98.3%
  Tried twice           23         46          $0.301     0.9%
  One-shot              48         48          $0.296     0.9%

That's real output from a live run. --url discovers the seller's receiving address from their own HTTP 402 response — only a discovered address gets called "x402" in the output; a raw address is reported as "USDC payments," since there's no 402 response backing that stronger claim:

x402-recon 0xRECEIVER_ADDRESS --last 30d

Six commands cover normal use (discover, report, customers, fetch, ingest, categorize); run --advanced to see the research/validation tooling used to measure this tool's own accuracy.

Independently validated. The x402 Bazaar publishes per-service call and unique-payer counts. Over a comparable 30-day window it reports 3,575 calls from 89 payers for the endpoint above; this tool measured 5,349 on-chain payments from 140 payers — within a pre-registered 2x acceptance criterion (API calls and settled on-chain payments count different things over non-identical windows, so close agreement rather than an exact match is the expected result).

What it can't tell you

• What was bought. x402 settlement carries no resource identifier on-chain, so every transaction's memo is None and the report says so instead of guessing.
• Grouping accuracy on your data, until you run evaluate against your own labeled sample — payer/service grouping is calibrated on simulated data by default.

Development

uv sync
uv run pytest

See CONTRIBUTING.md for the rules (no runtime dependencies, money is always integer micro-USDC, nothing silently dropped) and SECURITY.md for the reporting policy and what this tool does and doesn't send over the network.