X402 Receipt Verifier MCP server

x402 Receipt Verifier

Audits NEXUS's own x402 payment logs against its own delivery logs and issues a signed receipt proving a specific payment correlates with a real, successful service call. NEXUS candidate #13 -- manual build, not FORGE-generated.

-- charged $0.02 via x402 (Base mainnet, real USDC).

• POST /verify-payment-receipt {"assetname": "...", "payeraddress": "0x...", "claimedamountusd": 0.01, "claimed_at": "2026-08-22T21:31:34Z"}

previously-issued receipt is authentic and unmodified.

• POST /payer-spend-health {"assetname": "...", "payeraddress": "0x..."} -- charged $0.02 via x402.
• POST /verify-receipt-signature {"receipt": {...}, "signature": "..."} -- free, confirms a

• MCP tools verifypaymentreceipt / payerspendhealth at /mcp -- currently free, see "Known limitations".
• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (has x-payment-info).

Mainnet cutover (2026-09-03)

Originally built and measured on Base Sepolia testnet. Cut over to Base mainnet: x402 settlement moved to the CDP facilitator (createfacilitatorconfig(), same swap already applied to ws/live-entity-verification/erc8004-agent-liveness/onchain-activity-index), and the payto wallet moved to NEXUSX402PAYTOADDRESS (fail-fast env var, no placeholder default, renamed from X402WALLETADDRESS). CDPAPIKEYID/CDPAPIKEYSECRET and NEXUSX402PAYTOADDRESS must be set in Cloud Run before this deploys.

What it actually does (and why it's not just a log dump)

revenueevents (x402 payments settled) and trafficevents (HTTP requests served) are two separate, uncorrelated tables -- neither insert stores a shared ID linking a specific payment to the specific request it paid for. This asset does the correlation NEXUS itself doesn't otherwise do anywhere: given a claimed (assetname, payeraddress, claimedamountusd, claimedat), it finds the real matching revenueevents row (if any) within windowseconds, then checks whether a successful (2xx) trafficevents row for that same asset landed shortly after that real payment timestamp. The verdict (VERIFIEDDELIVERY / PAYMENTNODELIVERY / PAYMENTNOTFOUND) plus a signed receipt is the product -- not raw access to either table. Both tables are read through two Postgres SECURITY DEFINER RPC functions (nexusverifypaymentreceipt, nexuspayerspendhealth) that return only the computed verdict object, never a row dump -- consistent with this codebase's existing INSERT-only RLS policy on both tables (see CLAUDE.md SS5). Migration: addx402paymentreceiptverificationrpcs (Supabase project ieduhdgfjdeffvzxvihf).

Scope, on purpose: only covers NEXUS's own already-deployed x402 assets (whatever is actually in our own revenueevents/trafficevents). Auditing a third party's payment claims against a third party's logs was the original, broader idea (opportunity list item #3, "recibo/prueba de ejecucion verificable para pagos entre agentes") and was explicitly flagged there as carrying legal/dispute-liability risk from acting as an arbiter between two other parties. Narrowing scope to our own already-public asset catalog sidesteps that entirely -- there is no third party whose claim we're adjudicating, only our own already-settled data.

Known asset_name spellings (found while building this, real data)

revenueevents.assetname is not consistently kebab-case across the existing catalog -- e.g. the similarity-search asset's real stored value is "Similarity Search API" (display-cased), not similarity-search-api. Callers must pass the exact string as stored, or the RPC correctly (not a bug) returns PAYMENTNOTFOUND. As of this writing, real values seen in revenue_events: document-conversion-api, live-entity-verification, agent-verification-api, url-metadata-api, Similarity Search API, ws.

The signed receipt

Shortened. The full README is on GitHub.