Merlin API

Free Tier

Free access to Polymarket analytics. Leaderboard data, trader profiles, market trends, risk analysis, and more.

Rate Limits

60 requests/min per IP address (advisory — enforcement coming soon). All endpoints return JSON with Cache-Control headers for efficient caching.

Endpoints

GET /api/leaderboard

Top Polymarket traders ranked by PNL or volume.

Param	Default	Values
category	OVERALL	OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, ECONOMICS, TECH, FINANCE
timePeriod	DAY	DAY, WEEK, MONTH, ALL
orderBy	PNL	PNL, VOL
limit	25	1-50

Example response

[
  {
    "rank": "1",
    "proxyWallet": "0x...",
    "userName": "trader1",
    "vol": 1250000,
    "pnl": 85000,
    "profileImage": "https://...",
    "xUsername": "trader1x",
    "verifiedBadge": true
  }
]

GET /api/trader/{wallet}

Full trader profile with stats across all periods, open positions, and recent activity.

Param	Description
wallet	Ethereum address (0x...)

Example response

{
  "profile": {"userName": "...", "vol": 500000, "pnl": 25000},
  "stats": [{"period": "DAY", "entry": {...}}],
  "positions": [{"title": "...", "outcome": "Yes", "currentValue": 150}],
  "activity": [{"title": "...", "side": "BUY", "size": 100}]
}

GET /api/markets

Trending Polymarket events sorted by volume.

Param	Default	Values
period	all	1d, 7d, 30d, all

GET /api/losers

Bottom traders ranked by losses.

Param	Default	Values
category	OVERALL	Same as leaderboard
timePeriod	DAY	DAY, WEEK, MONTH, ALL

GET /api/resolution-risk

Markets with high resolution dispute risk. No parameters required.

GET /api/statistics

Aggregated Polymarket statistics — total volume, trader counts, top performers. No parameters required.

GET /api/heatmap

Market heatmap blocks with volume, heat score, and outcome data.

Param	Default	Values
period	1d	1d, 7d, 30d, all

Example response

[
  {
    "id": "...",
    "title": "Will Bitcoin hit $100K?",
    "slug": "bitcoin-100k",
    "volume": 5000000,
    "periodVolume": 250000,
    "heat": 1.0,
    "decisiveness": 0.6,
    "dominantOutcome": "Yes",
    "dominantPrice": 0.8,
    "outcomes": [
      {"label": "Yes", "price": 0.8},
      {"label": "No", "price": 0.2}
    ]
  }
]

Code Examples

cURL

curl "https://merlinagent.ai/api/leaderboard?timePeriod=ALL&orderBy=PNL&limit=10"

JavaScript

const res = await fetch(
  "https://merlinagent.ai/api/leaderboard?timePeriod=ALL&orderBy=PNL&limit=10"
);
const traders = await res.json();
console.log(traders);

Python

import requests

res = requests.get(
    "https://merlinagent.ai/api/leaderboard",
    params={"timePeriod": "ALL", "orderBy": "PNL", "limit": 10}
)
traders = res.json()
print(traders)

Coming Soon

API keys & authentication
Webhooks for trader activity
Paid tiers with higher rate limits
WebSocket feed for real-time data