{"openapi":"3.1.0","info":{"title":"x402 Receipt Verifier","description":"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 -- not just that a payment settled.","version":"1.0.0","contact":{"email":"dasaanrod@gmail.com"}},"paths":{"/verify-payment-receipt":{"post":{"summary":"Verify Payment Receipt Endpoint","description":"Looks up a real revenue_events row matching (asset_name, payer_address, claimed_amount_usd)\nwithin `window_seconds` of `claimed_at`, then checks traffic_events for a successful (2xx)\nrequest to that same asset within the window starting at the matched payment's real timestamp.\n\nverdict meanings:\n- VERIFIED_DELIVERY: a matching payment was found AND a successful request followed it.\n- PAYMENT_NO_DELIVERY: a matching payment was found but no successful request followed --\n  possible failed/errored call after payment, or a call outside the tolerance window.\n- PAYMENT_NOT_FOUND: no revenue_events row matches the claimed asset/payer/amount/time at all --\n  either the claim is wrong, or the payment was made through a different route than x402 REST.\n\nPayment for THIS call is settled by PaymentMiddlewareASGI before this handler runs, same as\nevery other paid route in this codebase -- a PAYMENT_NOT_FOUND or PAYMENT_NO_DELIVERY result is\nstill a charged, valid answer, not a failure of this endpoint.","operationId":"verify_payment_receipt_endpoint_verify_payment_receipt_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyPaymentReceiptRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentReceiptEnvelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}}]}}},"/payer-spend-health":{"post":{"summary":"Payer Spend Health Endpoint","description":"Aggregate delivery-confirmation rate for one payer address on one NEXUS asset over\n`lookback_days`. verdict is SUMMARY (with delivery_rate, a 0.0-1.0 fraction) or NO_PAYMENTS_FOUND.\n\nPayment for THIS call is settled by PaymentMiddlewareASGI before this handler runs, same as\nevery other paid route in this codebase -- a NO_PAYMENTS_FOUND result is still a charged,\nvalid answer, not a failure of this endpoint.","operationId":"payer_spend_health_endpoint_payer_spend_health_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayerSpendHealthRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendHealthEnvelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}}]}}},"/verify-receipt-signature":{"post":{"summary":"Verify Receipt Signature Endpoint","description":"Free. Confirms a `receipt`+`signature` pair returned by this asset is authentic (was actually\nissued by this service, unmodified) -- checks the HMAC server-side, does not require the caller\nto know the signing key. This is an online check, not an offline-verifiable signature.\n\nRejects oversized/deeply-nested bodies with 413 before any hashing work -- this route has no\nx402 gate, so it needs its own cheap bound (a real issued receipt is a flat dict well under the\n4096-byte cap).","operationId":"verify_receipt_signature_endpoint_verify_receipt_signature_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyReceiptSignatureRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySignatureResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PayerSpendHealthRequest":{"properties":{"asset_name":{"type":"string","maxLength":120,"minLength":1,"title":"Asset Name"},"payer_address":{"type":"string","title":"Payer Address"},"lookback_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Lookback Days","default":30}},"type":"object","required":["asset_name","payer_address"],"title":"PayerSpendHealthRequest"},"PaymentReceipt":{"properties":{"receipt_type":{"type":"string","const":"x402_payment_delivery_verification","title":"Receipt Type"},"asset_name":{"type":"string","title":"Asset Name"},"payer_address":{"type":"string","title":"Payer Address"},"claimed_amount_usd":{"type":"number","title":"Claimed Amount Usd"},"claimed_at":{"type":"string","title":"Claimed At"},"window_seconds":{"type":"integer","title":"Window Seconds"},"verdict":{"type":"string","enum":["VERIFIED_DELIVERY","PAYMENT_NO_DELIVERY","PAYMENT_NOT_FOUND"],"title":"Verdict","description":"VERIFIED_DELIVERY / PAYMENT_NO_DELIVERY / PAYMENT_NOT_FOUND -- see POST /verify-payment-receipt's own description for full semantics."},"matched_revenue_event":{"type":"boolean","title":"Matched Revenue Event"},"delivery_confirmed":{"type":"boolean","title":"Delivery Confirmed"},"candidate_successful_calls":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidate Successful Calls","description":"Count of successful (2xx) requests to this asset found within the window after the matched payment -- >1 means the correlation was ambiguous among several concurrent calls, see README 'Known limitations'."},"payment_timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Timestamp","description":"Real timestamp of the matched revenue_events row, null if verdict is PAYMENT_NOT_FOUND."},"issued_at":{"type":"string","title":"Issued At"},"signing_key_id":{"type":"string","title":"Signing Key Id"}},"type":"object","required":["receipt_type","asset_name","payer_address","claimed_amount_usd","claimed_at","window_seconds","verdict","matched_revenue_event","delivery_confirmed","issued_at","signing_key_id"],"title":"PaymentReceipt"},"PaymentReceiptEnvelope":{"properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"},"signature":{"type":"string","title":"Signature","description":"Hex-encoded HMAC-SHA256 over the canonical JSON of `receipt`. Verify authenticity via POST /verify-receipt-signature (free) -- this is NOT an offline-verifiable signature, see README 'Known limitations'."}},"type":"object","required":["receipt","signature"],"title":"PaymentReceiptEnvelope"},"SpendHealthEnvelope":{"properties":{"receipt":{"$ref":"#/components/schemas/SpendHealthReceipt"},"signature":{"type":"string","title":"Signature","description":"Hex-encoded HMAC-SHA256 over the canonical JSON of `receipt`. Verify authenticity via POST /verify-receipt-signature (free) -- this is NOT an offline-verifiable signature, see README 'Known limitations'."}},"type":"object","required":["receipt","signature"],"title":"SpendHealthEnvelope"},"SpendHealthReceipt":{"properties":{"receipt_type":{"type":"string","const":"x402_payer_spend_health_summary","title":"Receipt Type"},"asset_name":{"type":"string","title":"Asset Name"},"payer_address":{"type":"string","title":"Payer Address"},"lookback_days":{"type":"integer","title":"Lookback Days"},"verdict":{"type":"string","enum":["SUMMARY","NO_PAYMENTS_FOUND"],"title":"Verdict","description":"SUMMARY (fields below populated) or NO_PAYMENTS_FOUND."},"total_payments":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Payments"},"delivery_confirmed_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Delivery Confirmed Count"},"delivery_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delivery Rate","description":"Fraction 0.0-1.0 (NOT a percentage) of total_payments with a confirmed successful delivery."},"first_payment_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Payment At"},"last_payment_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Payment At"},"issued_at":{"type":"string","title":"Issued At"},"signing_key_id":{"type":"string","title":"Signing Key Id"}},"type":"object","required":["receipt_type","asset_name","payer_address","lookback_days","verdict","issued_at","signing_key_id"],"title":"SpendHealthReceipt"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyPaymentReceiptRequest":{"properties":{"asset_name":{"type":"string","maxLength":120,"minLength":1,"title":"Asset Name","description":"NEXUS asset name exactly as it appears in revenue_events.asset_name -- see README 'Known asset_name spellings' for the real values (they are not all consistently kebab-case)."},"payer_address":{"type":"string","title":"Payer Address","description":"EVM address that made the payment ('0x' + 40 hex chars)."},"claimed_amount_usd":{"type":"number","exclusiveMinimum":0.0,"title":"Claimed Amount Usd","description":"Amount the caller claims was paid, in USD."},"claimed_at":{"type":"string","title":"Claimed At","description":"ISO-8601 timestamp the caller claims the payment happened at."},"window_seconds":{"type":"integer","maximum":3600.0,"minimum":1.0,"title":"Window Seconds","description":"Tolerance window (seconds) for matching claimed_at against the real payment timestamp, and for matching the payment against a nearby successful request.","default":120}},"type":"object","required":["asset_name","payer_address","claimed_amount_usd","claimed_at"],"title":"VerifyPaymentReceiptRequest"},"VerifyReceiptSignatureRequest":{"properties":{"receipt":{"additionalProperties":true,"type":"object","title":"Receipt","description":"The exact `receipt` object returned by a prior call."},"signature":{"type":"string","title":"Signature","description":"The exact `signature` string returned alongside that receipt."}},"type":"object","required":["receipt","signature"],"title":"VerifyReceiptSignatureRequest"},"VerifySignatureResponse":{"properties":{"valid":{"type":"boolean","title":"Valid"}},"type":"object","required":["valid"],"title":"VerifySignatureResponse"}}}}