{ "openapi": "3.1.0", "info": { "title": "402xAgent: x402 pre-payment checks + verified catalog", "version": "0.42.1", "contact": { "url": "https://github.com/withgrokbot/verified-catalog/issues" }, "x-guidance": "Ask GET /v1/lookup?task=&max_price= (task names: /v1/tasks). 5 free calls per client per UTC day, then the same path answers 402; /v1/lookup/paid is the always-paid twin ($0.02 USDC on Base via x402) with identical results. Products: GET /v1/products/overnight-cos-pack ($9 USDC); GET /v1/products/endpoint-spot-check (5 free/day (25 per network) then $0.02 USDC a check, SSRF-safe x402 probe). Free MCP: POST /mcp.", "description": "Start free: GET https://api.402xagent.com/v1/products/endpoint-spot-check?url= (5 free checks per client per UTC day (at most 25 per network); free dry runs with &mode=dry-run). Real example: GET https://api.402xagent.com/v1/products/endpoint-spot-check?url=https://api.402rates.com/v1/ping -> {\"verdict\":\"pay\",\"reason\":\"listed $0.001, payment request matches the listed price\",\"receipt_url\":\"https://402xagent.com/v1/receipts/sc-1373dc485641b938\"}. Prior checks: https://402xagent.com/v1/skips. Then, only for the full payment terms: the paid check (HTTP 402, $0.02 USDC on Base via x402). Also: is an x402 endpoint reliable for task X at price <= Y? Facts from our own paid calls: receipts with settlement tx, delivered yes/no and a known-answer pass/fail. Pricing: 5 free lookups per client per UTC day, then HTTP 402 with an x402 payment requirement of $0.02 USDC on Base per lookup. Payment buys query access only. It never changes results, sort order, listings, check results or known-answer outcomes: free, paid and exempt lookups run the same code on the same data and get identical results. Not investment advice; we hold no customer funds." }, "servers": [ { "url": "https://api.402xagent.com", "description": "402xAgent API (canonical)" }, { "url": "https://402xagent.com", "description": "402xAgent (same API on the apex)" }, { "url": "https://verified-catalog-lookup.withgrokbot.workers.dev", "description": "legacy host (same Worker, still supported; older hosts keep answering API calls too)" } ], "paths": { "/v1/lookup": { "get": { "operationId": "lookup", "security": [], "summary": "Services for a task at or under a price, sorted by known-answer pass rate over the last n paid calls, then price", "parameters": [ { "name": "task", "in": "query", "schema": { "type": "string" }, "description": "task name, e.g. web-search (see /v1/tasks)" }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "maximum listed price per call, USD" }, { "name": "n", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }, "description": "paid receipts per service" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "description": "services returned" }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "a service id or endpoint URL" }, { "name": "client", "in": "query", "schema": { "type": "string" }, "description": "your agent or app name (optional)" }, { "name": "ref", "in": "query", "schema": { "type": "string" }, "description": "where you found this lookup, e.g. via-readme (optional, attribution only)" }, { "name": "payer", "in": "query", "schema": { "type": "string" }, "description": "your 0x wallet, if you want to report which vendor you paid (optional)" } ], "responses": { "200": { "description": "results (sorted), facts_only (broken on the seller's side, not sorted), access (free, paid or exempt). Identical results whether the call was free or paid. Paid calls carry a PAYMENT-RESPONSE header with the settlement tx." }, "400": { "description": "bad parameters (never metered)" }, "402": { "description": "free lookups used up for today: x402 v2 payment requirement in the PAYMENT-REQUIRED header (base64 JSON) and the body. Pay by retrying with a PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT header. $0.02 USDC on Base, payTo 0x37cfCC8a29e9ff9458902B29E31E42dc7B718674. Payment buys query access only. It never changes results, sort order, listings, check results or known-answer outcomes: free, paid and exempt lookups run the same code on the same data and get identical results." } } } }, "/v1/lookup/paid": { "get": { "operationId": "lookupPaid", "summary": "Same lookup as /v1/lookup, always paid: $0.02 USDC on Base per call via x402 (no free quota). Identical results.", "parameters": [ { "name": "task", "in": "query", "schema": { "type": "string" }, "description": "task name, e.g. web-search (see /v1/tasks); task or endpoint is required" }, { "name": "max_price", "in": "query", "schema": { "type": "string" }, "description": "maximum listed price per call, USD, e.g. 0.01" }, { "name": "n", "in": "query", "schema": { "type": "string" }, "description": "paid receipts per service, 1-20 (default 5)" }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "description": "services returned, 1-20 (default 10)" }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "a service id or endpoint URL instead of a task" }, { "name": "client", "in": "query", "schema": { "type": "string" }, "description": "your agent or app name (optional)" }, { "name": "ref", "in": "query", "schema": { "type": "string" }, "description": "where you found this lookup (optional, attribution only)" }, { "name": "payer", "in": "query", "schema": { "type": "string" }, "description": "your 0x wallet (optional)" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x37cfCC8a29e9ff9458902B29E31E42dc7B718674" } } ] }, "responses": { "200": { "description": "same body as /v1/lookup, access.tier = paid, PAYMENT-RESPONSE header with the settlement tx" }, "400": { "description": "bad parameters (checked after the 402, before anything is settled)" }, "402": { "description": "x402 v2 payment requirement ($0.02 USDC on Base) with Bazaar discovery metadata. Payment buys query access only. It never changes results, sort order, listings, check results or known-answer outcomes: free, paid and exempt lookups run the same code on the same data and get identical results." } } } }, "/v1/products/overnight-cos-pack": { "get": { "operationId": "getOvernightCosPack", "summary": "Overnight Chief of Staff Setup Pack: prompts, HTML template, and PDF guide ($9 USDC on Base via x402, always paid)", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "9" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x37cfCC8a29e9ff9458902B29E31E42dc7B718674" } } ] }, "responses": { "200": { "description": "JSON with product, title, price_usdc, files.prompts, files.templates, files.guide (PDF base64), access/settlement" }, "402": { "description": "x402 v2 payment requirement ($9 USDC on Base) with Bazaar discovery metadata for the Overnight CoS Setup Pack" } } }, "post": { "operationId": "getOvernightCosPackPost", "summary": "Same as GET /v1/products/overnight-cos-pack (POST accepted for discovery probes)", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "9" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x37cfCC8a29e9ff9458902B29E31E42dc7B718674" } } ] }, "responses": { "200": { "description": "same as GET" }, "402": { "description": "same as GET" } } } }, "/v1/products/payment-status": { "post": { "operationId": "paymentStatus", "summary": "After-payment check (Base USDC, EIP-3009): did the payment land, and is it safe to sign a new one? Same price ($0.02) and the same 5 free/day as the check. A bare request answers the x402 402.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_payload": { "type": "string", "description": "base64 PAYMENT-SIGNATURE (v2) / X-PAYMENT (v1) value of the payment you sent (exact EIP-3009 USDC on Base)" }, "tx_hash": { "type": "string", "description": "settle tx hash, if you have one" }, "from": { "type": "string" }, "nonce": { "type": "string", "description": "EIP-3009 nonce (0x + 32 bytes), with from" }, "valid_before": { "type": "string", "description": "unix seconds; needed for safe_to_resign when sending from + nonce without the payload" }, "seller_url": { "type": "string", "description": "the URL you paid (terms match + claim contacts)" }, "terms": { "type": "object", "description": "optional: the 402 terms you paid against {amount, payTo, asset, network}" }, "network": { "type": "string", "enum": [ "eip155:8453" ] }, "asset": { "type": "string" }, "client": { "type": "string" }, "ref": { "type": "string" } } }, "example": { "payment_payload": "", "seller_url": "https://seller.example/api/x" } } } }, "responses": { "200": { "description": "status landed|not_landed|pending|canceled|unknown, reason, safe_to_retry_same_payload (always true), safe_to_resign (strict two-source + expiry rule), wait_until, authorization, tx, terms_match, claim, cannot_know, finality, rpc, receipt (signed copy), access", "content": { "application/json": { "example": { "id": "ps-0123456789abcdef", "type": "payment-status", "status": "not_landed", "reason": "expired_unused", "safe_to_retry_same_payload": true, "safe_to_resign": true, "why": "two independent sources (alchemy, rpc2) agree the nonce is unused and the chain is past validBefore + 120s: this authorization can never settle, so a new payment cannot double-charge", "wait_until": null, "authorization": { "from": "0x...", "nonce": "0x...", "used_onchain": false, "event": null, "valid_before": "2026-10-16T17:05:00Z", "expired": true }, "tx": null, "terms_match": { "amount": "match", "pay_to": "match", "asset": "match", "network": "match", "source": "payment_payload", "compared": "authorization" }, "finality": { "confirmations": null, "min_confirmations": 10, "reorg_safe": false }, "rpc": { "sources": [ { "name": "alchemy", "ok": true, "head": 36000000 }, { "name": "rpc2", "ok": true, "head": 36000000 } ], "sources_agreed": 2 }, "receipt": "{ same fields + kid + signature (ed25519 over JCS) }", "access": { "tier": "free", "free_per_day": 5, "free_used_today": 1 } } } } }, "400": { "description": "missing_reference | bad_payload | bad_from | bad_nonce | bad_tx_hash | inconsistent | unsupported_network | unsupported_asset | bad_seller_url | bad_body" }, "402": { "description": "x402 v2 payment required (bare request, or free checks used up); amount 20000 USDC atomic on Base" }, "503": { "description": "chain_unavailable: no RPC source answered; nothing charged, no free check used" } } }, "get": { "operationId": "paymentStatusGet", "summary": "Same as POST with query params (payment_payload, tx_hash, from, nonce, valid_before, seller_url)", "responses": { "200": { "description": "see POST" }, "402": { "description": "see POST" } } } }, "/v1/products/endpoint-spot-check": { "get": { "operationId": "endpointSpotCheck", "summary": "Decision-shaped 402xAgent check: probe a public URL for PAYMENT-REQUIRED (never pays the target). Returns verdict/reason/quoted vs claimed. 5 free/client/UTC day (25/network), then $0.02 USDC a check on Base", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "public http(s) URL to probe" }, { "name": "task", "in": "query", "schema": { "type": "string" } }, { "name": "claimed_price", "in": "query", "schema": { "type": "number" }, "description": "optional claimed USD price to compare against quoted challenge" }, { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "GET", "POST" ], "default": "GET" }, "description": "how to probe the target (POST sends an empty JSON body; for POST-only x402 endpoints)" }, { "name": "pay_to", "in": "query", "schema": { "type": "string" }, "description": "optional wallet you expect to pay (from your listing); a 402 paying elsewhere is skip/pay_to_mismatch. Defaults to the listing in our crawl when we have one" }, { "name": "network", "in": "query", "schema": { "type": "string" }, "description": "optional CAIP-2 network you expect (e.g. eip155:8453 or solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp); a 402 on another network is skip/network_mismatch" }, { "name": "client", "in": "query", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "schema": { "type": "string" }, "description": "attribution tag, stored on the receipt; ref=dry-run- sets mode=dry-run" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "live", "dry-run" ], "default": "live" }, "description": "free dry run: one unpaid probe, nothing signed or paid, always stored as a public receipt (check_type dry-run). Returns the free-tier shape with payment_terms_sha256 null (never an approval). 50 per caller (ref, else client, else IP) per UTC day. ref=dry-run- also sets it" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02", "amount_atomic": "20000" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x37cfCC8a29e9ff9458902B29E31E42dc7B718674" } } ] }, "responses": { "200": { "description": "No 402 terms is skip/no_paywall (recheck/free_trial_active when the target sends x-free-trial headers); recheck only for timeouts, 5xx and network errors; wrong or unsupported network, non-canonical USDC or a pay_to that differs from the listing is skip. The same normalized URL + method reuses one probe for 5 min, so consecutive calls agree. Free tier: verdict (pay|skip|recheck), a plain-words reason, access. Paid tier: verdict, reason code, quoted_price_usd, claimed_price_usd, pay_to, network, asset, payment (the exact signable payment when verdict is pay), payment_terms_sha256, access (with settlement tx). Free tier also carries payment_terms_sha256", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "paid response: decision plus the facts behind it", "properties": { "verdict": { "type": "string", "enum": [ "pay", "skip", "recheck" ] }, "reason": { "type": "string", "enum": [ "price_ok", "price_below_listing", "price_mismatch", "network_mismatch", "pay_to_mismatch", "asset_not_usdc", "network_unsupported", "no_paywall", "free_trial_active", "timeout", "unreachable", "server_error", "bad_challenge", "ssrf_blocked" ] }, "free_trial_remaining": { "type": [ "integer", "null" ], "description": "reason free_trial_active only: the seller's x-free-trial-remaining, when parseable" }, "quoted_price_usd": { "type": [ "number", "null" ], "description": "price in the target's live 402 challenge" }, "claimed_price_usd": { "type": [ "number", "null" ], "description": "the claimed_price you sent" }, "pay_to": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "asset": { "type": [ "string", "null" ] }, "expected_pay_to": { "type": [ "string", "null" ], "description": "the pay_to you sent, else the listing's (from our crawl), else null" }, "expected_network": { "type": [ "string", "null" ] }, "expected_source": { "type": [ "string", "null" ], "enum": [ "request", "listing", null ] }, "payment": { "type": [ "object", "null" ], "description": "verdict pay only: THE payment a router may sign, from the live 402, checked against the listing: network (supported mainnet, CAIP-2), asset (that network's canonical USDC contract), amount {atomic, usd}, pay_to, deadline (UTC; validBefore, else probed_at + maxTimeoutSeconds, else + 60 s). Sign nothing else. scheme / amount_atomic / amount_usd / asset_is_usdc are kept for older clients.", "properties": { "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "object", "properties": { "atomic": { "type": "string" }, "usd": { "type": [ "number", "null" ] } }, "required": [ "atomic", "usd" ] }, "pay_to": { "type": "string" }, "deadline": { "type": "string", "format": "date-time" }, "deadline_source": { "type": "string", "enum": [ "validBefore", "maxTimeoutSeconds", "default_60s" ] }, "scheme": { "type": "string" }, "asset_is_usdc": { "type": [ "boolean", "null" ] }, "amount_atomic": { "type": "string" }, "amount_usd": { "type": [ "number", "null" ] } }, "required": [ "network", "asset", "amount", "pay_to", "deadline" ] }, "probe": { "type": "object", "description": "the live probe this decision used: probed_at, cached (true = reused within cache_ttl_s for the same normalized URL + method, so consecutive calls agree)", "properties": { "probed_at": { "type": "string" }, "cached": { "type": "boolean" }, "cache_ttl_s": { "type": "integer" }, "method_used": { "type": "string", "description": "present only when the listed GET answered 405 and the 402 came from POST" } } }, "check_type": { "type": "string", "enum": [ "dry-run", "self-checked" ], "description": "receipt label: self-checked for our own self-test client, dry-run for everyone else" }, "payment_terms_sha256": { "type": [ "string", "null" ], "description": "sha256 hex of lower-case network|asset|amount_atomic|pay_to (null unless pay)" }, "receipt_id": { "type": [ "string", "null" ], "description": "public receipt id for this decision (sc-...)" }, "receipt_url": { "type": [ "string", "null" ], "description": "free, public: GET it to show as the reason for paying or aborting" }, "pay_to_changed": { "type": [ "boolean", "null" ], "description": "true if the wallet differs from the previous receipt for this URL (same network); null if there is nothing to compare. A flag only: the verdict is unchanged." }, "reason_code": { "type": [ "string", "null" ], "description": "0.30.0 stable machine code for the verdict (see /rules.json); in free answers `reason` is plain words, here is the code" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "0.30.0 confidence in the verdict; rules at /rules.json" }, "history_observations": { "type": [ "array", "null" ], "description": "0.34.0, paid / router / exempt answers only: the last 30 observations of this endpoint, newest first (observed_at, http_status, price_usd, amount_atomic, network, asset, pay_to). Free answers, dry runs and receipts keep only the history summary.", "items": { "type": "object" } }, "history": { "type": [ "object", "null" ], "description": "0.29.0 summary of the last 30 observations of this endpoint (D1; price, wallet and network are not shown). stable_for_days = whole days the payment terms (price, network, asset, pay_to) have been the same; stable_since/last_changed = when the current terms were first seen (last_changed null if they never changed in the kept history); drift = the terms differ from the previous observation (null if nothing to compare). Observations without payment terms (timeouts, errors) do not reset stability. null when the store is unavailable.", "properties": { "observations": { "type": "integer" }, "stable_for_days": { "type": [ "integer", "null" ] }, "stable_since": { "type": [ "string", "null" ] }, "last_changed": { "type": [ "string", "null" ] }, "drift": { "type": [ "boolean", "null" ] } } }, "quality": { "type": [ "object", "null" ], "description": "0.37.0 (additive): quality of the unpaid 402 response (metadata only; codes at /rules.json quality_codes). Never changes verdict or reason_code.", "properties": { "code": { "type": "string", "enum": [ "quality_ok", "quality_unverified", "quality_bad_content_type", "quality_schema_mismatch", "quality_bad_status", "quality_unreachable" ] }, "checks": { "type": "object" } } }, "reputation": { "type": [ "object", "null" ], "description": "0.37.0 (additive): seller host reputation 0..100 (formula and weights at /rules.json reputation): score (null when low on data), band, confidence, low_data, provisional_score, breakdown, inputs. null when the store is unavailable.", "properties": { "host": { "type": "string" }, "score": { "type": [ "integer", "null" ] }, "band": { "type": "string", "enum": [ "high", "medium", "low", "insufficient_data" ] } } }, "access": { "type": "object", "properties": { "tier": { "const": "paid" }, "charged_usd": { "type": "string" }, "tx": { "type": "string" } } } }, "required": [ "verdict", "reason", "quoted_price_usd", "claimed_price_usd", "pay_to", "network", "asset", "expected_pay_to", "expected_network", "expected_source", "payment", "payment_terms_sha256", "probe", "check_type", "receipt_id", "receipt_url", "access" ] }, { "type": "object", "description": "free response (1 per client per UTC day): verdict and a plain-words reason only", "properties": { "verdict": { "type": "string", "enum": [ "pay", "skip", "recheck" ] }, "reason": { "type": "string", "description": "plain words, e.g. 'listed $0.01, no x402 payment request at this URL'" }, "payment_terms_sha256": { "type": [ "string", "null" ], "description": "sha256 hex of lower-case network|asset|amount_atomic|pay_to of the approved payment (null unless pay)" }, "receipt_id": { "type": [ "string", "null" ], "description": "public receipt id for this decision (sc-...)" }, "receipt_url": { "type": [ "string", "null" ], "description": "free, public: GET it to show as the reason for paying or aborting" }, "pay_to_changed": { "type": [ "boolean", "null" ], "description": "true if the wallet differs from the previous receipt for this URL (same network); null if there is nothing to compare. A flag only: the verdict is unchanged." }, "reason_code": { "type": [ "string", "null" ], "description": "0.30.0 stable machine code for the verdict (see /rules.json); in free answers `reason` is plain words, here is the code" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "0.30.0 confidence in the verdict; rules at /rules.json" }, "history": { "type": [ "object", "null" ], "description": "0.29.0 summary of the last 30 observations of this endpoint (D1; price, wallet and network are not shown). stable_for_days = whole days the payment terms (price, network, asset, pay_to) have been the same; stable_since/last_changed = when the current terms were first seen (last_changed null if they never changed in the kept history); drift = the terms differ from the previous observation (null if nothing to compare). Observations without payment terms (timeouts, errors) do not reset stability. null when the store is unavailable.", "properties": { "observations": { "type": "integer" }, "stable_for_days": { "type": [ "integer", "null" ] }, "stable_since": { "type": [ "string", "null" ] }, "last_changed": { "type": [ "string", "null" ] }, "drift": { "type": [ "boolean", "null" ] } } }, "quality": { "type": [ "object", "null" ], "description": "0.37.0 (additive): {code} of the unpaid 402 response's quality check (codes at /rules.json); full checks in the paid answer", "properties": { "code": { "type": "string" }, "rules": { "type": "string" } } }, "reputation": { "type": [ "object", "null" ], "description": "0.37.0 (additive): coarse seller band only: high | medium | low | insufficient_data; score and breakdown in the paid answer", "properties": { "host": { "type": "string" }, "band": { "type": "string", "enum": [ "high", "medium", "low", "insufficient_data" ] }, "rules": { "type": "string" } } }, "access": { "type": "object", "properties": { "tier": { "const": "free" } } } }, "required": [ "verdict", "reason", "payment_terms_sha256", "receipt_id", "receipt_url", "access" ], "additionalProperties": false } ] }, "examples": { "paid": { "value": { "verdict": "pay", "reason": "price_ok", "quoted_price_usd": 0.05, "claimed_price_usd": 0.05, "pay_to": "0x1111111111111111111111111111111111111111", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "expected_pay_to": "0x1111111111111111111111111111111111111111", "expected_network": "eip155:8453", "expected_source": "request", "payment": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": { "atomic": "50000", "usd": 0.05 }, "pay_to": "0x1111111111111111111111111111111111111111", "deadline": "2026-10-10T17:05:00Z", "deadline_source": "maxTimeoutSeconds", "scheme": "exact", "amount_atomic": "50000", "amount_usd": 0.05, "asset_is_usdc": true }, "payment_terms_sha256": "", "probe": { "probed_at": "2026-10-10T17:00:00Z", "cached": false, "cache_ttl_s": 300 }, "check_type": "dry-run", "receipt_id": "sc-0123456789abcdef", "receipt_url": "https://402xagent.com/v1/receipts/sc-0123456789abcdef", "pay_to_changed": false, "reason_code": "price_ok", "confidence": "high", "history": { "observations": 12, "stable_for_days": 9, "stable_since": "2026-10-01T17:00:00Z", "last_changed": "2026-10-01T17:00:00Z", "drift": false }, "history_observations": [ { "observed_at": "2026-10-10T17:00:00Z", "http_status": 402, "price_usd": 0.05, "amount_atomic": "50000", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "pay_to": "0x..." } ], "quality": { "code": "quality_unverified", "checks": { "reachable": true, "http_status": 402, "status_is_402": true, "content_type": "application/json", "content_type_ok": true, "body_bytes": 612, "schema_declared": false, "schema_source": null, "schema_match": null }, "note": "metadata of the unpaid 402 response only; never pays the seller, stores no body; does not change verdict or reason_code", "rules": "https://402xagent.com/rules.json" }, "reputation": { "host": "api.example.com", "score": 86, "band": "high", "confidence": "medium", "low_data": false, "breakdown": { "stability": { "value": 1, "weight": 25, "points": 25 }, "drift": { "value": 1, "weight": 20, "points": 20 }, "verdicts": { "value": 0.795, "weight": 30, "points": 23.85 }, "freshness": { "value": 1, "weight": 10, "points": 10 }, "quality": { "value": 0.45, "weight": 15, "points": 6.75 } }, "capped": false, "inputs": { "endpoints": 2, "observations": 14, "checks_30d": 14, "pay_30d": 12, "skip_30d": 2, "recheck_30d": 0, "term_transitions": 10, "pay_to_changes": 0, "network_or_asset_changes": 0, "price_changes": 0, "stable_for_days_min": 9, "stable_for_days_max": 9, "last_checked": "2026-10-10T17:00:00Z", "first_seen": "2026-10-01T17:00:00Z", "tracking_days": 9, "quality_codes": { "quality_unverified": 1, "quality_bad_status": 1 } }, "formula_version": "2026-10-15", "rules": "https://402xagent.com/rules.json" }, "access": { "tier": "paid", "charged_usd": "0.01", "asset": "USDC on Base", "tx": "0x...", "basescan_url": "https://basescan.org/tx/0x...", "payer": "0x..." } } }, "free": { "value": { "verdict": "pay", "reason": "listed $0.05, payment request matches the listed price", "payment_terms_sha256": "", "receipt_id": "sc-0123456789abcdef", "receipt_url": "https://402xagent.com/v1/receipts/sc-0123456789abcdef", "pay_to_changed": false, "reason_code": "price_ok", "confidence": "high", "history": { "observations": 12, "stable_for_days": 9, "stable_since": "2026-10-01T17:00:00Z", "last_changed": "2026-10-01T17:00:00Z", "drift": false }, "quality": { "code": "quality_unverified", "rules": "https://402xagent.com/rules.json" }, "reputation": { "host": "api.example.com", "band": "high", "rules": "https://402xagent.com/rules.json" }, "prior_checks": "https://402xagent.com/v1/skips", "upsell": "Full 402 details (exact payment terms, pay_to, deadline) for this endpoint for $0.02", "access": { "tier": "free", "free_per_day": 5, "free_used_today": 1, "free_remaining_today": 4, "then": "$0.02 USDC on Base for the full check of this endpoint via x402 (HTTP 402)" } } } } } } }, "400": { "description": "bad params, or SSRF-blocked URL as verdict=skip reason=ssrf_blocked (no fetch)" }, "402": { "description": "free quota used: x402 v2 payment requirement ($0.02 USDC on Base, amount 20000)" }, "429": { "description": "paid rate limit (per payer per UTC hour), or (0.33.0) the free-check network cap: 25 free live checks per network per UTC day across all client names; JSON points to the paid check and the router pack; Retry-After = seconds to 00:00 UTC" } } }, "post": { "operationId": "endpointSpotCheckPost", "summary": "Same as GET /v1/products/endpoint-spot-check (JSON body may carry url, task, claimed_price, client, ref)", "responses": { "200": { "description": "same as GET" }, "400": { "description": "same as GET" }, "402": { "description": "same as GET" } } } }, "/v1/skips": { "get": { "operationId": "skips", "security": [], "summary": "Free: public page of self-checked x402 endpoints whose 402 disagrees with their listing (verdict skip). HTML; ?format=json or /v1/skips.json for JSON. Each row has an anchor #.", "responses": { "200": { "description": "HTML or JSON list of skip receipts with totals and crawl time" } } } }, "/badge/{host}.svg": { "get": { "operationId": "statusBadge", "security": [], "summary": "Free SVG status badge for a host (or ?path= for one endpoint). Green 'pay ยท stable N days' only when the latest stored live verdict is pay and under 72 h old (and, for a host, no other endpoint on it has a fresher non-pay); otherwise grey 'stale' or 'not verified'. Never fetches the host, one D1 read, Cache-Control max-age=300. /badge/{host} (no .svg) is a small HTML page with the current status, the receipt link (redacted public view) and the embed snippets. Embed: [![402xAgent status](https://402xagent.com/badge/{host}.svg)](https://402xagent.com/badge/{host}).", "parameters": [ { "name": "host", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "400": { "description": "invalid host (grey SVG)" } } } }, "/saves": { "get": { "operationId": "savesPage", "security": [], "summary": "Free: endpoints from the last 30 days where a live x402 402 differed from the listing (price above the listing by more than 1%, a different pay_to shown only as 'pays a different wallet', or a different network). Endpoint without query, what differed, date, redacted receipt link. HTML; JSON at /saves.json.", "responses": { "200": { "description": "HTML saves list" } } } }, "/saves.json": { "get": { "operationId": "savesJson", "security": [], "summary": "Free: the saves list as JSON (count, counts by kind, saves[{endpoint, kind, what, date, source, receipt}]). Wallets are never included.", "responses": { "200": { "description": "JSON saves", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/rules": { "get": { "operationId": "rulesPage", "security": [], "summary": "Free: the verdict rules: every reason_code with its verdict and default confidence, and the confidence rules (high|medium|low). HTML; JSON at /rules.json.", "responses": { "200": { "description": "HTML rules page" } } } }, "/rules.json": { "get": { "operationId": "rulesJson", "security": [], "summary": "Free: machine-readable verdict rules (rules_version, reason_codes[{code, verdict, confidence, rule, text}], confidence.rules; 0.37.0: quality_codes and reputation {formula, weights, components, bands}).", "responses": { "200": { "description": "JSON rules", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/reputation/{host}": { "get": { "operationId": "reputationBand", "security": [], "summary": "Free (0.37.0): coarse seller reputation band for a host: high | medium | low | insufficient_data. HTML for browsers; JSON with Accept: application/json or /reputation/{host}.json. Score, breakdown and inputs are in paid / router answers (reputation). Formula at /rules.json.", "parameters": [ { "name": "host", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "band", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string" }, "band": { "type": "string", "enum": [ "high", "medium", "low", "insufficient_data" ] } } } } } }, "400": { "description": "not a host" } } } }, "/bazaar": { "get": { "operationId": "bazaarPage", "security": [], "summary": "Free: our daily check of the top public CDP Bazaar search results for a few common queries (endpoint without query string, verdict, short reason, public receipt). HTML for browsers; JSON otherwise.", "responses": { "200": { "description": "HTML (Accept: text/html) or the same JSON as /bazaar.json" } } } }, "/bazaar.json": { "get": { "operationId": "bazaarJson", "security": [], "summary": "Free: JSON of /bazaar: generated_at, queries, counts {pay, skip, recheck}, rows [{query, rank, service, endpoint, method, verdict, reason, reason_text, receipt_url}].", "responses": { "200": { "description": "Bazaar check snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "generated_at": { "type": [ "string", "null" ] }, "queries": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object" }, "rows": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/receipts/by-url": { "get": { "operationId": "receiptByUrl", "security": [], "summary": "Free: latest public receipt for a URL: latest_live (last live 402xAgent decision: live 402 terms, verdict, reason, timestamp, id) and latest_crawl (weekly self-checked crawl). A fresh live check is a paid 402xAgent check.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "the listing/endpoint URL exactly as checked" } ], "responses": { "200": { "description": "receipts" }, "400": { "description": "missing url" }, "404": { "description": "no receipt for this url yet (check_now link included)" } } } }, "/v1/receipts/{id}": { "get": { "operationId": "receiptById", "security": [], "summary": "Free: one receipt. sc-<16 hex> = a live 402xAgent decision (url, method, checked_at, verdict, reason, live_402 accepts, expected, approved_payment, payment_terms_sha256); 10-hex ids = weekly crawl receipts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "receipt JSON" }, "404": { "description": "unknown id" } } } }, "/v1/receipts": { "get": { "operationId": "receipts", "security": [], "summary": "Free: every self-checked receipt (url, claimed_price_usd, quoted_price_usd, pay_to, verdict, reason, timestamp, source_list). /v1/receipts/{id} returns one receipt. With type=dry-run or type=live: stored 402xAgent decisions, newest first (url, listing, live_demand, verdict, reason, checked_at, check_type, ref), filter by ref, page with limit (1-100, default 20) and cursor (next_cursor).", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "dry-run", "live" ] }, "description": "list stored 402xAgent receipts of this type" }, { "name": "ref", "in": "query", "schema": { "type": "string" }, "description": "only receipts with this ref (e.g. dry-run-mybot)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "JSON receipts" }, "400": { "description": "bad type, ref or cursor" } } } }, "/mcp": { "post": { "operationId": "mcp", "security": [], "summary": "Free remote MCP server (Streamable HTTP, stateless JSON-RPC 2.0): tools search_catalog, get_service, lookup, get_overnight_cos_pack, endpoint_spot_check (lookup shares vc-mcp quota; pack always paid; 402xAgent check 5 free/day (25 per network) then $0.02 a check)", "responses": { "200": { "description": "JSON-RPC response" }, "202": { "description": "notification accepted" } } } }, "/v1/tasks": { "get": { "operationId": "tasks", "security": [], "summary": "Task names", "responses": { "200": { "description": "task -> service ids" } } } }, "/v1/skips.json": { "get": { "operationId": "skipsJson", "security": [], "summary": "Skips page as JSON (free)", "responses": { "200": { "description": "self-checked x402 endpoints and the ones to skip" } } } }, "/badge/{host}": { "get": { "operationId": "badgePage", "security": [], "summary": "Badge page for a host (HTML, free): the SVG, its embed code and the receipt", "parameters": [ { "name": "host", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML" }, "400": { "description": "invalid host" } } } }, "/pricing": { "get": { "operationId": "pricing", "security": [], "summary": "Pricing page (HTML, free), built from the live price constants", "responses": { "200": { "description": "HTML" } } } }, "/blog": { "get": { "operationId": "blog", "security": [], "summary": "Blog (HTML, free): posts at /blog/", "responses": { "200": { "description": "HTML" } } } }, "/docs": { "get": { "operationId": "docs", "security": [], "summary": "Docs page (HTML, free): OpenAPI, rules, llms.txt, MCP, x402-spotcheck", "responses": { "200": { "description": "HTML" } } } }, "/.well-known/402xagent-keys.json": { "get": { "operationId": "receiptKeys", "security": [], "summary": "ed25519 public keys (kid, x) for signed receipts; JCS of the receipt minus signature", "responses": { "200": { "description": "key set" } } } }, "/.well-known/x402": { "get": { "operationId": "wellKnownX402", "security": [], "summary": "x402 discovery document", "responses": { "200": { "description": "resources, payment terms, free pages" } } } }, "/health": { "get": { "operationId": "health", "security": [], "summary": "Liveness and version", "responses": { "200": { "description": "{ok, version}" } } } } } }