Rate Limits

V3 REST limits are shared across all API keys owned by the same account. Limits scale with your plan and with the endpoint class.

Two independent controls: the per-minute, per-second, connection, and Free-session limits on this page remain in force. Polynode now also shows monthly API-request and WebSocket-transfer usage in the usage dashboard, but monthly usage enforcement is not active yet.

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 josh@quantish.live before activation.

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

How it works

V3 REST limits are tracked per account using a sliding window. You can use multiple keys at the same time, but every request draws from the same account allowance.
V3 REST data endpoints require a paid API key. Free-tier keys receive 402 Payment Required.
Heavy V3 trade-history endpoints check both your account’s standard V3 REST data limit and its 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.

Monthly usage allowances

Monthly usage is account-level and separate from the instantaneous limits above. Every active API key owned by the same account contributes to the same totals. Creating another key, reconnecting a WebSocket, or rotating a key does not create another allowance or reset usage. The usage dashboard shows three meters:

Meter	What it counts
API requests	Completed authenticated requests on metered API routes. Requests rejected by authentication, existing rate limits, or a Polynode 5xx are not billable usage.
Order Book + Chainlink	Successfully delivered Order Book and Chainlink WebSocket payload bytes.
On-chain events	Successfully delivered settlements, status updates, trades, redemptions, oracle events, and other classified on-chain WebSocket payload bytes.

Plan	API requests	Order Book + Chainlink	On-chain events
Free	100,000	5 GB	5 GB
Starter	10 million	250 GB	250 GB
Growth	50 million	1 TB	1 TB
Enterprise / Institutional	Unlimited	Unlimited	Unlimited

Plan allowances reset at the beginning of the account’s next service period. The dashboard shows the exact start and end dates. Transfer uses decimal units: 1 GB = 1,000,000,000 bytes and 1 TB = 1,000 GB. Enterprise/Institutional usage is still measured and visible in the dashboard, but it has no monthly API-request or WebSocket-transfer ceiling. The instantaneous request and connection limits in the tier table remain separate.

Monthly usage enforcement is not active yet. The dashboard and package purchases are live so you can observe real usage and prepare before monthly limits are enabled. Existing per-minute, per-second, connection, and Free-session limits still apply.

What transferred means

WebSocket transfer is the encoded application payload successfully submitted to your connection. Text messages count their UTF-8 payload length, while compressed binary messages count the smaller compressed payload length. The same payload delivered to two connections counts twice. Failed sends, acknowledgements, heartbeats, ping/pong frames, warnings, quota notices, close frames, WebSocket framing, TLS, TCP, IP, and retransmission overhead do not count. This is data transfer, not storage or a bandwidth-speed measurement. The dashboard may show API response transfer for transparency. It is informational and does not consume a version-one package or allowance.

How capacity is consumed

For each meter, Polynode consumes the allowance included with your plan first, then active purchased packages, then active courtesy capacity. Packages and courtesy grants with the earliest expiration are used first. Included capacity and added packages remain visually separate in the dashboard.

Usage packages

Signed-in Free and paid accounts can use a package to add capacity to one meter without changing the subscription plan:

Package	Added capacity	One-time price
API requests	10 million requests	$20
Order Book + Chainlink	100 GB	$20
On-chain events	100 GB	$20

A package adds only monthly capacity for its selected meter. It does not unlock paid-only endpoints or change per-minute, connection, or Free-session limits.

Select from 1 to 100 of one package in a Checkout. For example, 10 API-request packages add 100 million requests for a one-time $200 payment. Packages are resource-specific and do not raise the request-per-minute or connection limits in the tier table. Capacity is added only after Stripe confirms a successful payment. Reopening, refreshing, or replaying the same Checkout cannot add a package twice. Each package remains active for 90 days, does not reset with the monthly service period, and expires after 90 days if unused. The dashboard shows remaining capacity and expiration. A refund or payment dispute removes the unused portion of its package. Usage already delivered is not erased. If more capacity has been consumed than can be reversed safely, Polynode preserves the usage history for review instead of abruptly disconnecting a customer. The usage calculator assumes connections remain open 24 hours per day and can recommend package quantities. Its estimate is directional because activity, filters, reconnects, message shape, and compression affect actual transfer. It never purchases automatically; the dashboard remains the source of truth.

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 shared account 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. No V3 endpoint returns more than 1000 rows or buckets in one page. Cursors and offsets select where the next page starts; they do not increase its size. /v3/markets/condition/{condition_id}/positions supports tiered page sizes for holder lists: Starter keys can request up to 300 rows, while Growth and Enterprise keys can request up to 1000. /v3/wallets/{address}/pnl/events defaults to and clamps at limit=1000 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 josh@quantish.live for Enterprise capacity above the default V3 REST limits.

Getting Started

Guides

Tier limits

How it works

Monthly usage allowances

What transferred means

How capacity is consumed

Usage packages

Best practices

Use WebSocket for real-time data

Cache metadata locally

Batch where possible

Use filtered subscriptions

Expected WebSocket throughput

V3 REST data limits

Higher limits

​Tier limits

​How it works

​Monthly usage allowances

​What transferred means

​How capacity is consumed

​Usage packages

​Best practices

​Use WebSocket for real-time data

​Cache metadata locally

​Batch where possible

​Use filtered subscriptions

​Expected WebSocket throughput

​V3 REST data limits

​Pagination limits

​Higher limits

Tier limits

How it works

Monthly usage allowances

What transferred means

How capacity is consumed

Usage packages

Best practices

Use WebSocket for real-time data

Cache metadata locally

Batch where possible

Use filtered subscriptions

Expected WebSocket throughput

V3 REST data limits

Pagination limits

Higher limits