> For the complete documentation index, see [llms.txt](/llms.txt). For the full corpus in one file, see [llms-full.txt](/llms-full.txt). This page is also available as HTML at [/docs](/docs).
# Paddock API & MCP — Documentation

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

Agent payments have no chargeback. Paddock is pre-payment verification for AI agents. Live on-chain data on what AI agents buy across the x402 and MPP payment protocols. Free dashboards and a free MCP server; a paid REST API and a monthly *State of Agent Commerce* report.

Already have a Paddock API key? Skip to [Authentication](#authentication). Just evaluating? Browse the [endpoints](#endpoints) to see what's possible.

## Quickstart

Once you have a Paddock API key, confirm it works in ~30 seconds. (No key yet? Subscribe at [/api-access](https://paddock.finance/api-access) — Builder $99/mo includes 10,000 queries/day.)

    curl -H "X-Paddock-Key: pk_builder_YOUR_KEY" \
      https://paddock.finance/api/mcp/summary

Expected response: JSON with `daily_transactions`, `daily_volume_usdc`, and `top_categories`. If you see this, you're connected.

## Use Paddock in Claude (MCP)

Connect Paddock as an MCP server and ask about agent commerce in plain language. `get_market_summary` needs no key at all. `get_category_detail` and the other free-key tools need a free key — one email, no card — against a shared daily budget.

1. In Claude, open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Paste the connector URL below and save.
4. Ask Paddock anything.

Connector URL:

    https://paddock.finance/api/mcp/mcp

Try asking:

- "What are AI agents spending on right now?"
- "Which agent commerce category has the most room for a new entrant?"
- "Show me what's in the LLM inference category."

**Paid tools work in Claude too.** Every paid tool (niche gaps, best-value, liveness, changes, report data, circular signal, whale activity, token metrics) accepts an `api_key` argument — pass your Paddock key when Claude calls the tool and it runs the paid query over the connector, no separate REST call needed. Omit it to use the one free trial call per day or to see the x402 pay-per-query details. The same tools are also available as direct REST calls; see the [endpoints](#endpoints) below.

## Authentication

Pass your key as the `X-Paddock-Key` header on every request. Keys are issued by email after a Builder ($99/mo) or Pro Agent ($499/mo) subscription completes.

    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):

    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.

**Free key.** A `pk_free_` key is self-serve, instant, and needs only an email address — no card, no approval step:

    curl -X POST https://paddock.finance/api/keys/free \
      -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

It opens `verify_before_pay`, `get_category_detail`, `get_niche_gaps`, `get_token_metrics` and `get_liveness` against **10 calls/day shared between all five** — one counter, not ten each. `get_market_summary` needs no key at all. Everything else takes a Builder/Pro Agent key or a per-query x402/MPP payment.

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](https://paddock.finance/api-access) or contact hello@paddock.finance.

### Error responses

- **401 — Invalid key.** The key is missing, malformed, or has been cancelled. Check your welcome email or DM us on X.
- **402 — Payment required.** You called a paid endpoint without a key. Either subscribe, or include a valid x402 `X-Payment-Receipt` header.
- **429 — Rate limited.** Daily quota exceeded for your tier. Quotas reset at 00:00 UTC. See [Rate limits](#rate-limits) below.

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` and `get_liveness` against 10 calls/day shared between all five. The six 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.

## Why Paddock

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.*

## Who uses Paddock

- **For agents in production** — trading agents, content agents, and research agents that need real-time category data, niche detection, and cross-protocol intelligence to make payment decisions.
- **For builders shipping with agents** — indie devs and small teams building tools that ride on Paddock data — wallet labeling, category routing, agent leaderboards.
- **For analysts and researchers** — VCs, hedge funds, and journalism outlets pulling historical and real-time agent commerce data into reports and decisions.

## What you can build

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

- **Route every payment to the best live provider** (for agents) — 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. Tools: `get_best_value_provider`.
- **Gate payments on a liveness check** (for agents) — 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. Tools: `get_liveness`.
- **Find the open niche worth building in** (for builders) — Rank every category by concentration and opportunity score to see what's saturated and what's wide open, before you commit to building. Tools: `get_niche_gaps`.
- **Monitor what changed overnight** (for builders) — 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. Tools: `get_changes`.
- **Pull cite-worthy metrics into a memo** (for analysts) — Clean JSON of volume, category breakdowns, and provider counts for VC memos, fund diligence, and journalism. No scraping. Tools: `get_market_summary`, `get_category_detail`.
- **Embed live agent-commerce stats** (for builders) — Drop daily-granular numbers straight into a dashboard, newsletter, or dev tool, and keep them current with the change feed. Tools: `get_market_summary`, `get_changes`.
- **Get alerted when a category concentrates** (for investors) — 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. Tools: `get_niche_gaps`, `get_changes`.
- **Check an endpoint before paying it** (for buying agents) — One call returns `route: true/false/"inconclusive"` with evidence: is the endpoint live right now, does its 402 contract match what you expect, has it settled real volume recently, and how its price compares. Tools: `verify_before_pay`.
- **Pipe the monthly report into your stack** (for builders) — Pull the State of Agent Commerce report as structured JSON: trends, category breakdowns, protocol comparison and reliability, ready for dashboards and workflows. Any Agent Commerce Index block in it is a retained historical print — the index is suspended (ADR 0006) and no new prints are computed. Tools: `get_report_data`.

## Endpoints

See the [OpenAPI schema](https://paddock.finance/api/mcp/openapi.json) for the full contract on every endpoint.

check_payee: fast payee check from Paddock's settlement record, free, no live probe. Use before every payment; use verify_before_pay for a full check.

### verify_before_pay — Free key · $0.25 per call

`GET /api/mcp/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 - and a call that states no expectations at all gets `"inconclusive"`, because there was nothing to compare. 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.

**Call this before your agent authorizes any x402 payment.** One query returns `route: true` / `false` / `"inconclusive"` with evidence: is the endpoint live right now, does its 402 contract match what you expect (network, asset, seller, price), has it settled real volume recently from wallets that aren't its operator's, and how its price compares. The independent pre-payment check no seller can self-report.

| Parameter | Required | Description |
|---|---|---|
| `endpoint_url` | one of | The resource URL your agent is about to pay. This is what gets probed. |
| `pay_to` | one of | **Checked.** The recipient wallet from the 402 you are about to settle. If it is not one of the recipients the live challenge names, `route` is `false` and `pay_to` is in `mismatched_fields`. |
| `expect_network` | no | Network you expect (`eip155:8453` or `base`). Mismatch returns `route:false`. |
| `expect_asset` | no | Asset contract address you expect. Mismatch returns `route:false`. |
| `expect_seller` | no | Seller domain you expect. Mismatch returns `route:false`. |
| `expect_price_usdc` | no | Price in dollars you expect, e.g. `0.01`. **Any** difference returns `route:false`. |

    curl -s -H "X-Paddock-Key: pk_free_YOUR_KEY" \
      'https://paddock.finance/api/mcp/verify-before-pay?endpoint_url=https://api.example.com/x402/search&expect_price_usdc=0.01'

**Read `route` with `=== true`.** It is the JSON literal `true`, the JSON literal `false`, or the **string** `"inconclusive"`. A truthiness test passes on `"inconclusive"`, and that 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 used to return `true` on the strength of a readable 402 alone. The summary reads: "Nothing was compared. Pass pay_to or expect_* for a verdict; for liveness alone call get_liveness." If all you want is whether the endpoint is answering, that is `get_liveness`.

**A rate-limited endpoint is not an endpoint that does not charge.** From `verify_before_pay/0.8`, HTTP 429 on every attempt returns the reason code `live_rate_limited` and 503/504 return `live_temporarily_unavailable`, where all three previously arrived as `live_no_payment_requirements` alongside a genuine 200. A host that rate-limits us is healthy and declining to serve *us*, right now — the opposite of an endpoint that is free, and it implies the opposite action: back off and retry rather than drop the provider. Where the host names a wait, `attempts[].retry_after_seconds` carries it; that field is null, never zero, when it did not. No verdict moved — liveness was `"inconclusive"` for all of these before and is `"inconclusive"` now, and `route` is untouched — so the bump is for anyone who branches on or counts the reason code, not the verdict. Expect `live_no_payment_requirements` to get less frequent at the boundary: that is us classifying it better, not endpoints behaving differently.

**And neither is a broken one.** From `verify_before_pay/0.10`, the two causes 0.8 left inside the general code are named as well: any other 5xx on every attempt returns `live_server_error` — 500, 502, and the Cloudflare origin-error family — and HTTP 525/526 returns `live_tls_origin_failure`, meaning the seller's edge could not complete TLS to the seller's own origin, most often an expired origin certificate. Both were arriving as `live_no_payment_requirements` alongside a genuine 200. A broken host is not a free host and is not a gone host, and an origin certificate that expired is a seller-side outage with a named fix rather than a fact about price. Again no verdict moved: all of these were `"inconclusive"` before and are `"inconclusive"` now. What `live_no_payment_requirements` now covers is the case it is named for — an endpoint that answered `200` and did not ask for payment — plus a non-404 4xx and the mixed responses, where two attempts failed two different ways and claiming either specific cause would assert more than we observed. On a clean 200 the summary now says so in as many words: *not live for payment*, which is neither a pass nor a claim that the endpoint is free.

**The probe backs off rather than pushing through.** The POST is not attempted after a 429, so a rate-limited host produces exactly one row in `attempts[]` rather than two requests fired milliseconds apart at a host that has just asked us to stop. Scoped to 429 deliberately: a 503 is also the ordinary shape of a service that does not implement GET, where the POST is exactly what finds the challenge.

**From `verify_before_pay/0.11` that covers the whole call.** Alongside the probe we read the seller's self-declared config at two `.well-known` spellings, and until 0.11 those two GETs ran concurrently with the probe — already in flight when the 429 arrived, so a rate-limited host received three requests from us and the two it got after asking us to stop were the two that are not the point of the call. They now run after the probe and are skipped entirely when it came back 429: **a rate-limited host gets one request.** Where they are skipped the response says so rather than reading as a seller who publishes nothing — `checks.contract.self_declared.fetch_skipped_reason` is `"probe_rate_limited"` and the reason code is `contract_self_declared_not_fetched`, where `contract_self_declared_unavailable` continues to mean we looked at both spellings and found none. "We did not look" and "we looked and there is nothing" are different facts about a seller and only one of them is a mark against them. The cost is latency on the common path: the config fetch starts after the probe returns rather than alongside it.

The five checks, each with its own `status`, `universe`, `basis` and `as_of`:

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: a 200 means the endpoint did not ask for payment, which is a different fact.
2. **Contract match** — the decoded 402 against your `expect_*` parameters and against the seller's own published `.well-known/x402.json`. Any mismatch is `route:false` and names the field. Absence of a published config is not a mismatch; contradiction of one is.
3. **Settlement recency** — last observed settlement plus observed 7/30-day counts from Paddock's nightly snapshots. These are Σ of nightly rolling-24h captures taken ~24h apart, which **approximates** a calendar window and is not one; `days_present_7d` / `days_present_30d` say how many nights actually carried the target.
4. **Circular signal** — flagged-cluster membership and operator-funded share where the detector's facilitator coverage reaches. Outside that coverage it returns `"not_assessed"` with a basis naming what was in scope — 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.

**There is no success-rate field, deliberately.** Paddock observes settlements, not attempted calls: a payment that failed leaves no row in the record, so a rate computed from it could only ever be 100%. Recency and frequency are reported instead, and the response says so in its own body.

`schema_version` and `checked_at` are on every response, including errors, so verdicts can be stored now and graded against outcomes later. Responses are never cached — the value of the answer is that it was taken at `checked_at`.

Inconclusive liveness makes the whole verdict `"inconclusive"`, even when settlement history and the circular check both look perfect: without a readable 402 we do not know what the endpoint charges now. So does supplying no expectations at all, for the different reason that nothing was compared. A **hard** false — a contract mismatch, a flagged cluster, a 404/410 — still wins over either.

### get_market_summary — Keyless · free

`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: none.

    curl https://paddock.finance/api/mcp/summary

Example response:

```json
{
  "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": 1402
  },
  "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_detail — Free key

`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:

- `name` (string, required) — Category 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`.

    curl "https://paddock.finance/api/mcp/category?name=search"

Example response:

```json
{
  "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_gaps — Free key · $0.01 per call

`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: none.

    curl -H "X-Paddock-Key: YOUR_KEY" \
      https://paddock.finance/api/mcp/gaps

Example response:

```json
{
  "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"
}
```

402 response sample (no key, no x402 receipt) — exactly what the live endpoint returns when a request arrives without auth. This is what your agent (or HTTP client) should expect to negotiate against:

```json
{
  "tool": "get_niche_gaps",
  "status": "pro_required",
  "message": "Concentration analysis requires a Paddock API key or an x402 per-query payment.",
  "subscribe": {
    "options": [
      { "tier": "Builder",   "price": "$99/month",  "queries": "10,000/day",          "url": "https://buy.stripe.com/3cIcN62rD63m3fB4hPcbC02" },
      { "tier": "Pro Agent", "price": "$499/month", "queries": "Unlimited + archive", "url": "https://buy.stripe.com/6oUbJ26HTbnGdUfbKhcbC03" }
    ],
    "signup_page": "https://paddock.finance/api-access"
  },
  "pay_per_query": { "price": "$0.01 USDC per query", "protocol": "x402", "network": "Base (eip155:8453)" }
}
```

### get_best_value_provider — Paid · $0.02

`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:

- `category` (string, required) — Category id or alias: `llm`, `data`, `search`, `infra`, `content`, `markets`, `payments`, `comms` (plus aliases like `inference`, `scraping`, `defi`, `trading`).

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/best-value?category=infra"

Example response:

```json
{
  "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_liveness — Free key · $0.001 per call

`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 — 932 domains / 6,918 endpoints as of 2026-09-15. 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:

- `domain` (string, required) — Hostname (e.g. `api.example.com`). `www.` prefix is stripped.

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/liveness?domain=blockrun.ai"

Example response:

```json
{
  "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_changes — Paid · $0.10

`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:

- `since` (string, required) — Earlier date in `YYYY-MM-DD`. Capped at 90 days ago.

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/changes?since=2026-05-20"

Example response:

```json
{
  "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_data — Paid · $0.99 · metadata free

`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 — trends, category breakdowns, protocol comparison, and reliability. Any Agent Commerce Index block is a retained historical print: the index is **suspended** (ADR 0006), existing prints are served unmodified and no new prints are computed. 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:

- `month` (string, optional) — Report month as `YYYY-MM` (e.g. `2026-06`). Defaults to the latest published issue.

    curl -H "X-Paddock-Key: YOUR_KEY" \
      https://paddock.finance/api/mcp/report-data

Example response:

```json
{
  "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_signal — Paid · $0.99

`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:

- `window` (string, optional) — Reporting window for the trend context: `7d` or `30d` (default `30d`).

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/circular-signal?window=30d"

Example response:

```json
{
  "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,
      "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/paddock/methodology/circular-volume"
}
```

### get_whale_activity — Paid · $0.99

`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:

- `min_usd` (number, optional) — Large-settlement threshold in USD (default 1000).
- `window` (integer, optional) — Mover comparison window in days, 1–90 (default 7).

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/whale-activity?min_usd=1000&window=7"

Example response:

```json
{
  "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_provider_revenue — Paid · $0.99

`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:

- `window` (integer, optional) — Days to aggregate, 1–90 (default 7).
- `top` (integer, optional) — Return only the top N providers by `revenue_usd`, 1–100 (default 20).

    curl -H "X-Paddock-Key: YOUR_KEY" \
      "https://paddock.finance/api/mcp/provider-revenue?window=7&top=20"

Example response:

```json
{
  "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"
}
```

### get_token_metrics — Free key · $0.01 per call

`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.

First-party time series from Paddock's own census: spend share, daily transactions, concentration, new services, liveness score — the same chart-series the public /charts page reads, queryable by metric and date range. The `aci` metric returns the frozen Agent Commerce Index series: **suspended** (ADR 0006), existing prints retained and served, no new prints computed, so that series does not advance. 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:

- `metric` (string, required) — Which series to return: `spend_share_over_time`, `daily_transactions`, `category_concentration`, `new_services`, `liveness_score`, or `aci`.
- `days` (integer, optional) — Lookback window in days, 1–730 (default 90). Ignored by the `aci` metric, which uses `from`/`to`.
- `category` (string, optional) — Category id for the `category_concentration` metric (e.g. `llm`).
- `from` (string, optional) — Start month `YYYY-MM` (`aci` metric only).
- `to` (string, optional) — End month `YYYY-MM` (`aci` metric only).

    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
{
  "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"
}
```

## Code examples

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

```bash
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
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
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`);
}
```

## 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.

| Tier           | Daily limit             | Identified by                |
| -------------- | ----------------------- | ---------------------------- |
| Free MCP       | 1,000 calls/day         | IP address (x-forwarded-for) |
| Builder        | 10,000 calls/day        | API key (X-Paddock-Key)      |
| Pro Agent      | Unlimited               | API key (X-Paddock-Key)      |
| x402 per-query | No limit — pay per call | Payment receipt              |

Example 429 response:

```http
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"
}
```

## Support

Stuck? We'll help. DM **@PaddockFinance** on X for help — we respond within 24 hours: https://x.com/PaddockFinance

## Get started

- Subscribe — Builder $99/mo: https://paddock.finance/api-access
- Builder tier includes 10,000 queries/day and access to all ten MCP tools.

## Related

- Market — live x402 market by category: https://paddock.finance/market
- Charts — time-series agent commerce charts: https://paddock.finance/charts
- Report — the State of Agent Commerce monthly report: https://paddock.finance/report
- Methodology — how Paddock sources, snapshots, and scores data: https://paddock.finance/methodology