Rate Limits

Rate limiting details and best practices.

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

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)
Standard V3 REST data	Not available	1,000 req/min (~16 QPS)	2,000 req/min (~33 QPS)	4,000 req/min default; custom by agreement
Heavy V3 trade-history endpoints	Not available	1,000 req/min	1,500 req/min	1,500 req/min default; custom by agreement
Event WebSocket connections	1	10	50	Unlimited
Orderbook WebSocket connections	1	10	50	Unlimited
Filter items per subscription	10,000	10,000	10,000	Custom
Orderbook market subs	Unlimited	Unlimited	Unlimited	Unlimited
WebSocket session	1 hour/day	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.

V3 REST data endpoints require a paid plan. Heavy trade-history endpoints have a separate per-key bucket in addition to your standard V3 REST data limit. See V3 REST data limits below.

How it works

• Rate limits are tracked per API key using a sliding window.
• V3 REST data endpoints require a paid API key. Free-tier keys receive 402 Payment Required.
• Heavy V3 trade-history endpoints check both your standard V3 REST data limit and the heavy endpoint bucket. The stricter remaining limit applies.
• 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.
• Successful REST responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers.

Best practices

Use WebSocket for real-time data

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

// Instead of polling /v3/trades 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("/v3/markets/search?q=bitcoin&limit=100", { headers })
  .then((r) => r.json());

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

// Use cache for lookups, refresh every 5 minutes

Batch where possible

Use POST /v3/wallets/batch instead of many individual wallet summary requests when you need P&L for multiple wallets.

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.

V3 REST data limits

Standard V3 REST reads count against your plan’s V3 REST data limit.

Plan	Standard V3 REST data	Heavy V3 trade-history endpoints
Free	Not available	Not available
Starter	1,000 req/min	1,000 req/min
Growth	2,000 req/min	1,500 req/min
Enterprise	4,000 req/min default; custom by agreement	1,500 req/min default; custom by agreement

Heavy V3 trade endpoints have a separate per-key bucket because trade-history scans are the highest-throughput REST surface:

• /v3/trades
• /v3/wallets/{address}/trades
• /v3/wallets/{address}/combos/trades
• /v3/markets/{token_id}/trades
• /v3/markets/slug/{slug}/trades
• /v3/builders/{code}/trades

When the heavy bucket is exceeded, you’ll receive a 429 response with:

{
  "error": "rate limit exceeded",
  "scope": "v3_heavy",
  "reset_at": 1774108000
}

For real-time trades, use the WebSocket stream instead of polling trade-history endpoints.

Pagination limits

Most V3 list endpoints default to limit=100 and clamp limit to a maximum of 300 rows per page. If you request more than the page cap, PolyNode normalizes limit to the maximum allowed value. Responses include the actual limit, offset, rows_returned, and has_more values.

/v3/markets/condition/{condition_id}/positions supports tiered page sizes for holder lists: Starter keys can request up to 300 rows, Growth keys up to 1000, and Enterprise keys up to 2000.

/v3/wallets/{address}/pnl/events is the exception: it defaults to limit=5000 and clamps to a maximum of 10000 buckets.

For deep trade-history walks, prefer after and before time windows instead of very large offsets.

Higher limits

Upgrade your plan at polynode.dev/pricing for higher rate limits and more WebSocket connections. Contact [e-mail] for Enterprise capacity above the default V3 REST limits.