{"openapi":"3.1.0","info":{"title":"Paddock — Agent Commerce Data","description":"Live x402 and MPP transaction volume for the AI agent economy — what AI agents are paying for, broken down by category, with spend share, provider counts, and market concentration. The neutral, citable measurement and verification layer for agent commerce. Three things event counters cannot do, and Paddock does: independently verified settlement volume, wash/circular detection with a published methodology and a dated series, and payTo wallet attribution. Start with verify_before_pay: the pre-payment check an agent runs before authorizing an x402 payment to an endpoint it does not already trust — live probe at query time, decoded 402 contract against your expectations, settlement recency, circular-cluster signal, price vs category. Keyless (no key, no cap): get_market_summary. Free key (pk_free_, self-serve, 10 calls/day shared): verify_before_pay, get_category_detail, get_niche_gaps, get_token_metrics, get_liveness. Paid (Builder $99/mo · 10k calls/day, Pro Agent $499/mo unlimited + archive, or x402/MPP per-query): get_best_value_provider, get_changes, get_report_data, get_circular_signal, get_whale_activity, get_provider_revenue.","version":"3.7.0","termsOfService":"https://paddock.finance/terms","contact":{"url":"https://x.com/PaddockFinance"}},"servers":[{"url":"https://paddock.finance"}],"tags":[{"name":"Pre-Payment Trust","description":"Checks an agent runs BEFORE it authorizes a payment: is the endpoint live right now, is its 402 contract what you were told, and is its volume real."},{"name":"Market Data","description":"Settlement volume, category breakdowns, pricing and time series across the x402 and MPP rails."},{"name":"Provider Intelligence","description":"Per-provider revenue, liveness and value ranking, resolved through payTo wallet attribution rather than event counts."},{"name":"Integrity Signals","description":"Circular/wash settlement detection with a published methodology and a dated longitudinal series, plus large-settlement movements."},{"name":"Reports","description":"The monthly State of Agent Commerce dataset — structured figures behind the published report."}],"paths":{"/api/paddock/mcp/verify-before-pay":{"get":{"operationId":"verify_before_pay","tags":["Pre-Payment Trust"],"summary":"Should my agent pay this endpoint right now?","description":"The pre-payment check no seller can self-report. Call it before your agent authorizes an x402 payment. It sends an unpaid request to the endpoint you name at the moment you call, decodes the 402, and checks network, asset, seller, and price against what you expected and against the seller's published config. It then adds three things only an independent observer can: whether the endpoint has settled real volume recently from wallets that are not its operator's, whether it sits in a circular-settlement cluster, and how its price compares to its category. The answer is `route: true`, `false`, or `\"inconclusive\"`, each with the evidence and its date. Liveness and contract are as of the call; settlement and circular signal are snapshot-dated, and each block says which. There is no success-rate field, on purpose: Paddock observes settlements, not failed calls, so it returns recency and frequency, which it can actually see. Test for `route === true`; inconclusive is the one case where you must not pay on our say-so. `route: true` scopes to one claim — the live contract matched what you expected — and is not an all-clear on every signal: stale settlement, a circular flag, a payTo divergence and a failed request pre-flight can each coexist with it, and each block says whether it moved the verdict, so read the evidence rather than `route` alone. A second, narrower verdict rides alongside it: `contract_and_request_ok` is `true` only when `route` is `true` and your own declared request passed pre-flight, `false` when either is bad, and `\"not_assessed\"` when a term was never established; `contract_and_request_ok_excludes` names the risk categories it is silent on, so it can never be read as a full clearance. The independent pre-payment check no seller can self-report. Give the endpoint your agent is about to pay (endpoint_url), the wallet it is about to pay (pay_to), or both, plus whatever you expect the contract to be. Returns `route`: the JSON literal `true`, the JSON literal `false`, or the STRING `\"inconclusive\"` — test it with `route === true`, because a truthiness test passes on \"inconclusive\", which is the one case where you must not pay on our say-so. \"inconclusive\" IS ALSO WHAT YOU GET FOR ASKING NOTHING. Every contract check compares the live 402 against something you stated: pay_to for the wallet, expect_network for the chain, expect_asset for the token, expect_price_usdc for the price. A call carrying none of them compared nothing, so from verify_before_pay/0.7 it returns \"inconclusive\" with the reason code no_expectations_supplied, where it previously returned true on the strength of a readable 402 alone. Name what you expect and you get a verdict about it; if you only want to know whether the endpoint is answering, call get_liveness instead. WHAT route:true MEANS: the live 402 was read at query time and its contract matched what you said you expected. It is NOT an all-clear on every signal in the response. Stale or never-observed settlement, a circular-cluster flag, a payTo that diverges from Paddock's attribution or from the seller's published config, a divergent second challenge channel, and a FAILED request pre-flight can each coexist with route:true — each of those blocks carries its own status and, where the distinction exists, a moves_route field saying whether it fed the verdict. Read `checks`, not `route` alone. A SECOND, NARROWER VERDICT rides alongside it: `contract_and_request_ok` is true only when route is true AND your own declared request passed pre-flight; three-valued, with the string \"not_assessed\" when a term was never established (most often because you passed no intended_params). It does not replace route and it is not a clearance — `contract_and_request_ok_excludes` names the six risk categories it is silent on. Five checks: (1) LIVENESS — one unpaid GET and, if needed, one unpaid POST at query time, decoding 402 payment requirements from the response body AND from the payment-required/www-authenticate header; HTTP 200 is never treated as evidence of a live paid endpoint. (2) CONTRACT — the decoded 402 compared against your expect_* parameters and against the seller's own published x402 config, read at BOTH `.well-known` spellings (/.well-known/x402.json and /.well-known/x402 — a seller publishing only at the suffixless path is not reported unavailable); any mismatch is route:false and names the field. (3) SETTLEMENT RECENCY — last observed settlement plus observed 7/30-day counts from Paddock's nightly snapshots. (4) CIRCULAR SIGNAL — flagged-cluster membership and operator-funded share where the detector's facilitator coverage reaches, and an explicit not_assessed with its basis where it does not; never a silent skip and never a 'clean' for something that was not examined. (5) PRICE — the advertised price against the category median, with listed and settled bases reported separately and never combined. (6) PAID FULFILLMENT — where an independent third party has paid this endpoint with real USDC, whether a valid response came back, with the settlement transaction hash and the date it was observed. This is NOT a Paddock measurement: we observe settlement and do not buy from sellers. It is re-served under CC-BY 4.0 and never combined with any figure we measure; see https://paddock.finance/data-sources. A settled-then-rejected result is route:false — it is the strongest negative evidence in the response. A delivered result is not a free pass: it says the endpoint worked once, for someone else, on a past date, and it never outranks a contract mismatch or a dead probe today. NO SUCCESS RATE IS RETURNED, deliberately: Paddock observes settlements, not attempted calls, so a payment that failed leaves no row in the record and a rate computed from it could only ever be 100%. Recency and frequency are reported instead. `schema_version` and `checked_at` are on every response, including errors, so verdicts can be stored and graded later. Free with a `pk_free_` key against the shared daily allowance, or $0.25 USDC per query via x402/MPP, or any Builder/Pro Agent key.","security":[{"FreeApiKey":[]},{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"endpoint_url","in":"query","required":false,"description":"The resource URL your agent is about to pay. This is the URL that gets probed.","schema":{"type":"string","format":"uri"}},{"name":"pay_to","in":"query","required":false,"description":"The recipient wallet from the 402 you are about to settle. CHECKED: if it is not one of the recipients the live challenge names, route is false and pay_to is in mismatched_fields. Give this, endpoint_url, or both — at least one is required.","schema":{"type":"string"}},{"name":"expect_network","in":"query","required":false,"description":"Network you expect, CAIP-2 or shorthand (eip155:8453 / base). Mismatch returns route:false.","schema":{"type":"string"}},{"name":"expect_asset","in":"query","required":false,"description":"Asset contract address you expect. Mismatch returns route:false.","schema":{"type":"string"}},{"name":"expect_seller","in":"query","required":false,"description":"Seller domain you expect. Satisfied by the live 402's own resource host or by Paddock's payTo attribution. Mismatch returns route:false.","schema":{"type":"string"}},{"name":"expect_price_usdc","in":"query","required":false,"description":"Price in dollars you expect to pay, e.g. 0.01. ANY difference returns route:false and names the field.","schema":{"type":"number","minimum":0}},{"name":"intended_params","in":"query","required":false,"description":"Parameter NAMES your request will carry, comma-separated or as a query string ('slug,limit' or '?slug=amazon-us'). Values are discarded, never stored. Compared against the parameter schema the live 402 declares; a missing required name is reported in checks.requestPreflight and does NOT change route.","schema":{"type":"string"}},{"name":"intended_params_empty","in":"query","required":false,"description":"Assert that your paid request will carry NO parameters at all. Bare (?intended_params_empty) or =true. This is an assertion and it is checked: against a challenge that declares anything required, an empty request fails pre-flight, where omitting the argument entirely reports 'you did not say' and checks nothing. Passing this together with intended_params is a 400 — they are contradictory statements about one request.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The verdict, with per-check detail and dated evidence.","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","const":"verify_before_pay"},"schema_version":{"type":"string","description":"Bumped when a stored response stops being comparable to a live one: a breaking shape change, a change to what an existing field means, or a new verdict the older version did not emit. Store it with the verdict — a verdict is only comparable to another at the same version."},"checked_at":{"type":"string","format":"date-time","description":"When the live probe ran. The whole value of this response is that it was taken at this instant; it is never cached."},"route":{"description":"true = the endpoint asked for payment and the contract you stated matched. false = do not pay. \"inconclusive\" = either we could not read a 402, so we cannot vouch for what it will charge you, or you supplied no pay_to and no expect_* so there was nothing to compare (reason code no_expectations_supplied).","oneOf":[{"type":"boolean"},{"type":"string","const":"inconclusive"}]},"contract_and_request_ok":{"description":"The combined verdict (0.6). true only when the live contract matched your expectations (route === true) AND your own declared request passed pre-flight (checks.requestPreflight.status === \"pass\"). false when either term is bad — including when YOUR request is missing a parameter the challenge declares required. The STRING \"not_assessed\" when a term was never established, most often because you passed no intended_params or intended_params_empty, so there was no request of yours to clear; that is not a soft yes and not a no. Test with contract_and_request_ok === true. It does not replace route, which is unchanged, and it is NOT a clearance — read contract_and_request_ok_excludes.","oneOf":[{"type":"boolean"},{"type":"string","const":"not_assessed"}]},"contract_and_request_ok_excludes":{"type":"array","description":"Every risk category the conjunction does NOT cover, each with the field where that category's own verdict lives and what it can be doing while contract_and_request_ok is true: settlement recency, an unassessed circular signal, attribution divergence, a payTo-only divergence from the seller's published config, a divergent second challenge channel, and price against the category median. The list is STATIC — it says what the formula leaves out, not how this endpoint scored, so coverage can never be inferred from an absence.","items":{"type":"object","properties":{"category":{"type":"string"},"where":{"type":"string"},"note":{"type":"string"}}}},"reason_codes":{"type":"array","items":{"type":"string"},"description":"Stable, append-only vocabulary, e.g. live_402_observed, contract_mismatch_price, circular_flagged_cluster_member, settlement_never_observed."},"summary":{"type":"string"},"route_note":{"type":"string"},"target":{"type":"object","description":"What was probed, what the wallet resolved to, and which wallet the circular check used."},"expectations_supplied":{"type":"object"},"checks":{"type":"object","description":"One block per check, each carrying its own status, universe, basis and as_of date. No figure in one block is divided by a figure in another.","properties":{"liveness":{"type":"object"},"contract":{"type":"object"},"settlement_recency":{"type":"object"},"circular_signal":{"type":"object"},"paid_fulfillment":{"type":"object","description":"Independent third-party paid-verification result, re-served under CC-BY 4.0. Carries status, last_paid_attempt_at (the date the SOURCE observed it, never defaulted to now), basis, attribution_url, and the settlement tx_hash where one was published. Absent coverage returns not_assessed with a basis naming why."},"price":{"type":"object"}}},"evidence":{"type":"array","description":"One row per fact, each with the source it came from and the time it is as-of. Probe rows are as-of now; snapshot and classification rows are as-of their own dates, which are older.","items":{"type":"object","properties":{"check":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"detail":{"type":"string"}}}},"_meta":{"type":"object"}}}}}},"400":{"description":"Neither endpoint_url nor pay_to was supplied, or a parameter was malformed. Returned AFTER the auth check, so an unauthenticated caller sees the 402 first (x402scan indexes on it)."},"401":{"description":"A key was supplied and it is not valid or not active."},"402":{"description":"No key, no payment and no free trial left. Body carries the full x402 payment requirements ($0.25 USDC on Base) and names the free key as the cheaper path; the MPP challenge rides in the WWW-Authenticate header."},"429":{"description":"Free-key daily allowance exhausted (shared across all free-tier tools), or Builder daily rate limit exceeded."},"500":{"description":"The check itself failed. Carries schema_version and checked_at like every other response."}}}},"/api/paddock/mcp/summary":{"get":{"operationId":"get_market_summary","tags":["Market Data"],"summary":"How big is agent commerce today? (The citation number.)","description":"The number to quote. One call, no key, returns market-wide settled volume, USDC spend, active buyer agents, live providers, and the top categories, as of the most recent nightly snapshot. It is the same figure Paddock publishes, with the same methodology behind it, which is why it has no rate limit: it exists to be cited. Returns current x402 transaction volume, top spending categories, live server count, and market overview. Free — no authentication required. Note: each category's share_of_volume is its share of CATEGORIZED (attributed) transactions — named categories only, NOT a share of summary.daily_transactions (the full-ecosystem total). Only the top 6 categories are returned, so the shown shares sum to <100% by design.","security":[],"parameters":[],"responses":{"200":{"description":"Market summary with category breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"summary":{"type":"object","properties":{"daily_transactions":{"type":"number"},"daily_volume_usdc":{"type":"string"},"unique_buyer_agents":{"type":"number"},"live_service_providers":{"type":"number"}}},"top_categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"daily_transactions":{"type":"number"},"providers":{"type":"number"},"share_of_volume":{"type":"string","description":"Share of CATEGORIZED (attributed) agent-commerce transactions — named categories only, NOT a share of summary.daily_transactions (the full-ecosystem total). Top 6 categories returned, so values sum to <100% by design."}}}},"insight":{"type":"string"},"subscription_url":{"type":"string"}}}}}},"405":{"description":"Method not allowed. This operation is GET-only."},"500":{"description":"Snapshot read failed."},"503":{"description":"No snapshot available yet. The nightly capture runs at 23:30 UTC; this is returned rather than a stale or invented figure."}}}},"/api/paddock/mcp/category":{"get":{"operationId":"get_category_detail","tags":["Market Data"],"summary":"Who's selling in this category, and who's actually getting paid?","description":"The category, ranked by what settled. Every provider in the category with its daily transactions, USDC volume, unique buyers, and reliability score. Use it to see the alternatives before your agent commits, to watch your own category, or to size a market you're thinking of entering. Snapshot-dated; two to four calls a day keeps a dashboard current. Returns all services in a category with transaction counts, pricing, and reliability scores. Requires a free Paddock key (pk_free_, self-serve signup, 10 calls/day shared across free-tier tools). A Builder or Pro Agent key also opens it.","security":[{"FreeApiKey":[]},{"ProApiKey":[]}],"parameters":[{"name":"name","in":"query","required":true,"description":"Category id: llm, data, search, infra, content, markets, payments, or comms","schema":{"type":"string","enum":["llm","data","search","infra","content","markets","payments","comms"]}}],"responses":{"200":{"description":"Category detail with services and reliability","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"summary":{"type":"object","properties":{"total_daily_transactions":{"type":"number"},"provider_count":{"type":"number"},"market_status":{"type":"string"}}},"services":{"type":"array","items":{"type":"object","properties":{"service":{"type":"string"},"domain":{"type":"string"},"daily_transactions":{"type":"number"},"unique_buyers":{"type":"number"}}}}}}}}},"400":{"description":"Missing or unrecognised `name`. Returned BEFORE the key check, so a caller debugging a category typo is not told to go and get a key. The body lists the valid category ids.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"valid_categories":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"No key, or a key that is neither a valid free key nor an active subscription. The body carries self-serve signup instructions."},"429":{"description":"Free-key daily allowance exhausted (10 calls/day, shared across all free-tier tools)."}}}},"/api/paddock/mcp/gaps":{"get":{"operationId":"get_niche_gaps","tags":["Market Data"],"summary":"Where is demand outrunning supply?","description":"The open lanes. Categories where buyers are paying and few sellers are answering, ranked by the gap, with the settled volume and provider count that produced the ranking. Pair with `get_category_detail` to see who is already there and how much they move. Ranks every category in today's snapshot by opportunity_score = log10(1 + daily_transactions) / max(providers, 1). Returns share, top_provider_share, opportunity_score, and a signal (Consolidating | Open | Tightening | Mature) per category. Auth: X-Paddock-Key header (Builder $99/mo · 10k calls/day, Pro Agent $499/mo unlimited) or x402 per-query at $0.01 USDC.","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.01"},"mpp":{"tempo":{"amount":"0.01","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"0.99","currency":"USD"}}},"security":[{"FreeApiKey":[]},{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"top","in":"query","required":false,"description":"Limit results to the top N categories by opportunity_score. Omit to return all categories (up to 50).","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"All categories ranked by opportunity_score (descending)","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"date":{"type":"string"},"paid_via":{"type":"string"},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"category_id":{"type":"string"},"daily_transactions":{"type":"number"},"providers":{"type":"number"},"share":{"type":"number"},"top_provider_share":{"type":"number"},"opportunity_score":{"type":"number"},"signal":{"type":"string"},"paddock_url":{"type":"string"}}}},"methodology":{"type":"object"}}}}}},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/best-value":{"get":{"operationId":"get_best_value_provider","tags":["Provider Intelligence"],"summary":"Which provider in this category should my agent pick?","description":"A ranked answer with the formula shown. Providers in a category scored on reliability, reputation, and price, with every input returned so the score can be checked. The composite is published in the route and the docs for one reason: a score whose formula is private is a score that can be quietly adjusted. Paddock does not sell positions in this ranking. Returns every provider in the given category ranked by a composite score: (success_rate_7d × 0.40) + (reputation_norm × 0.30) + ((1 − price_norm) × 0.30). Auth: X-Paddock-Key (Builder/Pro Agent) or x402 per-query at $0.02 USDC.","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.02"},"mpp":{"tempo":{"amount":"0.02","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"0.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"category","in":"query","required":true,"description":"Category id or alias. Valid ids: llm, data, search, infra, content, markets, payments, comms.","schema":{"type":"string"}}],"responses":{"200":{"description":"Providers in the category, ranked by composite_score (descending)","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"date":{"type":"string"},"category":{"type":"string"},"category_label":{"type":"string"},"paid_via":{"type":"string"},"providers":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"title":{"type":["string","null"]},"price_usdc":{"type":["number","null"]},"liveness_score":{"type":["number","null"]},"success_rate_7d":{"type":["number","null"]},"tx_count":{"type":"number"},"unique_buyers":{"type":"number"},"composite_score":{"type":"number"},"rank":{"type":"number"}}}},"formula":{"type":"object"}}}}}},"400":{"description":"Missing or invalid ?category= parameter"},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/liveness":{"get":{"operationId":"get_liveness","tags":["Provider Intelligence"],"summary":"Was this domain up at last night's probe, per someone who isn't the seller?","description":"An up/down read backed by real probes, not the seller's status page. Works for any probed domain, including ones with no x402 volume. Returns the seven-day success rate, p50 and p95 latency, sample count, and when it was last probed. Probe data refreshes nightly, so once a day is the honest cadence; if you need sub-day downtime detection, run your own uptime check and use this to see how the ecosystem's prober sees you. Returns the latest TrustBench probe data for one domain. up = success_rate_7d >= 0.95. Auth: X-Paddock-Key (Builder/Pro Agent), x402 per-query at $0.001 USDC, or MPP (Machine Payments Protocol: tempo/charge $0.001 pathUSD testnet, stripe/charge $0.99 USD) via the Payment HTTP authentication scheme.","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.001"},"mpp":{"tempo":{"amount":"0.001","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"0.99","currency":"USD"}}},"security":[{"FreeApiKey":[]},{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"domain","in":"query","required":true,"description":"Hostname to look up (e.g. api.example.com).","schema":{"type":"string"}}],"responses":{"200":{"description":"Liveness record for the domain. Un-probed domains also return 200 with status:\"not_probed\" and up:null (coverage limitation, not an error).","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"paid_via":{"type":"string"},"domain":{"type":"string"},"up":{"type":"boolean"},"score":{"type":"number"},"success_rate_7d":{"type":"number"},"latency_p50_ms":{"type":"number"},"latency_p95_ms":{"type":"number"},"samples_7d":{"type":"number"},"last_probed_at":{"type":"string"}}}}}},"400":{"description":"Missing ?domain= parameter"},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/changes":{"get":{"operationId":"get_changes","tags":["Market Data"],"summary":"What changed since a date I name?","description":"Change tracking without polling. Name a past date and get the diff: services that appeared, services that retired, and the providers that moved most in volume, with the figures on both sides. Built on the daily archive, so any date since May 2026 is a valid baseline. Returns new_services, retired_services, category_movements (|delta_pp| ≥ 3), and top_movers (|pct_change| ≥ 50%) between two snapshots. `since` is capped at 90 days ago (full-fidelity retention). Auth: X-Paddock-Key (Builder/Pro Agent) or x402 per-query at $0.10 USDC.","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.10"},"mpp":{"tempo":{"amount":"0.10","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"1.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"since","in":"query","required":true,"description":"Earlier date in YYYY-MM-DD (max 90 days ago).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Diff between today's snapshot and the snapshot at ?since","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"paid_via":{"type":"string"},"since":{"type":"string"},"today":{"type":"string"},"limited_to_rollup_only":{"type":"boolean"},"new_services":{"type":"array","items":{"type":"object"}},"retired_services":{"type":"array","items":{"type":"object"}},"category_movements":{"type":"array","items":{"type":"object"}},"top_movers":{"type":"array","items":{"type":"object"}},"summary":{"type":"string"}}}}}},"400":{"description":"Missing or invalid ?since= parameter"},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/circular-signal":{"get":{"operationId":"get_circular_signal","tags":["Integrity Signals"],"summary":"Is this facilitator's volume real, or is it paying itself?","description":"The wash check. Paddock's published circular-settlement methodology, applied per facilitator: which clusters are flagged, how much settlement they carry, when the detection ran, and the criteria it used, past tense and dated. A number that cannot be self-reported by anyone in the flow. Scope is stated in the response, including what the method cannot yet catch. Returns the circular-settlement classification (methodology v0.1) grouped BY FACILITATOR: cluster count, cluster volume (30d/7d), self-funding %, external-payer count, flagged share of settlement, and trend. Patterns attach to the facilitator only — no seller wallet addresses, operator identity, or per-wallet rows. Auth: X-Paddock-Key (Builder/Pro Agent), x402 per-query at $0.99 USDC, or MPP (tempo/charge $0.99 pathUSD testnet, stripe/charge $4.99 USD).","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.99"},"mpp":{"tempo":{"amount":"0.99","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"4.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"window","in":"query","required":false,"description":"Trend window context (7d or 30d).","schema":{"type":"string","enum":["7d","30d"]}}],"responses":{"200":{"description":"Per-facilitator circular signal","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"methodology_version":{"type":"string"},"facilitators":{"type":"array","items":{"type":"object","properties":{"facilitator":{"type":"string"},"cluster_count":{"type":"number"},"cluster_volume_usd":{"type":"object"},"self_funding_pct":{"type":"number"},"external_payer_count":{"type":"number"},"flagged_share_of_listed_pct":{"type":["number","null"]},"trend":{"type":"string"}}}}}}}}},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/whale-activity":{"get":{"operationId":"get_whale_activity","tags":["Integrity Signals"],"summary":"Where did the large settlements go?","description":"The largest settlements in the window and the providers that moved most, aggregated so the answer is about the market, not a wallet. Amounts, dates, and the category each landed in. Returns AGGREGATE large-settlement activity over a window: counts and USDC amounts by facilitator, by category, and by size band, plus per-category mover counts. Describes size and where, never who — no individual seller identity. Auth: X-Paddock-Key (Builder/Pro Agent), x402 per-query at $0.99 USDC, or MPP (tempo/charge $0.99 pathUSD testnet, stripe/charge $4.99 USD).","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.99"},"mpp":{"tempo":{"amount":"0.99","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"4.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"window","in":"query","required":false,"description":"Mover comparison window in days (1-90, default 7).","schema":{"type":"integer","minimum":1,"maximum":90}},{"name":"min_usd","in":"query","required":false,"description":"Large-settlement threshold in USD (default 1000).","schema":{"type":"number","minimum":0}}],"responses":{"200":{"description":"Aggregate whale activity","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"window_days":{"type":"number"},"large_threshold_usd":{"type":"number"},"totals":{"type":"object"},"by_facilitator":{"type":"array","items":{"type":"object"}},"by_category":{"type":"array","items":{"type":"object"}},"size_bands":{"type":"array","items":{"type":"object"}},"movers_by_category":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/provider-revenue":{"get":{"operationId":"get_provider_revenue","tags":["Provider Intelligence"],"summary":"Who earns the most, and how much of the market can that answer see?","description":"The leaderboard with its own limits printed on it. Services ranked by attributed revenue, and beside it the share of settled volume Paddock can currently attribute to a named service, so the ranking is never mistaken for the whole market. Returns the ATTRIBUTED-universe revenue leaderboard (never the full-ecosystem census) over a window of daily snapshots: per-provider revenue_usd, tx_count, unique_buyers. Facilitator pass-through and circular-flagged wallets are excluded. Unresolved wallets are not dropped — the `unattributed` row reports their transaction share (no dollar amount exists for them anywhere in the snapshot). Reports the window's dates and whether the recipient list was complete every day, plus `retroactive_exclusion_caveat` for any day before 2026-07-28 where a wallet added to the facilitator/circular exclusion lists afterward could not be retroactively re-checked. Auth: X-Paddock-Key (Builder/Pro Agent), x402 per-query at $0.99 USDC, or MPP (tempo/charge $0.99 pathUSD testnet, stripe/charge $4.99 USD).","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.99"},"mpp":{"tempo":{"amount":"0.99","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"4.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"window","in":"query","required":false,"description":"Days to aggregate (1-90, default 7).","schema":{"type":"integer","minimum":1,"maximum":90}},{"name":"top","in":"query","required":false,"description":"Return only the top N providers by revenue_usd (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Attributed provider revenue leaderboard plus market-visibility and unattributed accounting","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"universe":{"type":"string"},"window":{"type":"object"},"providers":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"category":{"type":"string"},"revenue_usd":{"type":"number"},"tx_count":{"type":"number"},"unique_buyers":{"type":"number"}}}},"market_visibility":{"type":"object"},"unattributed":{"type":"object"},"retroactive_exclusion_caveat":{"type":["object","null"]}}}}}},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/token-metrics":{"get":{"operationId":"get_token_metrics","tags":["Market Data"],"summary":"Is today's number a real move or ordinary noise?","description":"Paddock's first-party series, queryable. The same chart data the site renders, by metric and date range: `daily_transactions`, `spend_share_over_time`, `category_concentration`, `new_services`, `liveness_score`, and the monthly Agent Commerce Index. Pull 90 days and compare against today's summary to tell a spike from a Tuesday. This is Paddock's series, not token prices; third-party token market data is deliberately not resold here. Returns the five /charts series (spend_share_over_time, daily_transactions, category_concentration, new_services, liveness_score) plus the Agent Commerce Index (aci) monthly series — queryable by metric and date range. First-party data only; token spot price is excluded pending a licensing review (see the response's compliance field). Auth: X-Paddock-Key (Builder/Pro Agent) or x402 per-query at $0.01 USDC.","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.01"},"mpp":{"tempo":{"amount":"0.01","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"0.99","currency":"USD"}}},"security":[{"FreeApiKey":[]},{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"metric","in":"query","required":true,"description":"Which series to return.","schema":{"type":"string","enum":["spend_share_over_time","daily_transactions","category_concentration","new_services","liveness_score","aci"]}},{"name":"days","in":"query","required":false,"description":"Lookback window in days for chart series (1-730, default 90).","schema":{"type":"integer","minimum":1,"maximum":730}},{"name":"category","in":"query","required":false,"description":"Category id for category_concentration (e.g. llm).","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Start month YYYY-MM (aci metric only).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"End month YYYY-MM (aci metric only).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"Chart/index series for the requested metric","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"metric":{"type":"string"},"range":{"type":"object"},"points":{"type":"array","items":{"type":"object"}},"available_metrics":{"type":"array","items":{"type":"string"}},"compliance":{"type":"object"}}}}}},"400":{"description":"Missing or invalid ?metric= parameter"},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/report-data/paid":{"get":{"operationId":"get_report_data","tags":["Reports"],"summary":"What are the numbers behind the monthly report?","description":"Everything behind the monthly report, as data. Every published figure with its universe label, methodology version, and date, plus the series the report charts. For anyone building on the month rather than the day. Returns the full machine-readable JSON of the monthly State of Agent Commerce report: ecosystem trends, category breakdowns, the Agent Commerce Index (ACI v1.0) with component decomposition, protocol comparison, and reliability data. Auth: X-Paddock-Key (Builder $99/mo current month, Pro Agent $499/mo all history) or x402 per-query at $0.99 USDC. Unauthenticated requests receive the HTTP 402 x402 v2 challenge. Free metadata (no payment) at /api/paddock/mcp/report-data. Full report for people at https://paddock.finance/report ($299/mo).","x-payment-info":{"protocols":"x402, mpp","price":{"mode":"fixed","currency":"USD","amount":"0.99"},"mpp":{"tempo":{"amount":"0.99","currency":"pathUSD","network":"tempo-testnet"},"stripe":{"amount":"19.99","currency":"USD"}}},"security":[{"ProApiKey":[]},{"x402Payment":[]},{"mppPayment":[]}],"parameters":[{"name":"month","in":"query","required":false,"description":"Report month in YYYY-MM format (e.g. 2026-06). Defaults to latest published month.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"Full report data (paid)","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"month":{"type":"string"},"title":{"type":"string"},"published_at":{"type":"string"},"table_of_contents":{"type":"array","items":{"type":"string"}},"executive_summary_excerpt":{"type":"string"},"paid_via":{"type":"string"},"data":{"type":"object"},"paddock_url":{"type":"string"}}}}}},"401":{"description":"Invalid or expired API key. Payment-authenticated callers never see this — supply a valid x402 receipt or MPP credential instead."},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"403":{"description":"Builder tier: current month only. Upgrade to Pro Agent for full history."},"429":{"description":"Rate limit exceeded (Builder tier: 10,000 calls/day)"}}}},"/api/paddock/mcp/report-data":{"get":{"operationId":"get_report_data_free_metadata","tags":["Reports"],"summary":"State of Agent Commerce report metadata — free preview (title, TOC, executive summary excerpt)","description":"Returns free report metadata without payment: title, table of contents, and an executive summary excerpt (<200 words), plus payment details for the full data. Full structured data: use /api/paddock/mcp/report-data/paid (x402 $0.99 USDC or Paddock API key).","security":[],"parameters":[{"name":"month","in":"query","required":false,"description":"Report month in YYYY-MM format (e.g. 2026-06). Defaults to current published month.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"Report data (full if paid, metadata only if free)","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"access":{"type":"string"},"month":{"type":"string"},"title":{"type":"string"},"table_of_contents":{"type":"array","items":{"type":"string"}},"executive_summary_excerpt":{"type":"string"},"data":{"type":"object"}}}}}},"403":{"description":"Builder tier: current month only. Upgrade to Pro Agent for full history."}}}}},"components":{"securitySchemes":{"FreeApiKey":{"type":"apiKey","in":"header","name":"X-Paddock-Key","description":"Free Paddock key (pk_free_ prefix), self-serve at https://paddock.finance/api-access. 10 calls/day shared across all free-tier tools."},"ProApiKey":{"type":"apiKey","in":"header","name":"X-Paddock-Key","description":"Paddock API key (Builder or Pro Agent subscription). See https://paddock.finance/api-access"},"x402Payment":{"type":"http","scheme":"x402","description":"Per-query x402 micropayment on Base mainnet (USDC). See x-payment-info on each operation for amount and payTo address. Compatible with any x402-capable wallet (AgentCash, Coinbase CDP, etc.)."},"mppPayment":{"type":"http","scheme":"payment","description":"Per-query MPP (Machine Payments Protocol) payment via the `Payment` HTTP authentication scheme. Methods per operation (see x-payment-info.mpp): tempo/charge in pathUSD on Tempo testnet, or stripe/charge in USD via Stripe Shared Payment Tokens. Unauthenticated requests receive WWW-Authenticate: Payment challenges on the 402."}},"schemas":{"PaymentRequired":{"type":"object","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","example":2},"error":{"type":"string","example":"Payment required"},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","amount","asset","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"amount":{"type":"string","example":"10000","description":"Atomic USDC units (v2 spec field)."},"maxAmountRequired":{"type":"string","description":"v1 alias for amount (superset)."},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"payTo":{"type":"string"},"resource":{"type":"string","example":"https://paddock.finance/api/paddock/mcp/gaps"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"},"maxTimeoutSeconds":{"type":"number","example":300},"extra":{"type":"object","example":{"name":"USD Coin","version":"2"},"description":"USDC EIP-712 domain (name/version) used by the x402 signer."}}}},"extensions":{"type":"object","description":"x402 v2 extensions. `bazaar` is the official CDP Bazaar discovery extension (built with @x402/extensions) that lets the CDP facilitator auto-index this resource on agentic.market / x402scan.","properties":{"bazaar":{"type":"object","properties":{"info":{"type":"object"},"schema":{"type":"object"}}}}},"resource":{"type":"object","description":"Legacy top-level resource object (superset; canonical resource is inside each accepts item).","properties":{"url":{"type":"string","example":"https://paddock.finance/api/paddock/mcp/gaps"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"}}},"tool":{"type":"string"},"status":{"type":"string","example":"pro_required"}}}}}}