{ "openapi": "3.1.0", "info": { "title": "PayScout (formerly Spot-Check): x402 pre-payment checks + verified catalog", "version": "0.16.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 (1 free/day then $0.01 to $0.25 USDC (one tenth of the target's quoted price), SSRF-safe x402 probe). Free MCP: POST /mcp.", "description": "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://payscout.dev", "description": "PayScout" }, { "url": "https://api.payscout.dev", "description": "PayScout" }, { "url": "https://verified-catalog-lookup.withgrokbot.workers.dev", "description": "legacy host (same Worker, still supported)" } ], "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/endpoint-spot-check": { "get": { "operationId": "endpointSpotCheck", "summary": "Decision-shaped x402 endpoint spot-check: probe a public URL for PAYMENT-REQUIRED (never pays the target). Returns verdict/reason/quoted vs claimed. 1 free/client/UTC day, then $0.01-$0.25 (one tenth of the target quote) USDC 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); 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": "dynamic", "currency": "USD", "min": "0.01", "max": "0.25", "rule": "one tenth of the target endpoint's quoted x402 price" }, "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_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" } } }, "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" }, "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 payment request, details locked'" }, "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" }, "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://payscout.dev/v1/receipts/sc-0123456789abcdef", "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, details locked", "payment_terms_sha256": "", "receipt_id": "sc-0123456789abcdef", "receipt_url": "https://payscout.dev/v1/receipts/sc-0123456789abcdef", "access": { "tier": "free", "free_per_day": 1, "free_used_today": 1, "free_remaining_today": 0, "then": "$0.01 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.01 to $0.25 USDC (one tenth of the target's quoted price) on Base)" }, "429": { "description": "paid rate limit (per payer per UTC hour)" } } }, "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" } } } }, "/v1/receipts/by-url": { "get": { "operationId": "receiptByUrl", "security": [], "summary": "Free: latest public receipt for a URL: latest_live (last live PayScout decision: live 402 terms, verdict, reason, timestamp, id) and latest_crawl (weekly self-checked crawl). A fresh live check is the paid Spot-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 PayScout 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 Spot-Check 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 PayScout 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; spot-check 1 free/day then $0.01-$0.25 by target quote)", "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" } } } } } }