x402 Receipt Verifier

Prüft NEXUS’ eigene x402-Zahlungslogs gegen die eigenen Zustellungslogs und stellt eine signierte Quittung aus, die belegt, dass eine bestimmte Zahlung mit einem tatsächlichen, erfolgreichen Service-Aufruf korreliert. NEXUS-Kandidat #13 -- manueller Build, nicht FORGE-generiert.

• POST /verify-payment-receipt {"asset_name": "...", "payer_address": "0x...", "claimed_amount_usd": 0.01, "claimed_at": "2026-08-22T21:31:34Z"} -- kostet $0,02 per x402 (Base‑Sepolia‑Testnetz).

• POST /payer-spend-health {"asset_name": "...", "payer_address": "0x..."} -- kostet $0,02 per x402.

• POST /verify-receipt-signature {"receipt": {...}, "signature": "..."} -- kostenlos, bestätigt, dass eine zuvor ausgestellte Quittung authentisch und unverändert ist.

• MCP-Tools verify_payment_receipt / payer_spend_health unter /mcp -- derzeit kostenlos, siehe „Bekannte Einschränkungen".

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (enthält x-payment-info).

Was es tatsächlich tut (und warum es kein bloßer Log-Auszug ist)

revenue_events (abgerechnete x402-Zahlungen) und traffic_events (bediente HTTP-Anfragen) sind zwei getrennte, nicht korrelierte Tabellen -- bei keinem Insert wird eine gemeinsame ID gespeichert, die eine bestimmte Zahlung mit der konkreten Anfrage verknüpft, die sie bezahlt hat. Dieses Asset führt die Korrelation durch, die NEXUS selbst sonstnirgends vorsschafft: Zu einer behaupteten Angabe (asset_name, payer_adresse, claimed_amount_usd, claimed_at) findet es die echte stimmende revenue_events-Zeile (falls vorhanden) innerhalb von window_seconds und prüft dann, ob eine erfolgreiche (2xx) traffic_events-Zeile für dasselbe Asset kurz nach diesem echten Zahlungszeitpunkt eingegangen ist. Das Ergebnis (VERIFIED_DELIVERY / PAYMENT_NO_DELIVERY / PAYMENT_NOT_FOUND) plus eine signierte Quittung ist das Produkt -- kein von loggerem Zugriff auf eine Testsdaher. Beide Tabellen werden über zwei Postgres-SECURITY-DEFINER-RPC-Funktionen ausgelesen (nexus_verify_payment_receipt, nexus_payer_spend_health), is warehouse read over only the calculation where -- never a row dump. This is in line with the existing INSERT-only RLS policy for both tables in this codebase (see CLAUDE.md SS5). Migration: add_x402_payment_receipt_verification_rpcs (Supabase project ieduhdgjdeffvzxvihf).

Sinnvoll begrenzter scope: Abgedeckt werden nur bereits bereitgestellte NEX-x402-Assets selbst, also der echte eigenen... das, was wirklich in revenue_events/traffic_events liegt. Die Prüfung der Zahlungsansprüche eines Dritten anhand der eigenen Logs eines Dritten war die ursprüngliche, breite Idee (Opportunity-Liste Punkt #3, „recibo/prueba de ejecución verificable para pagos entre agentes") – and dort als rechtliches/streitiges Haftung Risiko markiert, denn husband.

Es ist Korrelation, die NEXUS selbst sonst nirgends macht (actual written):

"Dieses Asset übernimmt die Korrelation, die NEXUS itself ansonsten nirgends durchführt, wenn man with einem behaupteten (asset_name, payer_address, claimed_amount_usd, claimed_at) die real vorhandene Zeile in revenue_events findet."

Let me correct the above in the final answer.

Related MCP server: address-intel-api

Bekannte asset_name-Schreibwendungen (beim Entwickeln gefunden, echte Daten)

revenue_events.asset_name ist in positiver Form nicht konsistent im Katalog kebab-case -- z.. B. ist der real gespeicherte value des Similarity Search Asset "Similarity Search API" (Anzeige-Schreibform) and not similarity-search-api. Aufrufer müssen die exact gespeicherte character string übergeben, sonst returns beanbeiter die RP function PAYMENT_NOT_FOUND (korrekt, not a bug). In revenue_events bislang: document-conversion-api, live-entity-verification, agent-verification-api, url-metadata-api, Similarity Search API, ws.

Die signierte Quittung

signature ist ein HMAC-SHA256 (hex) über die kanonische JSON-Kodierung des receipt, geführt mit NEXUS_RECEIPT_SIGNING_KEY. Das ist kein offline verifizierbare Signatur (dafür would man asymmetrische Krypto + einen published öffentlichen Schlüssel benötigen -- bewusst weggelassen, see „Bekannte Einschränkungen"): Ein Inhaber belegt die Authentifizierung, indem das dafür verantwortliche kostenlose Assets POST /verify-receipt-signature aufrufen, der den HMAC serverseitig noch einmal prüft. Bei Drehung von NEXUS_RECEIPT_SIGNING_KEY wird jede alte Quittung ungültig.

Deploy Ziel: Cloud Run

Same pipeline wie Kandidaten #4/#3/#6 -- siehe skills/infra-deploy-ops.

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh x402-receipt-verifier manual_assets/x402-receipt-verifier

# 2. Grab the printed *.run.app URL, then (only if it differs from env-vars.deploy.yaml's guess):
gcloud run services update x402-receipt-verifier --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

Bekannte Grenzen (bewusst nicht behoben -- in CLAUDE.md SS3, kein Gate ohne Beweis, notwendig)

• MCP-Tool-Aufrufe sind nicht kostenpflichtig -No in-process call pattern like all other manual assets in this codebase (url-metadata-api, agent-verification-api, document-conversion-api).

• Receipt-Signatur erfordert eine Online- Finanzielle asymmetric Offline check — siehe oben.

• Die Korrelation ist eine Zeitfenster-Heuristik, kein harter Link. weder revenueevents noch traffic_evens speichert eine gemeinsame Korrelation ID, daher bedeutet VERIFIED_DELIVERY „eine erfolgreiche Anfrage zu dem Asset war within the window nach der Zahlung“, nicht "diese exacte Anfrage wurde durch diese actualle Transaktion gefunden". On a sparse asset is this effectively exact; on a stark frequentierte mit performed numerous synchronous callers it would be ambiguous. Such candidate_successful_calls ( directly on the receipt located, see PaymentReceipt in main.py) zeigen >1 in that case in `. Event in the six registered assets there were no density concurrent for this scenario, end 2026-08-23.

• Payment is settled before, then RPC starts -- a real „pay for nichts“-gap, not disclosed until the 2026-08-23 gate (functional/Buyer-experience lens). If nexus_verify_payment_receipt/nexus_payer_spend_health or the RPC itself (Supabase down, RPC timeout, malformed upstream response – see _nexus_supabase_rpc's paths 502/503/504) the baster has already paid via PaymentMiddlewareABk/ PaymentMiddlewareASGI and gets an error, no answer, no refund path. Accepted only because this is Base Sepolia Testnet – no real funds at stake. Before reusing this exact payment-then-RPC pattern on any Mainnet-Asset, build in either a Supabase called check or move to a result settlement.

• An‑Key‑RPC‑Bypass. The two SQL RDS functions are granted anon (needed with PostgREST as they are at all) – a leaked SUPABASE_ANON_KEY opens direct /rest/v1/rpc/nexus_verify_payment_receipt without that Asset's x402-Custom. Accepted: the RPCs give only correlating verdicts about NEXT_ky own already public assets, documentation of no sensitive which has bypasses only the paywall. Exactly the same risk level as any of the Anon-Key use here.

• No Limit per caller. Fine for a Seven-day measurement window.

Quality gate (rollout 2026-08-22; gate since 2026-08-23 after spend-limit interruption)

Same 2-agent process as candidates #3/#4/#6 down security, function/quality/buyer-experience, run immediately after the rollout – this time the review ran until it was disrupted at night due to the monthly spend cap, and was continued and ended in the following session. Real, applied findings:

• Sicherheit (1, small): POST /verify-receipt-signature had no x402 gate nor size/depth limit, and hash a arbitrary receipt from caller for free – a common cost/availability nuisance, not into severe attack. Fixed now: 400/413 for >4096 byte or >10 depth.Body before every hash (_validate_receipt_shape, _MAX_RECEIPT_BYTES/_MAX_RECEIPT_DEPTH in main.py).

• Function / Buyer-Experience (1, medium): The payment is applied before running the RPC; thus a failure of Supabase after the payment means the client remains charged, never an answer, no refund. Not disclosed. Fixed: documented under "Known limitations" (No code change; announced for testnet; revisit before mainnet reuse of this pattern).

• Everything else did checked (SSRF-class from cand. #3, zip-bomb / thread-leak-class cand. #6, anon-key RPC overreturn, HMAC-correct, self-payment payTo-class cand. #4, sealing of IP, injection surface) survived clean – verified, not only claimed, re-read relevant code paths.

• Cosmetic low object unchanged: an unused parameter ctx: SomeContext = None (same as the existing unused in agent-verification-api / main.py, worth no deviation here) and silent clamping of window_seconds/lookback_days in the MCP path only (REST openly rejects out-of-bounds via Pydantic; the MCP path reports the substituted value back in the receipt, so it is discoverable, but not as an exact error – no current evidence for the need of a gate).

Measurement (candidate #13, seven-day window)

Seven-day window from first actual deploy (2026-08-23 -> meeting point 2026-08-30). source of truth: traffic_events / revenue_events / mcp_call_events (asset_name = 'x402-receipt-verifier'), no Cloud Logs. Day 7: if zero real trajectories (filtered crawlers) pause / delete the Cloud Run service (gcloud run services delete x402-receipt-verifier --region us-central1 --project nexus-505016).