API

PolyOrderbooks API rate limits by plan

PolyOrderbooks enforces per-key rate limits that scale with your plan. This guide covers what each tier allows, how limits are counted, how to handle 429 responses gracefully, and how to compare with Polymarket's own API limits.

What this guide covers

Starter: 60 requests/min, 1,000/day — 3 days of history
Paid windows (30d–120d): 300 requests/min, 50,000/day at Steady speed
Fast add-on (+$19/mo): 1,000/min, 120,000/day — Heavy (+$39/mo): 2,500/min, 300,000/day
Limits are per API key, not per IP

Understanding rate limits by plan

Every PolyOrderbooks API key has two limits: requests per minute (rpm) and requests per day. The minute-level limit controls burst throughput; the daily limit controls total volume. Both reset on different schedules — the per-minute limit is a sliding window, while the daily limit resets at UTC midnight.

The Starter plan is designed for exploration and small-scale projects. At 60 rpm and 1,000 requests per day, you can pull order books for several markets without hitting limits. The 3-day history window is enough to test the API and validate your use case.

Paid data window plans (30d through 120d) include a higher base throughput: 300 rpm and 50,000 requests per day. This is enough for most production applications, including backtesting pipelines that need to pull thousands of market snapshots.

For high-throughput use cases — like building a real-time dashboard or running large-scale backtests — the Fast add-on (+$19/mo) increases to 1,000 rpm and 120,000/day. The Heavy add-on (+$39/mo) goes further: 2,500 rpm and 300,000/day.

PolyOrderbooks rate limits by plan tier
Plan	Price	Requests/min	Requests/day	History
Starter	Free	60	1,000	3 days
30-day window	$19/mo	300	50,000	30 days
60-day window	$29/mo	300	50,000	60 days
90-day window	$39/mo	300	50,000	90 days
120-day window	$49/mo	300	50,000	120 days
+ Fast	+$19/mo	1,000	120,000	On any window
+ Heavy	+$39/mo	2,500	300,000	On any window

Handling 429 responses

When you exceed your rate limit, the API returns HTTP 429 (Too Many Requests) with a Retry-After header indicating how many seconds to wait. The correct response is to pause, then retry with exponential backoff.

A common mistake is to retry immediately. This makes the problem worse — you're sending more requests to an already-throttled endpoint. Instead, respect the Retry-After header and add a small random jitter to avoid thundering-herd effects if you have multiple workers.

Another mistake is creating multiple API keys to bypass limits. Limits are enforced per key, but our abuse detection will flag this pattern. If you consistently need more throughput, upgrade your plan or add the Fast/Heavy speed add-on.

Comparing with Polymarket's own API

Polymarket's CLOB API has its own rate limits, which are IP-based and undocumented. The Gamma API allows roughly 1,000 requests per 10 seconds for general endpoints, but this is a burst limit — sustained high-volume polling will get throttled.

The key difference is predictability. Polymarket's limits are enforced via Cloudflare throttling, which means requests are delayed rather than rejected. You won't get a 429 — your request will just take longer. This makes it harder to know exactly where the limit is.

PolyOrderbooks limits are per key and clearly documented. You know exactly what you get on each plan. If you hit 429, you know you've exceeded the limit and can adjust. This predictability is valuable for production applications.

Code examples

import requests, time, random

def fetch_with_retry(url, headers, params, retries=3):
    """Fetch with exponential backoff and jitter."""
    for attempt in range(retries):
        r = requests.get(url, headers=headers, params=params)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        wait = int(r.headers.get('Retry-After', 2 ** attempt))
        jitter = random.uniform(0, 1)
        time.sleep(wait + jitter)
    raise Exception('Rate limit exceeded after retries')

# Batch multiple market fetches with rate limiting
BASE = 'https://api.polyorderbooks.com/v1'
HEADERS = {'X-API-Key': 'your-key'}
slugs = ['btc-updown-5m-1787486400', 'eth-updown-5m-1787486400']

for slug in slugs:
    data = fetch_with_retry(
        f'{BASE}/markets/{slug}/books',
        HEADERS,
        params={'resolution': '1s'},
    )
    print(f'{slug}: {len(data)} snapshots')
    time.sleep(0.2)  # stay under 300 rpm

Free tier

The Starter plan is free, includes order books, prices, and metrics at 1-second resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.

Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.

FAQ

What happens if I hit the rate limit?

The API returns a 429 status. Pause and retry with exponential backoff. Your daily counter resets at UTC midnight. Rate limits are per API key — creating additional Starter accounts does not bypass them.

How do rate limits compare to Polymarket's own API?

Polymarket's CLOB /prices-history allows ~1,000 requests per 10 seconds but is IP-throttled with undocumented caps. PolyOrderbooks limits are per key and documented on the pricing page — you know exactly what you get.

Can I increase my rate limit?

Upgrade your data window plan for higher base throughput (300 rpm on paid), then add the Fast (+$19/mo) or Heavy (+$39/mo) speed add-on for 1,000 or 2,500 rpm respectively. Enterprise plans have custom limits.

Do rate limits apply to the free Starter plan?

Yes. Starter gets 60 rpm and 1,000 requests per day. This is enough for exploration and small projects. If you consistently hit the limit, it's a signal to upgrade.

How many requests does a typical backtest need?

It depends on the time range and resolution. A 5-minute market at 1s resolution returns ~300 snapshots in one request. Backtesting 100 markets requires 100 requests. At 300 rpm (paid plan), this takes about 20 seconds.

Are there separate limits for different endpoints?

No. The rate limit is global across all API endpoints. Whether you're fetching markets, books, prices, or metrics, every request counts toward the same per-minute and per-day limits.