Merlin API

Free Tier

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

The Merlin API provides free access to Polymarket analytics data. Query the leaderboard for top 50 traders by P&L or volume, fetch individual trader profiles with stats and positions, get trending markets, resolution risk scores, and aggregated statistics. Rate limit: 60 requests/min per IP.

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://merlin.trade/api/leaderboard?timePeriod=ALL&orderBy=PNL&limit=10"

JavaScript

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

Python

import requests

res = requests.get(
    "https://merlin.trade/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

Frequently Asked Questions — API

Is the Merlin API free?

Yes. The Merlin API is currently free with a rate limit of 60 requests per minute per IP address. All endpoints return JSON with cache headers for efficient caching.

What data does the Merlin API provide?

The API provides access to Polymarket leaderboard data, individual trader profiles and stats, trending markets, losing traders, resolution risk analysis, market heatmap data, and aggregated statistics.

Do I need an API key?

No API key is currently required. Authentication and paid tiers with higher rate limits are coming soon.