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.
Quickstart
Once you have a Paddock API key, here's how to confirm it works in 30 seconds. (Don't have one yet? Subscribe at /api — 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
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.
https://paddock.finance/api/mcp/mcp
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 API Reference 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.
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 (and the free pair stay available) — require either an API key in X-Paddock-Key or an x402 micropayment.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 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 API
Trading agents, content agents, and research agents that need real-time category data, niche detection, and cross-protocol intelligence to make payment decisions.
Indie devs and small teams building tools that ride on Paddock data — wallet labeling, category routing, agent leaderboards.
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.
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.
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.
Rank every category by concentration and opportunity score to see what's saturated and what's wide open, before you commit to building.
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.
Clean JSON of volume, category breakdowns, and provider counts for VC memos, fund diligence, and journalism. No scraping.
Drop daily-granular numbers straight into a dashboard, newsletter, or dev tool, and keep them current with the change feed.
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.
Pull the State of Agent Commerce report as structured JSON: the Agent Commerce Index, category analysis, and protocol landscape, ready for dashboards and workflows.
Endpoints
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.
| Name | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
curl https://paddock.finance/api/mcp/summary
{
"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"
}Returns all services in a category with transaction counts, pricing, and reliability scores.
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | yes | 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"
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
curl -H "X-Paddock-Key: YOUR_KEY" \ https://paddock.finance/api/mcp/gaps
{
"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"
}{
"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)" }
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| category | string | yes | 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"
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| domain | string | yes | 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"
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| since | string | yes | 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"
{
"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"
}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".
| Name | Type | Required | Description |
|---|---|---|---|
| month | string | no | 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
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| window | string | no | 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"
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| min_usd | number | no | Large-settlement threshold in USD (default 1000). |
| window | integer | no | 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"
{
"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"
}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).
| Name | Type | Required | Description |
|---|---|---|---|
| metric | string | yes | Which series to return: spend_share_over_time, daily_transactions, category_concentration, new_services, liveness_score, or aci. |
| days | integer | no | Lookback window in days, 1–730 (default 90). Ignored by the aci metric, which uses from/to. |
| category | string | no | Category id for the category_concentration metric (e.g. llm). |
| from | string | no | Start month YYYY-MM (aci metric only). |
| to | string | no | 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"
{
"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"
}See the OpenAPI schema for the full contract on every endpoint.
Code examples
Three minimal clients that call get_market_summary and print the top three categories. Substitute your own key.
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]'
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")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 |
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"
}Stuck? We'll help.
DM @PaddockFinance on X for help. We respond within 24 hours.
Message us on X →Ready to integrate Paddock?
Builder tier includes 10,000 queries/day and access to all ten MCP tools.