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

Paddock is the neutral, citable data layer for AI agent commerce: 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. This exposes the two free, read-only tools — `get_market_summary` and `get_category_detail` — so no API key is required.

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.

### 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` and `get_category_detail` work without a key. The eight paid tools — `get_niche_gaps`, `get_best_value_provider`, `get_liveness`, `get_changes`, `get_report_data`, `get_circular_signal`, `get_whale_activity`, `get_token_metrics` — require either an API key in `X-Paddock-Key` or an x402 micropayment.

## 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 the live, neutral, citable data layer for what agents actually do.

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`.
- **Pipe the monthly report into your stack** (for builders) — Pull the State of Agent Commerce report as structured JSON: the Agent Commerce Index, category analysis, and protocol landscape, ready for dashboards and workflows. Tools: `get_report_data`.

## Endpoints

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

### get_market_summary — Free

`GET /api/mcp/summary`

Returns current x402 transaction volume, top spending categories, live server count, and market overview. Use this to answer questions about the current state of agent commerce.

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
  },
  "top_categories": [
    { "category": "LLM inference",       "daily_transactions": 9842, "providers": 6, "share_of_volume": "41%" },
    { "category": "Data & scraping",     "daily_transactions": 4011, "providers": 5, "share_of_volume": "17%" },
    { "category": "Search",              "daily_transactions": 3402, "providers": 2, "share_of_volume": "14%" }
  ],
  "share_of_volume_basis": "share_of_volume 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

`GET /api/mcp/category`

Returns all services in a category with transaction counts, pricing, and reliability scores.

Parameters:

- `name` (string, required) — Category id: `llm`, `data`, `search`, `infra`, `content`, `trading`, `payments`, `social`, `translation`, `image`. Hyphenated forms (e.g. `llm-inference`) and common aliases are normalized.

    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 — Paid (API key or x402, $0.01 USDC)

`GET /api/mcp/gaps`

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 (API key or x402, $0.02 USDC)

`GET /api/mcp/best-value`

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 — Paid (API key or x402, $0.001 USDC)

`GET /api/mcp/liveness`

Per-domain liveness lookup: up/down, 7-day success rate, and latency from the latest endpoint probe data. `up = success_rate_7d ≥ 0.95`. Coverage: ~1,200 services across the agent commerce ecosystem are probed — large or newly-launched services may not yet be indexed. A 404 "Domain not tracked in liveness data" means exactly that (a coverage limitation, not a server error); the response includes `tracked_services_count` so you know the size of the universe you're querying. Successful responses carry a `_meta` block with the same count. 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 (API key or x402, $0.10 USDC)

`GET /api/mcp/changes`

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 (API key or x402, $0.99 USDC)

`GET /api/mcp/report-data`

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:

- `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 (API key or x402, $0.99 USDC)

`GET /api/mcp/circular-signal`

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",
  "criteria": "self-funding share >= 75% AND distinct external payers < 5, over a 30-day window",
  "facilitators": [
    {
      "facilitator": "meridian",
      "cluster_count": 2,
      "cluster_volume_usd": { "d30": 215915.91, "d7": 41203.84 },
      "self_funding_pct": 100,
      "external_payer_count": 0,
      "flagged_txns_30d": 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 (API key or x402, $0.99 USDC)

`GET /api/mcp/whale-activity`

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_token_metrics — Paid (API key or x402, $0.01 USDC)

`GET /api/mcp/token-metrics`

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:

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