Documentation

Paddock API & MCP — Documentation

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

Already have a Paddock API key? Skip to Authentication. Just evaluating? Browse the endpoints below to see what's possible.

— 30-second test

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

bash

copy

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.

— MCP

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.

01

Open Connectors settings

In Claude, go to Settings → Connectors.

02

Add a custom connector

Click “Add custom connector.”

03

Paste the Paddock URL

Use the connector URL below, then save.

04

Ask Paddock anything

Claude can now call the free Paddock tools. Try one of the questions below.

Connector URL

url

copy

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 — niche gap analysis and report data — are available via the REST API with your key; see the API Reference below. Paid tools in Claude are coming soon.

— Auth

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.

header

copy

X-Paddock-Key: pk_builder_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

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

Free vs paid: get_market_summary and get_category_detail work without a key. get_niche_gaps and get_report_data require either an API key or an x402 micropayment.

— Why this data

Why Paddock — and why now.

The AI agent economy is on-chain and observable now. Every transaction, every wallet, every category — all of it is open, and we're capturing it nightly. Paddock is 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.

— Audiences

Who uses Paddock API

01 · For agents in production

Live data inside the agent loop.

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

02 · For builders shipping with agents

The data layer for agent tooling.

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

03 · For analysts and researchers

Cite-worthy commerce metrics.

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

— Reference

Endpoints

get_market_summaryFree

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

Name	Type	Required	Description
No parameters.

Example request

Free tier — no API key required.

curl

copy

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

Example response

json

copy

{
  "tool": "get_market_summary",
  "tier": "free",
  "date": "2026-05-19",
  "summary": {
    "daily_transactions": 24180,
    "daily_volume_usdc": "$8,412",
    "unique_buyer_agents": 1247,
    "live_service_providers": 38,
    "registered_payment_endpoints": 812,
    "mpp_services": 64,
    "mcp_registry_servers": 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%" }
  ],
  "insight": "LLM inference leads agent spending with 9,842 daily transactions across 6 providers.",
  "pro_features": "For niche gap analysis and report data, subscribe at https://paddock.finance/api-access",
  "subscription_url": "https://paddock.finance/api-access",
  "paddock_url": "https://paddock.finance/market"
}

get_category_detailFree

GET/api/mcp/category

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

Parameters

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.

Example request

Free tier — no API key required.

curl

copy

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

Example response

json

copy

{
  "tool": "get_category_detail",
  "tier": "free",
  "date": "2026-05-19",
  "category": "Search",
  "category_id": "search",
  "summary": {
    "total_daily_transactions": 3402,
    "provider_count": 2,
    "market_status": "Open niche — fewer than 3 providers with real volume"
  },
  "services": [
    {
      "service": "Exa Search",
      "domain": "api.exa.ai",
      "daily_transactions": 2104,
      "daily_volume_usdc": "$73.64",
      "unique_buyers": 188,
      "reliability": { "uptime": "99%", "latency_ms": 412, "score": 94 }
    }
  ],
  "subscription_url": "https://paddock.finance/api-access"
}

get_niche_gapsPaid · API key or x402

GET/api/mcp/gaps

Returns categories with real agent spend (>500 daily transactions) and fewer than 3 service providers — open niches where a new entrant could capture market share. Requires a Paddock API key in X-Paddock-Key, or an x402 per-query payment ($0.01 USDC).

Parameters

Name	Type	Required	Description
No parameters.

Example request

Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.

curl

copy

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

Example response

json

copy

{
  "tool": "get_niche_gaps",
  "date": "2026-05-19",
  "paid_via": "api_key",
  "tier": "builder",
  "subscriber": "you@yourservice.com",
  "open_niches": [
    {
      "category": "Search",
      "category_id": "search",
      "daily_transactions": 3402,
      "providers": 2,
      "opportunity_score": 224,
      "signal": "Two providers — room for a differentiated entrant",
      "paddock_url": "https://paddock.finance/market"
    }
  ],
  "approaching_threshold": [
    {
      "category": "Translation",
      "category_id": "translation",
      "daily_transactions": 312,
      "providers": 1,
      "status": "approaching_threshold",
      "note": "312 daily txns — approaching the 500 threshold. Early position opportunity."
    }
  ],
  "summary": "1 open niche found. Search has the highest opportunity score.",
  "methodology": "Categories with ≥500 daily agent transactions and fewer than 3 active providers.",
  "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

copy

{
  "tool": "get_niche_gaps",
  "status": "pro_required",
  "message": "Niche gap 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": "100,000/day + webhooks", "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_report_dataPaid · API key or x402

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, or an x402 per-query payment ($0.99 USDC). First issue publishes June 30, 2026.

Parameters

Name	Type	Required	Description
month	string	no	Report month as YYYY-MM (e.g. 2026-06). Defaults to the latest published issue.

Example request

Requires Paddock API key (Builder $99/mo) or x402 payment. The example below assumes a valid key.

curl

copy

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

Example response

json

copy

{
  "tool": "get_report_data",
  "month": "2026-06",
  "title": "The State of Agent Commerce — June 2026",
  "published_at": "2026-06-30T12:00:00Z",
  "table_of_contents": [
    "Agent Commerce Index",
    "Category analysis",
    "Endpoint liveness",
    "Protocol landscape",
    "Dark discovery"
  ],
  "paid_via": "api_key",
  "tier": "pro_agent",
  "data": {
    "agent_commerce_index": 61,
    "categories_tracked": 19,
    "open_niches": 4
  },
  "paddock_url": "https://paddock.finance/report/2026-06"
}

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

— SDKs

Code examples

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

curl

bash

copy

export PADDOCK_API_KEY=pk_builder_YOUR_KEY

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

Python

python

copy

import os, requests

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

JavaScript

javascript

copy

const PADDOCK_KEY = process.env.PADDOCK_API_KEY;

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

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

— Limits

Rate limits

Quotas are per API key and reset daily at 00:00 UTC. Free Dev quotas are per IP. Need more? Email enterprise via the support link below.

Tier	Daily quota	Burst	Webhooks
Free Dev	100 queries/day	10/min	no
Builder	10,000 queries/day	60/min	no
Pro Agent	100,000 queries/day	600/min	yes

Example 429 response

http

copy

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747958400

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

— Support

Stuck? We'll help.

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

Message us on X →

— Get started

Ready to integrate Paddock?

Subscribe — Builder $99/mo →Talk to us first →

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

— Keep going

What to read next.

— x402 market

What agents pay for.

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

See the market →

— For the trader

Track agent tokens.

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

See the leaderboard →