---
name: paddock-agent-commerce
description: Query live AI agent commerce data from Paddock — market summaries, category breakdowns, niche/opportunity analysis, provider rankings, endpoint liveness, daily change diffs, and monthly report data across the x402 and MPP payment protocols. Use when an agent needs to route a payment to the best live provider, find an open market niche, verify a service is live before paying, monitor what changed overnight, or cite agent-commerce metrics.
homepage: https://paddock.finance
documentation: https://paddock.finance/docs
mcp_server: https://paddock.finance/api/mcp/mcp
---
# Paddock — Agent Commerce Data
Paddock is the neutral, citable data layer for AI agent commerce. It snapshots every service, wallet, and transaction across the x402 and MPP payment protocols nightly. Use Paddock to make payment decisions, find market gaps, verify liveness, and cite commerce metrics.
## If you were sent here by a one-liner
Route by what your host can do:
- **If you can add MCP connectors yourself** (Claude Code, shell agents, IDE agents): connect `https://paddock.finance/api/mcp/mcp` as a custom MCP connector, then call `get_market_summary` to confirm the connection is live. The free tools need no API key.
- **If you cannot add connectors** (Claude Desktop, web chat): don't make the user wait. **First** answer their question now over free REST — `GET https://paddock.finance/api/mcp/summary` (no key) returns the current market summary. **Then**, so the tools are there next time, give the user these steps in plain language:
  1. Open **Settings → Connectors**.
  2. Choose **Add custom connector**.
  3. Paste this URL: `https://paddock.finance/api/mcp/mcp`
  4. Save. The free tools (`get_market_summary`, `get_category_detail`) work right away — no key or sign-up.
## Verify you're connected
Call `get_market_summary` — it's free and takes no parameters or key. Example call and a truncated response envelope:

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

```json
{
  "tool": "get_market_summary",
  "tier": "free",
  "date": "YYYY-MM-DD",
  "summary": { "daily_transactions": …, "live_service_providers": …, "…": … },
  "top_categories": [ { "category": "…", "providers": …, "share_of_volume": "…" } ],
  "insight": "…"
}
```
If the response contains `"tool": "get_market_summary"`, you're connected and the free tools are working.
## How to connect
- **MCP (recommended, zero-code in Claude):** add `https://paddock.finance/api/mcp/mcp` as a custom connector (Settings → Connectors). The free tools work with no key.
- **REST:** call the endpoints below directly. Base URL `https://paddock.finance/api/mcp`.
## Authentication and payment
- Free tools require no auth: `get_market_summary`, `get_category_detail`.
- Paid tools require **either** a Paddock API key in the `X-Paddock-Key` header **or** an x402 micropayment (USDC on Base, `eip155:8453`).
- **Free trial:** your first paid call each UTC day is free with no key — one trial call per day, shared across all paid tools (via the Paddock MCP server), then the 402 applies. Subscribe for more: Builder $99/mo, 10,000 calls/day, at https://paddock.finance/api-access.
- A paid request with no auth returns HTTP **402** with subscribe options and the per-query x402 price. Negotiate against that 402, then retry with a payment receipt.
- Rate limits reset at 00:00 UTC. Over-limit returns HTTP **429** with `X-RateLimit-*` headers.
## When to use each tool
| Tool | Use it to… | Key param | Price |
| --- | --- | --- | --- |
| `get_market_summary` | Get the current state of agent commerce: volume, top categories, live provider count. Start here. | — | free |
| `get_category_detail` | List every service in one category with tx counts, pricing, reliability. | `name` | free |
| `get_best_value_provider` | Before paying, rank live providers in a category and route to the winner. | `category` | $0.02 |
| `get_liveness` | Confirm a single domain is up before committing USDC. Cheapest call — safe for high-volume polling inside the payment loop. | `domain` | $0.001 |
| `get_niche_gaps` | Find open or tightening niches across all categories, ranked by opportunity score. | — | $0.01 |
| `get_changes` | Diff today vs an earlier date for new/retired services, category shifts, and top movers. Powers digests and anomaly alerts. | `since` (YYYY-MM-DD, ≤90d) | $0.10 |
| `get_report_data` | Pull the monthly State of Agent Commerce report as structured JSON (Agent Commerce Index, category analysis, protocol landscape). | `month` (YYYY-MM, optional) | $0.99 |
| `get_circular_signal` | Per-facilitator wash / circular-settlement signal (methodology v0.1): cluster count, self-funding %, external-payer count, flagged share, and trend. Attributed to the facilitator only — no seller wallets or operator identity. | `window` (`7d`/`30d`) | $0.99 |
| `get_whale_activity` | Large settlements and movers over a window, aggregate only: by facilitator, category, and size band, plus per-category mover counts. Size and where, never who. | `min_usd`, `window` (days, 1–90) | $0.99 |
| `get_token_metrics` | The first-party chart series behind /charts plus the Agent Commerce Index (ACI), queryable by metric and date range. Third-party token spot price is intentionally excluded. | `metric`, `days`, `category`, `from`, `to` | $0.01 |
## Recommended payment-routing flow
1. `get_market_summary` to orient on the current market.
2. `get_best_value_provider?category=<id>` to rank providers.
3. `get_liveness?domain=<top provider>` to confirm the chosen provider is up.
4. Pay. If the call fails, re-run step 2 — the next result returns a fresh ranking.
## Category ids
`llm`, `data`, `search`, `infra`, `content`, `markets`, `payments`, `comms`. Hyphenated forms and common aliases are normalized onto these ids — e.g. `inference`→`llm`, `scraping`/`social`/`translation`→`data`, `image`→`content`, `defi`/`trading`/`signals`→`markets`.
## Notes and limits
- Liveness coverage: TrustBench probes ~1,200 services. A 404 "Domain not tracked" is a coverage gap, not an error.
- `get_changes` lookback is capped at 90 days; older slim snapshots still return category-level diffs but flag per-service diffs unavailable.
- `get_report_data`: Builder tier returns the current published month only; Pro Agent returns the full archive. Unpublished months return 200 with `status: "unpublished"`.
- Full contract: https://paddock.finance/api/mcp/openapi.json
- Full docs: https://paddock.finance/docs.md · Index: https://paddock.finance/llms.txt