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 /mcp.
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 } }| 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 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. |
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, Tech & Science), 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://polynyx.com/api/v1/markets?category=Esports&subcategory=League%20of%20Legends&limit=20" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/markets/will-bitcoin-hit-150k-in-2026?history=1&period=1m" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/markets/will-bitcoin-hit-150k-in-2026/smart-money?scope=all&trades=20" -H "Authorization: Bearer pnx_YOUR_KEY"GET /api/v1/markets/{market}/book
The live Polymarket CLOB order book for each outcome of a market: bids (best/highest first) and asks (best/lowest first) as price/size levels, capped to `depth` per side.
| Parameter | Type | Description |
|---|---|---|
| market*path | string | Polymarket slug or 0x conditionId. |
| depth | integer | Levels per side (default 10, max 50). |
curl "https://polynyx.com/api/v1/markets/will-bitcoin-hit-150k-in-2026/book?depth=10" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/traders?category=Politics&sort=pnlMonth&limit=25" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/traders/search?q=theo" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/traders/0x…40hex?include=positions,trades&limit=25" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/signals?history=1" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/conviction?category=Sports&clustersOnly=1&limit=20" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/activity?minUsd=5000&limit=50" -H "Authorization: Bearer pnx_YOUR_KEY"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://polynyx.com/api/v1/categories" -H "Authorization: Bearer pnx_YOUR_KEY"