llms.txt: documentation index for LLMs and agentsllms-full.txt: full documentation corpusMarkdown version of the documentationskill.md: agent skill filePaddock MCP server descriptor
Documentation

Paddock API & MCP — Documentation

Everything you need to integrate Paddock data into your agents, workflows, and applications.

Already have a Paddock API key? Skip to Authentication. Just evaluating? Browse the endpoints below to see what's possible. Want your agent to set itself up? Copy the one-liner below.

Quick · Paste in your agent's chat
No key needed. Your agent fetches the skill file and connects itself.
— Start here

Sixty seconds

Three steps. The first needs nothing at all.

01
Call something, with no key
get_market_summary is keyless, unmetered, and exists to be cited. If this returns JSON, you are connected.
bash
copy
curl -s https://paddock.finance/api/mcp/summary | jq '{daily_transactions, daily_volume_usdc}'
02
Mint a free key
One email, no card, no approval step. It opens the 5 free-key tools against a shared 10 calls a day.
bash
copy
curl -s -X POST https://paddock.finance/api/keys/free \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]"}'
03
Make one keyed call
The flagship: Should my agent pay this endpoint right now? Send the key as a header — query strings land in access logs and browser history.
bash
copy
curl -s -H "X-Paddock-Key: pk_free_YOUR_KEY" \
  'https://paddock.finance/api/mcp/verify-before-pay?endpoint_url=https%3A%2F%2Fpaddock.finance%2Fapi%2Fpaddock%2Fmcp%2Fgaps&expect_network=eip155%3A8453' \
  | jq '{route, reason_codes}'
Not writing code? Connect Paddock to Claude over MCP and ask in plain language — same tools, same tiers, two minutes to set up.
Design partner? Start here instead — the two calls to run first, refusal before pass.
— Every tool

What each one answers, and what it costs

Twelve tools, the question each answers, and its price and tier. Rendered from the canonical table — this is the same wording every Paddock surface uses, because they all read it from one file.

ToolThe question it answersPriceTier
verify_before_payShould my agent pay this endpoint right now?$0.25Free key
check_payeeIs this the seller's wallet, before my agent pays it?$0.01Keyless
@paddock-finance/x402-guard npm · GitHub
get_market_summaryHow big is agent commerce today? (The citation number.)—Keyless
get_category_detailWho's selling in this category, and who's actually getting paid?—Free key
get_livenessWas this domain up at last night's probe, per someone who isn't the seller?$0.001Free key
get_niche_gapsWhere is demand outrunning supply?$0.01Free key
get_token_metricsIs today's number a real move or ordinary noise?$0.01Free key
get_best_value_providerWhich provider in this category should my agent pick?$0.02Paid
get_changesWhat changed since a date I name?$0.10Paid
get_circular_signalIs this facilitator's volume real, or is it paying itself?$0.99Paid
get_whale_activityWhere did the large settlements go?$0.99Paid
get_provider_revenueWho earns the most, and how much of the market can that answer see?$0.99Paid
get_report_dataWhat are the numbers behind the monthly report?$0.99 · metadata freePaid
A price beside “Free key” is not a contradiction: the free key is how you reach the tool without paying, against the shared 10-a-day budget, and the price is what the same call costs per query via x402 once you are past it — or if you would rather not hold a key at all.
— Flagship

verify_before_pay

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. route_state carries the same verdict as route, always as a string ("true", "false", "inconclusive"), for clients that cannot type a boolean-or-string field. Pass `attest: true` to also issue a signed, publicly fetchable record of this verdict - an attestation id and a URL a third party can verify independently against Paddock's published key.

The response
jsonc
copy
{
  "tool": "verify_before_pay",
  "schema_version": "verify_before_pay/0.15",
  "checked_at": "2026-08-28T19:41:07.412Z",
  "route": false,
  "contract_and_request_ok": false,
  "contract_and_request_ok_excludes": [ { "category": "settlement_recency", "where": "...", "note": "..." } ],
  "reason_codes": ["live_402_observed", "contract_mismatch_price"],
  "summary": "Do not route: the live 402 contract does not match on price_usdc.",
  "target":   { "probed_url": "...", "resolved_domain": "...", "...": "..." },
  "checks":   { "liveness": {...}, "contract": {...}, "settlement": {...},
                "circular": {...}, "price": {...} },
  "mpp":      { "challenges": [ { "index": 0, "method": "tempo", "checks": {...} } ],
                "result": "...", "matched_rail": null },
  "evidence": [ { "check": "...", "observed_at": "...", "source": "...", "detail": "..." } ]
}
route is three-valued: the JSON literal true, the JSON literal false, or the STRING "inconclusive".
js
copy
// The only correct test:
if (result.route === true) { pay(); } else { doNotPay(); }

// NEVER this — "inconclusive" is a non-empty string, so it is truthy,
// and this pays exactly when we have told you we could not check.
if (result.route) { pay(); }        // ✗

"inconclusive" means we could not read a 402 from the endpoint at query time. Not that it failed — that we do not know. Everything else in that response is history, and history is not proof of what an endpoint will charge you now. Treat it as a no for payment purposes and a look-again for yours.

It is also what you get for asking nothing. Every contract check needs you to say what you expected: the wallet check reads pay_to, the chain check expect_network, the token check expect_asset, the price check expect_price_usdc. A call carrying none of them compared nothing, so since verify_before_pay/0.15 it returns "inconclusive" with no_expectations_supplied in reason_codes — where it used to return true on the strength of a readable 402 alone. “We compared nothing” and “we compared four things and all four matched” are not the same answer and no longer arrive as the same value. The summary says so in one line: Nothing was compared. Pass pay_to or expect_* for a verdict; for liveness alone call get_liveness.

If all you want to know is whether an endpoint is answering, that is get_liveness, and it is cheaper.

route: true means the live contract matched what you said you expected. It is not an all-clear on every signal. Stale settlement, an unassessed circular signal, an attribution divergence, a divergent second challenge channel and a failed request pre-flight can each sit alongside it — each in its own block, each saying whether it moved the verdict. Read checks, not route alone.

contract_and_request_ok conjuncts exactly two of those for you: it is true only when the live contract matched your expectations and your declared request passed pre-flight. It is three-valued like route — false when either term is bad, and the string "not_assessed" when a term was never established, most often because you passed no intended_params. That third value is not a soft yes: it is us declining to conjunct something we were not told. It does not replace route, and it is not a clearance — contract_and_request_ok_excludes ships in every response naming the six risk categories it is silent on and where each one's own verdict lives.

Each checks block carries its own status, universe, basis and as_of, and nothing in the response divides a figure from one universe by a figure from another. liveness and contract are as of checked_at; settlement_recency is as of the last nightly snapshot; circular_signal is as of the detection date, which can be weeks older than the snapshot beside it.

Putting it in front of a real payment path? The design-partner guide runs the refusal case first, on purpose.
— Auth

Authentication

Pass your key as the X-Paddock-Key header on every request. Free keys (pk_free_) are issued instantly from POST /api/keys/free — see the Free tier quickstart above. Builder (pk_builder_, $99/mo) and Pro Agent (pk_proagent_, $499/mo) keys are issued by email once the subscription completes.

header
copy
X-Paddock-Key: pk_builder_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

For quick lookups and browser testing, the key can also be passed as an ?api_key= query parameter (the header takes precedence if both are present):

bash
copy
https://paddock.finance/api/mcp/best-value?category=infra&api_key=pk_builder_YOUR_KEY

Prefer the header in production — query strings can be captured in server access logs, browser history, and Referer headers. The query param is a convenience, not the recommended default.

Error responses
401
Key required / invalid
The key is missing, malformed, or cancelled. On get_category_detail this means you need a free key — the response body carries the signup request.
402
Payment required
A paid endpoint without a key or payment, OR a free key calling a paid tool. The body names the price and the paid paths. A refused paid call is NOT counted against your free quota.
429
Rate limited
Daily quota exceeded for your tier — 10/day on a free key, 10,000/day on Builder. Quotas reset at 00:00 UTC.
Free vs paid: get_market_summary works with no key at all. A free pk_free_ key opens verify_before_pay, get_category_detail, get_niche_gaps, get_token_metrics, get_liveness against a shared daily allowance. The 6 paid tools — get_best_value_provider, get_changes, get_circular_signal, get_whale_activity, get_provider_revenue, get_report_data — require either an API key in X-Paddock-Key or an x402 micropayment. Every tool that carries a USDC price keeps that paid path whatever tier you are on.
— Reference

Endpoints

get_market_summaryKeyless · free
How big is agent commerce today? (The citation number.)
GET/api/mcp/summary

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.

Parameters
NameTypeRequiredDescription
No parameters.
Example request
Free tier — no API key required.
curl
copy
curl https://paddock.finance/api/mcp/summary
Example response
json
copy
{
  "tool": "get_market_summary",
  "tier": "free",
  "date": "2026-05-19",
  "summary": {
    "daily_transactions": 24180,
    "daily_volume_usdc": "$8,412",
    "unique_buyer_agents": 1247,
    "live_service_providers": 38,
    "registered_payment_endpoints": 812,
    "mpp_services": 64,
    "mcp_registry_servers": null
  },
  "mcp_registry_basis": "Suppressed. This count was capped by pagination limits in every era of the series (100 before 2026-07-24, 20,000 after) and has never been a measurement. It will return when the underlying count is real.",
  "endpoints_basis": "registered_payment_endpoints is an all-time count of payment endpoints listed in the upstream catalog. live_service_providers is the count of sellers observed settling in the last 24 hours. Different sources, different units, different windows, so the ratio between them is not a liveness rate.",
  "top_categories": [
    { "category": "LLM inference",       "daily_transactions": 9842, "providers": 6, "share_of_transactions": "41%" },
    { "category": "Data & scraping",     "daily_transactions": 4011, "providers": 5, "share_of_transactions": "17%" },
    { "category": "Search",              "daily_transactions": 3402, "providers": 2, "share_of_transactions": "14%" }
  ],
  "share_of_transactions_basis": "share_of_transactions is each category's share of CATEGORIZED agent-commerce transactions (named categories only; excludes the uncategorized 'other' bucket and unindexed ecosystem volume). It is NOT a share of summary.daily_transactions, which is the full-ecosystem total. Only the top 6 categories are returned, so the shown rows sum to <100% by design.",
  "insight": "LLM inference leads agent spending with 9,842 daily transactions across 6 providers.",
  "pro_features": "For niche gap analysis and report data, subscribe at https://paddock.finance/api-access",
  "subscription_url": "https://paddock.finance/api-access",
  "paddock_url": "https://paddock.finance/market"
}
get_category_detailFree key · free key
Who's selling in this category, and who's actually getting paid?
GET/api/mcp/category

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.

Parameters
NameTypeRequiredDescription
namestringyesCategory id: llm, data, search, infra, content, markets, payments, comms. Hyphenated forms (e.g. llm-inference) and common aliases are normalized onto these — e.g. inference→llm, scraping/social/translation→data, image→content, defi/trading/signals→markets.
Example request
Free tier — no API key required.
curl
copy
curl "https://paddock.finance/api/mcp/category?name=search"
Example response
json
copy
{
  "tool": "get_category_detail",
  "tier": "free",
  "date": "2026-05-19",
  "category": "Search",
  "category_id": "search",
  "summary": {
    "total_daily_transactions": 3402,
    "provider_count": 2,
    "market_status": "Open niche — fewer than 3 providers with real volume"
  },
  "services": [
    {
      "service": "Exa Search",
      "domain": "api.exa.ai",
      "daily_transactions": 2104,
      "daily_volume_usdc": "$73.64",
      "unique_buyers": 188,
      "reliability": { "uptime": "99%", "latency_ms": 412, "score": 94 }
    }
  ],
  "subscription_url": "https://paddock.finance/api-access"
}
get_niche_gapsFree key · free key · $0.01 per call
Where is demand outrunning supply?
GET/api/mcp/gaps

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.

Concentration analysis across every category in today's snapshot, ranked by opportunity_score = log10(1 + daily_transactions) / max(providers, 1). Each row includes share, top_provider_share, opportunity_score, and a signal (Consolidating / Open / Tightening / Mature). Requires a Paddock API key in X-Paddock-Key, or an x402 per-query payment ($0.01 USDC).

Parameters
NameTypeRequiredDescription
No parameters.
Example request
Free tier — no API key required.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  https://paddock.finance/api/mcp/gaps
Example response
json
copy
{
  "tool": "get_niche_gaps",
  "date": "2026-05-27",
  "paid_via": "api_key",
  "tier": "builder",
  "categories": [
    {
      "category": "LLM & inference",
      "category_id": "llm",
      "daily_transactions": 18500,
      "providers": 4,
      "share": 0.4920,
      "top_provider_share": 0.4216,
      "opportunity_score": 1.0681,
      "signal": "Mature — multiple providers serving demand",
      "paddock_url": "https://paddock.finance/market#llm"
    },
    {
      "category": "Markets & DeFi",
      "category_id": "markets",
      "daily_transactions": 1700,
      "providers": 3,
      "share": 0.0452,
      "top_provider_share": 0.6470,
      "opportunity_score": 1.0768,
      "signal": "Tightening — fillable opening",
      "paddock_url": "https://paddock.finance/market#markets"
    }
  ],
  "summary": "Markets & DeFi leads opportunity_score (1.0768); signal: Tightening — fillable opening.",
  "methodology": {
    "opportunity_score": "log10(1 + daily_transactions) / max(providers, 1)",
    "top_provider_share": "Largest single provider's share of this category's total txns.",
    "share": "Category's share of total snapshot transactions.",
    "signal_thresholds_first_match_wins": [
      "share >= 0.50                                   → Consolidating",
      "providers <= 2  AND daily_transactions >= 500   → Open",
      "providers <= 3  AND daily_transactions >= 200   → Tightening",
      "otherwise                                       → Mature"
    ]
  },
  "paddock_url": "https://paddock.finance/market"
}
get_best_value_providerPaid · $0.02
Which provider in this category should my agent pick?
GET/api/mcp/best-value

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 providers in the given category ranked by composite score: (success_rate_7d × 0.40) + (reputation_norm × 0.30) + ((1 − price_norm) × 0.30). Clients sort/filter client-side; the route returns the full data so you can replicate or override the ranking. Requires a Paddock API key or an x402 per-query payment ($0.02 USDC).

Parameters
NameTypeRequiredDescription
categorystringyesCategory id or alias: llm, data, search, infra, content, markets, payments, comms (plus aliases like inference, scraping, defi, trading).
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/best-value?category=infra"
Example response
json
copy
{
  "tool": "get_best_value_provider",
  "date": "2026-05-27",
  "category": "infra",
  "category_label": "Infra & compute",
  "paid_via": "api_key",
  "tier": "builder",
  "providers": [
    {
      "domain": "api.clusterprotocol.ai",
      "title": "Cluster Protocol",
      "price_usdc": 0.001,
      "liveness_score": 92,
      "success_rate_7d": 0.989,
      "tx_count": 10025,
      "unique_buyers": 412,
      "composite_score": 0.8763,
      "rank": 1
    }
  ],
  "formula": {
    "composite_score": "(success_rate_7d * 0.40) + (reputation_norm * 0.30) + ((1 - price_norm) * 0.30)",
    "reputation_norm": "log10(1 + unique_buyers) / log10(1 + max(unique_buyers in category))",
    "price_norm":      "price_usdc / max(price_usdc in category)",
    "defaults": {
      "no_bazaar_price":     "price_norm = 0.5 (neutral)",
      "no_liveness_data":    "success_rate_7d = 0.5 (neutral)",
      "reputation_max_zero": "reputation_norm = 0 for all"
    }
  },
  "paddock_url": "https://paddock.finance/market#infra"
}
get_livenessFree key · free key · $0.001 per call
Was this domain up at last night's probe, per someone who isn't the seller?
GET/api/mcp/liveness

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 share of probes that succeeded, 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.

Per-domain liveness lookup: up/down, 7-day share of probes that succeeded, and latency from the latest endpoint probe data. up = success_rate_7d ≥ 0.95. Coverage: TrustBench (trustbench.io), one nightly CSV — 545 domains / 6,610 endpoints as of 2026-11-08. A domain is what you look up; the endpoint count is how much probing sits behind those domains. A service missing from it may be newly launched or niche. A 404 "Domain not tracked in liveness data" means exactly that (a coverage limitation, not a server error); the _meta block on every response carries both counts — tracked_domains_count is the universe a lookup is against, and tracked_services_count counts the probed endpoints behind those domains. Requires a Paddock API key or an x402 per-query payment ($0.001 USDC — the cheapest tool in the API for high-volume polling).

Parameters
NameTypeRequiredDescription
domainstringyesHostname (e.g. api.example.com). www. prefix is stripped.
Example request
Free tier — no API key required.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/liveness?domain=blockrun.ai"
Example response
json
copy
{
  "tool": "get_liveness",
  "_meta": {
    "tracked_services_count": 1252,
    "source": "agent commerce endpoint liveness probes"
  },
  "paid_via": "api_key",
  "tier": "builder",
  "domain": "blockrun.ai",
  "up": true,
  "score": 95,
  "success_rate_7d": 1,
  "latency_p50_ms": 247,
  "latency_p95_ms": 892,
  "samples_7d": 1008,
  "last_probed_at": "2026-05-28T00:42:11Z"
}
get_changesPaid · $0.10
What changed since a date I name?
GET/api/mcp/changes

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.

Diff today's snapshot against an earlier date. Returns new_services, retired_services, category_movements (|delta_pp| ≥ 3), and top_movers (|pct_change| ≥ 50%). Lookback capped at 90 days (full-fidelity retention). Older slim snapshots downgrade gracefully — category-level diffs still work; per-service diffs are flagged unavailable. Requires a Paddock API key or an x402 per-query payment ($0.10 USDC).

Parameters
NameTypeRequiredDescription
sincestringyesEarlier date in YYYY-MM-DD. Capped at 90 days ago.
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/changes?since=2026-05-20"
Example response
json
copy
{
  "tool": "get_changes",
  "since_date": "2026-05-20",
  "today_date": "2026-05-27",
  "days_elapsed": 7,
  "paid_via": "api_key",
  "tier": "builder",
  "limited_to_rollup_only": false,
  "new_services": [
    { "domain": "api.newentrant.io", "title": "NewEntrant", "category": "data", "first_day_tx_count": 420 }
  ],
  "retired_services": [],
  "category_movements": [
    { "category": "LLM & inference", "category_id": "llm", "old_share": 0.5421, "new_share": 0.4920, "delta_pp": -5.01 }
  ],
  "top_movers": [
    { "domain": "scrape.x402.dev", "title": "Scrape", "category": "data", "old_tx_count": 1200, "new_tx_count": 1900, "pct_change": 0.583 }
  ],
  "summary": "7-day diff (2026-05-20 → 2026-05-27). 1 new, 0 retired, 1 top mover. 1 category shift ≥ 3pp.",
  "thresholds": { "category_movement_min_pp": 3, "top_mover_min_pct_change": 0.5 },
  "paddock_url": "https://paddock.finance/charts"
}
get_report_dataPaid · $0.99 · metadata free
What are the numbers behind the monthly report?
GET/api/mcp/report-data

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 structured JSON from the State of Agent Commerce monthly report — the Agent Commerce Index, category analysis, endpoint liveness, and protocol landscape. Requires a Paddock API key in X-Paddock-Key (Builder: current published month only; Pro Agent: full archive), or an x402 per-query payment ($0.99 USDC). Published monthly on the 1st. If the requested month has no report, returns a 200 with status:"unpublished".

Parameters
NameTypeRequiredDescription
monthstringnoReport month as YYYY-MM (e.g. 2026-06). Defaults to the latest published issue.
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  https://paddock.finance/api/mcp/report-data
Example response
json
copy
{
  "tool": "get_report_data",
  "month": "2026-06",
  "title": "The State of Agent Commerce — June 2026",
  "published_at": "2026-06-30T12:00:00Z",
  "table_of_contents": [
    "Agent Commerce Index",
    "Category analysis",
    "Endpoint liveness",
    "Protocol landscape",
    "Dark discovery"
  ],
  "paid_via": "api_key",
  "tier": "pro_agent",
  "data": {
    "agent_commerce_index": 61,
    "categories_tracked": 19,
    "open_niches": 4
  },
  "paddock_url": "https://paddock.finance/report/2026-06"
}
get_circular_signalPaid · $0.99
Is this facilitator's volume real, or is it paying itself?
GET/api/mcp/circular-signal

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.

The wash / circular-settlement signal, per facilitator (methodology v0.1). Returns cluster count, cluster volume (30d/7d), self-funding %, external-payer count, flagged share of settlement, and trend. A facilitator is flagged when self-funding share >= 75% AND distinct external payers < 5 over a 30-day window. Patterns attach to the facilitator only — no seller wallet addresses, operator identity, or per-wallet rows are ever returned. Requires a Paddock API key, or an x402 per-query payment ($0.99 USDC).

Parameters
NameTypeRequiredDescription
windowstringnoReporting window for the trend context: 7d or 30d (default 30d).
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/circular-signal?window=30d"
Example response
json
copy
{
  "tool": "get_circular_signal",
  "methodology_version": "v0.1",
  "snapshot_date": "2026-06-24",
  "paid_via": "api_key",
  "tier": "pro_agent",
  "detection_date": "2026-06-23",
  "days_since_detection": 4,
  "criteria": "self-funding share >= 75% AND distinct external payers < 5, over a 30-day window as of 2026-06-23",
  "facilitators": [
    {
      "facilitator": "meridian",
      "cluster_count": 2,
      "cluster_volume_usd": { "as_of": "2026-06-23", "d30": 215915.91, "d7": 41203.84 },
      "self_funding_pct": 100,
      "facilitator_observable_volume_usd": { "as_of": "2026-06-23", "d30": 259903.99 },
      "flagged_share_of_facilitator_volume_pct": 83.1,
      "external_payer_count": 0,
      "flagged_txns_snapshot_day": 286,
      "flagged_share_of_listed_pct": 1,
      "trend": "new"
    }
  ],
  "firewall_note": "Patterns are attributed to the facilitator only — no seller wallet addresses, operator identity, or per-wallet rows are exposed.",
  "paddock_url": "https://paddock.finance/methodology#circular"
}
get_whale_activityPaid · $0.99
Where did the large settlements go?
GET/api/mcp/whale-activity

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.

Large settlements / large movers over a window, aggregate only: amounts and counts by facilitator, by category, and by size band, plus per-category mover counts. Describes size and where, never who — no individual seller identity is returned. Requires a Paddock API key, or an x402 per-query payment ($0.99 USDC).

Parameters
NameTypeRequiredDescription
min_usdnumbernoLarge-settlement threshold in USD (default 1000).
windowintegernoMover comparison window in days, 1–90 (default 7).
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/whale-activity?min_usd=1000&window=7"
Example response
json
copy
{
  "tool": "get_whale_activity",
  "snapshot_date": "2026-06-24",
  "window_days": 7,
  "large_threshold_usd": 1000,
  "paid_via": "api_key",
  "tier": "pro_agent",
  "totals": { "large_settlement_providers": 3, "large_settlement_volume_usd": 48200 },
  "by_facilitator": [{ "facilitator": "meridian", "count": 4, "volume_usd": 31200 }],
  "by_category": [{ "category": "Markets & DeFi", "count": 2, "volume_usd": 22000 }],
  "size_bands": [
    { "band": "$100k+", "min_usd": 100000, "count": 0, "volume_usd": 0 },
    { "band": "$10k-$100k", "min_usd": 10000, "count": 1, "volume_usd": 22000 },
    { "band": "$1k-$10k", "min_usd": 1000, "count": 3, "volume_usd": 26200 }
  ],
  "movers_by_category": [{ "category": "LLM & inference", "surging": 5, "fading": 1 }],
  "firewall_note": "Aggregate only — size and where, never who.",
  "paddock_url": "https://paddock.finance/charts"
}
get_token_metricsFree key · free key · $0.01 per call
Is today's number a real move or ordinary noise?
GET/api/mcp/token-metrics

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.

The same chart-series the public /charts page reads, plus the Agent Commerce Index (ACI) series — queryable by metric and date range. Metrics: spend_share_over_time, daily_transactions, category_concentration, new_services, liveness_score, aci. First-party agent-commerce series only; third-party token spot price is intentionally excluded. Requires a Paddock API key, or an x402 per-query payment ($0.01 USDC).

Parameters
NameTypeRequiredDescription
metricstringyesWhich series to return: spend_share_over_time, daily_transactions, category_concentration, new_services, liveness_score, or aci.
daysintegernoLookback window in days, 1–730 (default 90). Ignored by the aci metric, which uses from/to.
categorystringnoCategory id for the category_concentration metric (e.g. llm).
fromstringnoStart month YYYY-MM (aci metric only).
tostringnoEnd month YYYY-MM (aci metric only).
Example request
Free tier — no API key required.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/token-metrics?metric=aci&from=2026-05&to=2026-06"
Example response
json
copy
{
  "tool": "get_token_metrics",
  "paid_via": "api_key",
  "tier": "pro_agent",
  "metric": "aci",
  "methodology_version": "1.0",
  "range": { "returned": 2, "from": "2026-05", "to": "2026-06" },
  "points": [
    { "month": "2026-05", "aci": 72 },
    { "month": "2026-06", "aci": 75 }
  ],
  "available_metrics": [
    "spend_share_over_time", "daily_transactions", "category_concentration",
    "new_services", "liveness_score", "aci"
  ],
  "source": "Same first-party series the public /charts page and ACI methodology page read from.",
  "paddock_url": "https://paddock.finance/charts"
}
get_provider_revenuePaid · $0.99
Who earns the most, and how much of the market can that answer see?
GET/api/mcp/provider-revenue

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.

Which providers earn the most, over a window of days, and how much of the market that answer can see. ATTRIBUTED universe only (never the full-ecosystem census): facilitator pass-through and circular-flagged wallets are excluded from the leaderboard; unresolved wallets are not dropped — they surface as one explicit unattributed row (transaction share only, no dollar figure exists for them). Reports whether the recipient list was complete every aggregated day, and flags (retroactive_exclusion_caveat) any day before 2026-07-28 where a wallet added to the exclusion lists afterward could not be retroactively re-checked. Requires a Paddock API key, or an x402 per-query payment ($0.99 USDC).

Parameters
NameTypeRequiredDescription
windowintegernoDays to aggregate, 1–90 (default 7).
topintegernoReturn only the top N providers by revenue_usd, 1–100 (default 20).
Example request
Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.
curl
copy
curl -H "X-Paddock-Key: YOUR_KEY" \
  "https://paddock.finance/api/mcp/provider-revenue?window=7&top=20"
Example response
json
copy
{
  "tool": "get_provider_revenue",
  "universe": "attributed",
  "universe_note": "Attributed universe only — resolved sellers with facilitator pass-through and circular-flagged wallets excluded (never the full-ecosystem census).",
  "snapshot_date": "2026-06-24",
  "paid_via": "api_key",
  "tier": "pro_agent",
  "window": {
    "dates": ["2026-06-18", "2026-06-19", "2026-06-20", "2026-06-21", "2026-06-22", "2026-06-23", "2026-06-24"],
    "days_requested": 7,
    "days_aggregated": 7,
    "list_complete_all_days": true
  },
  "providers": [
    { "domain": "api.example.com", "category": "llm", "revenue_usd": 4200.5, "tx_count": 3100, "unique_buyers": 210 }
  ],
  "providers_truncated": false,
  "providers_total_count": 42,
  "market_visibility": { "resolved_txns": 9000, "listed_txns": 12000, "coverage_pct_listed": 0.75 },
  "unattributed": { "revenue_usd": null, "tx_count": 3000, "share_of_listed_txns": 0.25, "note": "No dollar amount exists anywhere in the snapshot for unresolved wallets — see the full note in a live response." },
  "retroactive_exclusion_caveat": null,
  "paddock_url": "https://paddock.finance/charts"
}

See the OpenAPI schema for the full contract on every endpoint.

— SDKs

Code examples

Three minimal clients that call get_market_summary and print the top three categories. Substitute your own key.

curl
bash
copy
export PADDOCK_API_KEY=pk_builder_YOUR_KEY

curl -s -H "X-Paddock-Key: $PADDOCK_API_KEY" \
  https://paddock.finance/api/mcp/summary \
  | jq '.summary, .top_categories[0:3]'
Python
python
copy
import os, requests

PADDOCK_KEY = os.environ["PADDOCK_API_KEY"]
r = requests.get(
    "https://paddock.finance/api/mcp/summary",
    headers={"X-Paddock-Key": PADDOCK_KEY},
    timeout=10,
)
r.raise_for_status()
data = r.json()
print(f"Today: {data['summary']['daily_transactions']} txns, "
      f"{data['summary']['daily_volume_usdc']}")
for c in data["top_categories"][:3]:
    print(f"  {c['category']:20} {c['daily_transactions']:>6} txns")
JavaScript
javascript
copy
const PADDOCK_KEY = process.env.PADDOCK_API_KEY;

const res = await fetch(
  "https://paddock.finance/api/mcp/summary",
  { headers: { "X-Paddock-Key": PADDOCK_KEY } },
);
if (!res.ok) throw new Error(`Paddock ${res.status}`);
const data = await res.json();

console.log(`Today: ${data.summary.daily_transactions} txns, ${data.summary.daily_volume_usdc}`);
for (const c of data.top_categories.slice(0, 3)) {
  console.log(`  ${c.category.padEnd(20)} ${String(c.daily_transactions).padStart(6)} txns`);
}
— Growing

When you outgrow the free tier

Building something with the free tier? Build on Paddock is the walkthrough — worked examples, what each free tool is actually good for, and how to size your usage. This section is the reference; that is the tutorial.

get_market_summary needs no key at all. Everything else starts with a free key: 10 calls per UTC day, shared across verify_before_pay, get_category_detail, get_niche_gaps, get_token_metrics, get_liveness — one counter for all of them, not 10 each.

1 — Request a key
bash
copy
curl -X POST https://paddock.finance/api/keys/free \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Self-serve and instant — there is no approval step and nothing to wait for. The key is in the response body and a copy is emailed to the address you give. Requesting again with the same address returns the same key rather than minting a second one, so a lost key is one command away. ([email protected] is for questions and commercial licensing, not for requesting a key.)

2 — First call
bash
copy
export PADDOCK_API_KEY=pk_free_YOUR_KEY

curl -s -H "X-Paddock-Key: $PADDOCK_API_KEY" \
  'https://paddock.finance/api/mcp/category?name=llm' \
  | jq '.usage, .summary'
3 — Meter yourself with usage

Every successful free-key response carries a usage object, so you never have to guess how much quota is left or when it resets. Quotas reset at 00:00 UTC.

json
copy
{
  "tool": "get_category_detail",
  "tier": "free_key",
  "usage": {
    "used": 3,
    "limit": 10,
    "remaining": 7,
    "resets_at": "2026-08-11T00:00:00.000Z"
  },
  "summary": { "total_daily_transactions": 5000, "provider_count": 30 },
  "services": [ /* … */ ]
}
4 — What the limit looks like when you hit it
http
copy
HTTP/1.1 429 Too Many Requests

{
  "tool": "get_liveness",
  "status": "rate_limited",
  "error": "free_tier_daily_limit_reached",
  "usage": { "used": 11, "limit": 10, "remaining": 0,
             "resets_at": "2026-08-11T00:00:00.000Z" },
  "upgrade": {
    "pay_per_query": "Settle the tool's USDC price via x402 at call time — no subscription, no key.",
    "builder": "Builder — $99/mo, 10,000 calls/day, every paid tool.",
    "url": "https://paddock.finance/api-access"
  }
}
Over MCP

The connector URL is the same for every tier. Pass the key as the api_key argument on the tool call and the server forwards it as X-Paddock-Key.

json
copy
{
  "mcpServers": {
    "paddock": {
      "url": "https://paddock.finance/api/mcp/mcp"
    }
  }
}
Free trial and free key are different things. The free trial is 1 call per IP per day, shared across all paid tools, with no key at all — a zero-friction taste, and it still works. The free key is the workflow tier above it: 10 calls/day against the 5 tools listed above, tied to your key rather than your IP. Neither unlocks the paid tools — those need an x402 payment or a Builder key.
Free for development and internal use. Redistribution, resale, or serving Paddock data to your end users requires a commercial license — see paddock.finance/api-access or contact [email protected].
— Limits

Rate limits

Quotas are per API key (or per IP for the Free tier) and reset at 00:00 UTC. Every gated response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix epoch seconds when the window resets). Over-limit calls return HTTP 429 with a JSON body describing the limit, current usage, and reset time.

TierDaily limitIdentified by
Keyless toolsNo limitNo key required
Free trial (paid tools)1 call/IP/dayNo key required — counted per IP
Free key10 calls/day, shared across the 5 free-key toolsAPI key (X-Paddock-Key)
Builder10,000 calls/dayAPI key (X-Paddock-Key)
Pro AgentUnlimitedAPI key (X-Paddock-Key)
x402 per-queryNo limit — pay per callPayment receipt
Example 429 response
http
copy
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747958400

{
  "error": "rate_limit_exceeded",
  "tier": "builder",
  "limit": 10000,
  "reset_at": "2026-05-20T00:00:00Z",
  "upgrade_url": "https://paddock.finance/api-access"
}
— Why this data

Why Paddock — and why now.

The AI agent economy is on-chain and observable now. Every transaction, every wallet, every category, all of it is open, and we're capturing it nightly. Paddock is pre-payment verification for AI agents, watching all of it live.

We snapshot every service, every wallet, every transaction. Every night since launch. After six months, that's data nobody else has.

You're integrating early. That's the point.

— Audiences

Who uses Paddock API

01 · For agents in production
Live data inside the agent loop.

Trading agents, content agents, and research agents that need real-time category data, niche detection, and cross-protocol intelligence to make payment decisions.

02 · For builders shipping with agents
Pre-payment verification for AI agents.

Indie devs and small teams building tools that ride on Paddock data — wallet labeling, category routing, agent leaderboards.

03 · For analysts and researchers
Cite-worthy commerce metrics.

VCs, hedge funds, and journalism outlets pulling historical and real-time agent commerce data into reports and decisions.

— Use cases

What you can build

Eight ways teams plug Paddock into agents, tools, and research. Most work zero-code inside Claude via the MCP connector or the skill one-liner; all of them work over the REST API below.

For agents
Route every payment to the best live provider

Before an agent pays, rank the live providers in a category by reliability, reputation, and price, then route to the winner. If it goes down, the next call returns a new #1 automatically.

For agents
Gate payments on a liveness check

Confirm a service is actually up before committing USDC. The cheapest call in the API ($0.001), built to sit inside the payment loop at high volume.

For builders
Find the open niche worth building in

Rank every category by concentration and opportunity score to see what's saturated and what's wide open, before you commit to building.

For builders
Monitor what changed overnight

Diff today against any prior date for new services, retired ones, category share shifts, and top movers, to power a Discord or Telegram digest or an anomaly alert.

For analysts
Pull cite-worthy metrics into a memo

Clean JSON of volume, category breakdowns, and provider counts for VC memos, fund diligence, and journalism. No scraping.

For builders
Embed live agent-commerce stats

Drop daily-granular numbers straight into a dashboard, newsletter, or dev tool, and keep them current with the change feed.

For investors
Get alerted when a category concentrates

Watch top-provider share and the Open / Tightening / Consolidating signal flip, to catch a winner-take-all moment or a fresh opening as it happens.

For builders
Pipe the monthly report into your stack

Pull the State of Agent Commerce report as structured JSON: the Agent Commerce Index, category analysis, and protocol landscape, ready for dashboards and workflows.

— Support

Stuck? We'll help.

DM @PaddockFinance on X for help. We respond within 24 hours.

Wondering whose numbers sit underneath ours? Every upstream we read, and the licence each one is used under, is listed at Data sources and licences.

Message us on X →
— Get started

Ready to integrate Paddock?

Subscribe — Builder $99/mo →Talk to us first →
Free · no key

Builder tier includes 10,000 queries/day and access to all 13 MCP tools.

Keep going

What to read next.

x402 market
What agents pay for.

Real transaction volume by category. Three sources merged into one live table.

See the market →
For the trader
Track agent tokens.

Live Virtuals leaderboard. ROI, volume, market cap. Sortable. Free.

See the leaderboard →