How do I authenticate to the API?

Send your key in an Authorization: Bearer pnx_… header (X-API-Key is also accepted). Keys are created in the developer dashboard and shown once. Never put the key in a query string.

What do the X-RateLimit and X-Quota headers mean?

X-RateLimit-Limit / -Remaining are this key's per-minute budget; X-Quota-Limit / -Remaining are the account's requests for the calendar month (UTC), with X-Quota-Reset the unix time it resets. A 429 carries a Retry-After in seconds.

How do I identify a market or a trader?

Markets take the Polymarket slug (the last part of a polymarket.com URL) or the 0x conditionId; traders take the 0x wallet address or a known handle. Event slugs that group several markets return 404 with is_event — query each market's own slug.

What units does the API use?

Probabilities are 0..1, money is USD, shares are outcome tokens, timestamps are unix seconds unless a field is named *Iso. Realized P&L is net of what the wallet paid; bots are flagged, not hidden, unless you pass hideBots.

How fresh is the data?

Markets and odds refresh every few seconds; smart-money and holder data within about two minutes for hot markets; the leaderboard continuously; trader deep-dives on open (a profile that has not been viewed recently may take a few seconds on the first call).

Polymarket API reference

Base URL https://polynyx.com/api/v1. JSON in, JSON out, CORS enabled. The same capabilities are exposed as tools on the MCP server at https://polynyx.com/mcp. Powered by Polynyx Analytics.

Authentication

Create a key in the developer dashboard and send it as a bearer token. Keys look like pnx_…, are shown once, and can be revoked at any time.

curl "https://polynyx.com/api/v1/me" -H "Authorization: Bearer pnx_YOUR_KEY"

# → { "plan": "hobby", "limits": { "perMinute": 120, "monthlyCalls": 50000, ... }, "usage": { "monthCalls": 1234, "resetsAt": 1764547200 } }

Limits & headers

Plan	Per minute / key	Per month / account	Keys	Max page
Hobby	120	50k	3	200
Developer	600	500k	10	500
Scale	2000	5M	50	500

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. Both the REST API and MCP tool calls count against the same budget: one call, one request.

Errors

Errors are JSON: { "error": { "code", "message", "docs" } }.

401	missing_api_key / invalid_api_key	No key, an unknown or revoked key, or a lapsed plan.
402	no_active_plan	Key exists but the account has no active API plan.
404	market_not_found / trader_not_found / is_event	Unknown id, or an event slug that groups several markets.
429	rate_limited / quota_exceeded	Per-minute or monthly limit hit — see Retry-After.
502	upstream_error	A data source did not answer in time. Retry shortly.

List live markets

MCP tool · list_markets

GET /api/v1/markets

Live Polymarket markets with current odds, 24h volume and liquidity, hottest first. Filter by category (Sports, Esports, Politics, Crypto, Economics, Pop Culture), subcategory (e.g. NFL, League of Legends, Bitcoin) or a title search.

Parameter	Type	Description
category	string	Category name, e.g. Sports. Default: all.
subcategory	string	Subcategory name, e.g. NFL or League of Legends.
q	string	Case-insensitive title search.
upcoming	boolean	Include upcoming markets with no 24h volume yet.
limit	integer	Rows to return (default 50).

curl "https://www.polydune.com/api/v1/markets?category=Esports&subcategory=League%20of%20Legends&limit=20" -H "Authorization: Bearer pnx_YOUR_KEY"

Get a market

MCP tool · get_market

GET /api/v1/markets/{market}

One Polymarket market by slug or conditionId: outcomes with live probabilities, volume, liquidity, timing and resolution status. Optionally the odds history (period 1h|6h|1d|1w|1m|max) and the order books.

Parameter	Type	Description
market*path	string	Polymarket slug (e.g. will-bitcoin-hit-150k-in-2026) or 0x conditionId.
history	boolean	Include odds-over-time series.
period	1h \| 6h \| 1d \| 1w \| 1m \| max	History window (default 1w).
orderbook	boolean	Include the live order books.

curl "https://www.polydune.com/api/v1/markets/will-bitcoin-hit-150k-in-2026?history=1&period=1m" -H "Authorization: Bearer pnx_YOUR_KEY"

Smart money on a market

MCP tool · get_smart_money

GET /api/v1/markets/{market}/smart-money

Who the smart money is on a market and which side they hold: per-outcome smart-wallet positions (ranked, Sharp and Whale wallets, bots excluded) with wallet identities, shares, entry prices and track records; the aggregate 'follow' line (favoured side, average entry); top holders; and, once resolved, the realized winners and losers.

Parameter	Type	Description
market*path	string	Polymarket slug or 0x conditionId.
scope	strict \| all	strict = wallets smart in this market's own subcategory (default); all = any ranked/Sharp/Whale wallet.
holders	integer	Top holders per outcome to include (default 10, 0 to omit).
trades	integer	Recent trades to include (default 0).

curl "https://www.polydune.com/api/v1/markets/will-bitcoin-hit-150k-in-2026/smart-money?scope=all&trades=20" -H "Authorization: Bearer pnx_YOUR_KEY"

Trader leaderboard

MCP tool · list_traders

GET /api/v1/traders

The Polynyx leaderboard: 200k+ Polymarket wallets ranked by realized P&L (or volume, ROI, 24h/7d/30d P&L), with win rate, bot flag and dominant category. Filter by category/subcategory, hide bots, or search a handle/address prefix.

Parameter	Type	Description
sort	pnl \| volume \| roi \| pnlDay \| pnlWeek \| pnlMonth	Default pnl.
dir	desc \| asc
category	string
subcategory	string	One or more, comma-separated.
hideBots	boolean	Exclude arbitrage / market-maker bots (default true).
q	string	Handle substring or address prefix.
limit	integer
offset	integer

curl "https://www.polydune.com/api/v1/traders?category=Politics&sort=pnlMonth&limit=25" -H "Authorization: Bearer pnx_YOUR_KEY"

Search traders

MCP tool · search_traders

GET /api/v1/traders/search

Find Polymarket wallets by handle or address prefix (up to 20 results with P&L and volume).

Parameter	Type	Description
q*	string
limit	integer

curl "https://www.polydune.com/api/v1/traders/search?q=theo" -H "Authorization: Bearer pnx_YOUR_KEY"

Trader deep-dive

MCP tool · get_trader

GET /api/v1/traders/{trader}

A wallet's full track record: profile, all-time metrics (P&L, volume, win rate, markets traded), per-category stats, leaderboard ranks and badges. Add include=positions,trades,series,markets for open positions, recent trades, the P&L curve and best/worst markets.

Parameter	Type	Description
trader*path	string	0x wallet address or a known Polymarket handle.
include	string	Comma-separated: positions, trades, series, markets.
limit	integer	Max trades / positions to include (default 50).

curl "https://www.polydune.com/api/v1/traders/0x…40hex?include=positions,trades&limit=25" -H "Authorization: Bearer pnx_YOUR_KEY"

Live model signals

MCP tool · get_signals

GET /api/v1/signals

Polynyx's signal families (sharp-agreement, conviction clusters, parlays and more) with their live picks, each family's paper track record (win rate, Brier, P&L) and health. Use it to see what the model would bet right now.

Parameter	Type	Description
family	string	Only this family key.
history	boolean	Include each family's recent settled picks.

curl "https://www.polydune.com/api/v1/signals?history=1" -H "Authorization: Bearer pnx_YOUR_KEY"

Smart-money conviction

MCP tool · get_conviction

GET /api/v1/conviction

Accumulated smart-money positioning on live and upcoming markets: per market-outcome, how many smart wallets agree, net $ flow, their average entry, the share of smart flow vs the crowd price (divergence) and the actors behind it. Highest conviction first.

Parameter	Type	Description
category	string
subcategory	string
clustersOnly	boolean	Only outcomes with 2+ agreeing wallets (default false: lone accumulators included).
limit	integer

curl "https://www.polydune.com/api/v1/conviction?category=Sports&clustersOnly=1&limit=20" -H "Authorization: Bearer pnx_YOUR_KEY"

Live smart-money tape

MCP tool · get_activity

GET /api/v1/activity

The latest taker trades across all Polymarket markets, enriched with each trader's leaderboard rank, badge (Sharp / Whale / bot) and the market's category. Filter by category, subcategory and minimum trade size.

Parameter	Type	Description
category	string	One or more, comma-separated.
subcategory	string	One or more, comma-separated.
exclude	string	Categories to hide, comma-separated.
minUsd	number	Minimum trade size in USD.
limit	integer

curl "https://www.polydune.com/api/v1/activity?minUsd=5000&limit=50" -H "Authorization: Bearer pnx_YOUR_KEY"

Categories & subcategories

MCP tool · list_categories

GET /api/v1/categories

The category taxonomy used by every other tool (Sports → NFL, NBA…; Esports → League of Legends…), with the leaderboard URL of each.

curl "https://www.polydune.com/api/v1/categories" -H "Authorization: Bearer pnx_YOUR_KEY"

API FAQ

How do I authenticate to the API?: Send your key in an Authorization: Bearer pnx_… header (X-API-Key is also accepted). Keys are created in the developer dashboard and shown once. Never put the key in a query string.
What do the X-RateLimit and X-Quota headers mean?: X-RateLimit-Limit / -Remaining are this key's per-minute budget; X-Quota-Limit / -Remaining are the account's requests for the calendar month (UTC), with X-Quota-Reset the unix time it resets. A 429 carries a Retry-After in seconds.
How do I identify a market or a trader?: Markets take the Polymarket slug (the last part of a polymarket.com URL) or the 0x conditionId; traders take the 0x wallet address or a known handle. Event slugs that group several markets return 404 with is_event — query each market's own slug.
What units does the API use?: Probabilities are 0..1, money is USD, shares are outcome tokens, timestamps are unix seconds unless a field is named *Iso. Realized P&L is net of what the wallet paid; bots are flagged, not hidden, unless you pass hideBots.
How fresh is the data?: Markets and odds refresh every few seconds; smart-money and holder data within about two minutes for hot markets; the leaderboard continuously; trader deep-dives on open (a profile that has not been viewed recently may take a few seconds on the first call).