Rate Limits

Rate limiting details and best practices.

PolyNode uses per-key rate limiting to ensure fair usage. Limits scale with your plan.

Tier limits

Firehose = a WebSocket subscription with no filters applied. It receives every event (all settlements, trades, blocks, etc.) at full throughput. Filtered subscriptions — where you specify wallets, tokens, slugs, or size thresholds — use far less bandwidth and don’t count toward your firehose limit.

	Free	Starter ($50/mo)	Growth ($200/mo)	Enterprise ($750/mo)
Rate limit	120 req/min (2 QPS)	6,000 req/min (100 QPS)	18,000 req/min (300 QPS)	60,000 req/min (1,000 QPS)
Enriched endpoints	1 req/sec	30 req/sec	50 req/sec	100 req/sec
WebSocket connections	1	500	3,000	Unlimited
Firehose connections	1	100	750	Unlimited
Orderbook connections	1	2	10	Unlimited
Orderbook market subs	Unlimited	Unlimited	Unlimited	Unlimited
API keys	1	3	10	25
Snapshot size (snapshot_count)	20	100	200	500
Snapshot lookback (since)	30 seconds	2 minutes	5 minutes	5 minutes
Key generation	1 per IP per day	Via dashboard	Via dashboard	Via dashboard
Support	Community	Email	Priority	Dedicated + Slack

Snapshot size vs snapshot lookback — these are two separate snapshot modes controlled by different parameters. snapshot_count returns the last N events (capped by your tier). since returns all events after a UNIX-ms timestamp within your tier’s lookback window. If you pass both, since takes priority and snapshot_count is ignored. See subscribing for details.

Enterprise includes dedicated server infrastructure. Contact [e-mail] before activation.

Enriched endpoints (/v1/trader/*, /v1/leaderboard, /v1/trending, etc.) and data endpoints (/v1/wallets/*/positions, /v1/wallets/*/trades) have separate rate limits from your plan’s main limit. See Enriched endpoints and Data endpoint limits below for details.

How it works

• Rate limits are tracked per API key using a sliding window.
• When you exceed the limit, you’ll receive a 429 Too Many Requests response.
• The error message includes a Unix timestamp for when you can retry.

Best practices

Use WebSocket for real-time data

Instead of polling REST endpoints, connect via WebSocket for live updates:

// Instead of polling /v1/markets every 5 seconds (12 req/min)...
// Use WebSocket (1 connection, unlimited events)
const ws = new WebSocket("wss://ws.polynode.dev/ws?key=pn_live_YOUR_KEY");
ws.send(JSON.stringify({
  action: "subscribe",
  type: "settlements",
}));

Cache metadata locally

Market metadata (question, slug, outcomes) changes infrequently. Cache it and only refresh periodically:

// Fetch full market list once
const markets = await fetch("/v1/markets?count=1000", { headers })
  .then((r) => r.json());

// Cache by token_id
const cache = new Map(markets.markets.map((m) => [m.token_id, m]));

// Use cache for lookups, refresh every 5 minutes

Batch where possible

Use /v1/markets?count=1000 instead of individual /v1/markets/:id calls to reduce requests.

Use filtered subscriptions

WebSocket subscriptions with filters reduce message volume and processing overhead:

{
  "action": "subscribe",
  "type": "settlements",
  "filters": {
    "tokens": ["specific-token-id"],
    "min_size": 100
  }
}

Expected WebSocket throughput

WebSocket subscriptions are not rate-limited by requests/min, but message volume varies significantly by subscription type:

Subscription	Typical messages/sec	Notes
Firehose (no filters)	50–150	~0.5–1.5 Mbps uncompressed
Filtered (1 market)	1–20	Depends on market activity
Filtered (1 wallet)	0–5	Most wallets trade infrequently
Blocks only	~0.5	One per Polygon block (~2s)

status_update events arrive in bursts (30–80 per block). If you don’t need confirmation tracking, exclude them from your event_types filter to reduce volume.

Data endpoint limits

The wallet and market data endpoints proxy to upstream sources and have their own rate limits, separate from your per-key limit.

Standard data endpoints

These endpoints share your plan’s normal rate limit and a global throughput cap of 20 upstream calls per second across all data endpoints. This ensures stable upstream performance for all users.

• /v1/wallets/{addr}/positions
• /v1/wallets/{addr}/trades
• /v1/wallets/positions (multi-wallet)
• /v1/markets/{id}/positions
• /v1/markets/{id}/trades

Batch requests (multiple wallets) count each wallet as one request toward your limit. For example, a 5-wallet batch counts as 5 requests.

Onchain enrichment: The wallet positions endpoints check onchain redemption state for resolved positions. This adds a single batched RPC call (~130ms) per request when redeemable positions are present. No extra rate limit cost — it’s included in the same request.

Enriched endpoints

The enriched analytics endpoints have their own per-key rate limit that scales with your tier:

Tier	Limit
Free	1 req/sec
Starter	30 req/sec
Growth	50 req/sec
Enterprise	100 req/sec

Enriched endpoints:

• /v1/trader/{wallet} — trader profile with EOA resolution
• /v1/trader/{wallet}/pnl — PnL time series
• /v1/leaderboard — top traders
• /v1/trending — trending markets
• /v1/activity — platform trade feed
• /v1/event/{slug} — event details
• /v1/movers — biggest price movers

Responses are cached for a short window to ensure fast lookups. The trader profile endpoint resolves the underlying EOA wallet address onchain when available.

Heavy endpoints RATE LIMITED

Some data endpoints fan out many upstream requests per call and have a stricter per-key limit:

Endpoint	Limit	Why
/v1/markets/{id}/positions?includeTrades=true	60 req/min per key	Each call fetches trade history for every position holder in the market (can be 50-100+ upstream calls)

When this limit is exceeded, you’ll receive a 429 response with:

{
  "error": "includeTrades rate limit exceeded (60/min). Retry after 1774108000."
}

If you only need position sizes and P&L, omit includeTrades to use the standard rate limit. Only add includeTrades=true when you specifically need firstTradeAt and lastTradeAt timestamps.

For real-time data, use the WebSocket stream instead of polling these endpoints.

Higher limits

Upgrade your plan at polynode.dev/pricing for higher rate limits and more WebSocket connections.