Polymarket order book and data guides

1 second on every plan, including the free Starter tier. Paid plans also support coarser query grids from 60s to 1s. The capture cadence is uniform — you choose the grid at query time.

Yes. Resolved markets stay queryable with the winning outcome on every row. Prices and books for the full history are available after resolution — nothing is deleted.

Full bid/ask ladders — every level, not just the top of book. Each row carries aligned bids, asks, spread, depth, and a timestamp. Prices and metrics come on separate endpoints with the same timestamps.

Polymarket's CLOB /book endpoint serves the live order book at the current moment. PolyOrderbooks captures and stores the complete book state at regular intervals, so you can query the exact book that existed at any point in a market's history.

Yes. Omit start_ts and end_ts to get the full lifecycle from market open to resolution. The response includes every 1-second snapshot, which for a 5-minute market is approximately 300 snapshots.

The maximum range depends on your plan. Starter gives 3 days, paid plans give 30–120 days. Within that window, you can query any contiguous range. Large ranges return more data and count more against your daily 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.

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.

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.

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.

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.

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.

Yes. The Starter plan is free, includes order books, prices, and metrics at 1-second resolution with 3 days of history. No credit card required to sign up.

After signing in, go to Dashboard and open the API keys section. Generate a key there. The key is shown once on creation — store it securely.

Pass it as an X-API-Key header on requests to the PolyOrderbooks REST API. The header is per-request, not per-IP.

Yes. You can generate multiple keys from the dashboard. Each key has its own rate limit pool. This is useful for separating development and production traffic.

Revoke the lost key from the dashboard immediately, then generate a new one. The old key is invalidated instantly. Any in-flight requests using the revoked key will fail with 401.

No. The same key works with the Python SDK, raw requests, curl, and any HTTP client. Set it via the POLYORDERBOOKS_API_KEY environment variable or pass it directly to the client.

pip install polyorderbooks. The SDK wraps the REST API and handles authentication, pagination, and retries. Set your API key via the POLYORDERBOOKS_API_KEY environment variable or pass it directly.

Yes. All endpoints are REST and documented at docs.polyorderbooks.com. Pass your API key as an X-API-Key header. The SDK is a convenience wrapper — raw requests work identically.

Sign up for the free Starter plan, grab your API key from the dashboard, pip install polyorderbooks, and call client.markets() to list available markets. From there, pull books or prices for any slug.

The current SDK uses synchronous requests. For async workflows, use aiohttp or httpx directly with the REST API. The endpoints and authentication are the same.

Yes. The SDK works in Jupyter notebooks, Google Colab, and any Python environment. Set the API key as an environment variable before importing the client.

For simple price charts and implied probabilities, yes — /prices-history is free and requires no API key. Use PolyOrderbooks when you need full L2 depth, spread, aligned metrics, or historical book snapshots for fill simulation.

The CLOB /prices-history returns minute-level or sub-minute intervals at best, and older data may only be hourly. PolyOrderbooks captures at 1-second resolution and lets you query grids from 60s down to 1s.

Many users start with /prices-history for quick price checks and move to PolyOrderbooks /books when they need depth for backtesting, slippage analysis, or microstructure research. The free Starter tier gives you 3 days to test the difference.

It's reliable for price-level analysis, but it doesn't give you order book depth. For backtesting that includes fill simulation and slippage, you need the L2 data that only PolyOrderbooks provides.

For a simple price chart, /prices-history is free and fast. For a dashboard that shows depth, spread, and liquidity metrics, PolyOrderbooks /books gives you all the data you need in one endpoint.

Thousands. New 5-minute markets are created every 5 minutes, and longer timeframes (1h, 1d) are created regularly. The /markets endpoint is the authoritative source for the current count.

A slug is a unique identifier for each market, like btc-updown-5m-1787486400. You use it to query order books, prices, and metrics. Slugs encode the coin, timeframe, and resolution timestamp.

For active trading, every 5 to 15 minutes. For batch analysis, every hour is fine. The /markets endpoint is lightweight and does not count heavily against your rate limit.

Yes. Pass ?status=resolved to see only markets that have already settled. Each resolved market includes the winning outcome, which is useful for historical analysis and backtesting.

Metrics are derived from the same L2 order book data used by the /books endpoint. Spread is best_ask minus best_bid. Depth is the sum of all size values on each side. VWAP weights each price level by its size.

Yes. Metrics, books, and prices share the same timestamps, so you can join them in a DataFrame or analysis tool without any time alignment logic.

Yes. The metrics endpoint is separate from the books endpoint. If you only need summary statistics, skip the books endpoint and use metrics directly. This saves processing time and reduces data transfer.

Spread tells you the gap between the best bid and best ask. VWAP tells you the average execution price across all levels, weighted by size. A market can have a tight spread but a high VWAP if there is thin depth beyond the top of book.

https://api.polyorderbooks.com/v1. All endpoints are relative to this base. There is no versioning beyond v1; breaking changes will get a v2 path.

Include an X-API-Key header on every request. Get your key from the dashboard after signing up. There is no OAuth or token refresh flow.

All responses are JSON. Error responses have a consistent {"error": "<message>"} structure. Success responses are arrays or objects depending on the endpoint.

The API returns HTTP 400 with a JSON error message explaining what went wrong. Common causes: missing required parameters, invalid slug, or out-of-range time values.

Yes. The polyorderbooks SDK works in Google Colab with no special setup. Install it with !pip install polyorderbooks and set the API key as an environment variable.

Use coarser resolutions (5s or 1m) for initial exploration, then drill into 1s data for specific time windows. Pandas handles tens of thousands of rows well.

Yes. After building a DataFrame, use df.to_csv("output.csv") to export. This works for any analysis you want to share or use outside the notebook.

Export DataFrames to CSV or Parquet with df.to_csv() or df.to_parquet(). For interactive charts, export as HTML with fig.write_html(). You can also share the notebook itself as a .ipynb file or convert it to a static HTML report.

Parquet for analysis and backtesting (fastest queries, smallest files). CSV for sharing with non-technical stakeholders. JSON for API ingestion and debugging.

Typically 3 to 5x smaller for order book data. The exact ratio depends on the number of price levels and the compression ratio.

Yes. DuckDB and Polars can query Parquet files directly without loading them into memory. This is useful for large datasets.

Yes. Sample datasets are provided in Parquet format for optimal file size and query performance. You can convert to CSV or JSON as needed.

It depends on how many markets you track. Each market requires one request per endpoint (books, prices, metrics). Tracking 500 active markets means ~1,500 requests per run.

The SDK handles retries and pagination automatically, which saves code. Raw requests give you more control over error handling and logging. For production pipelines, raw requests with explicit retry logic are often preferred.

Refresh your market index at the start of each pipeline run. New markets appear in the /markets list before they start trading.

Log the failure and retry on the next scheduled run. Do not retry immediately because if the API is down for maintenance, immediate retries waste rate limit budget.

L1 shows only the best bid and best ask (top of book). L2 shows every price level with its size. L2 is essential for depth analysis, fill simulation, and slippage estimation.

Look for price levels with disproportionately large size compared to neighboring levels. These concentrations act as support/resistance.

Depth imbalances are a directional signal but not definitive. Use depth as one input alongside spread, volume, and other indicators.

BTC markets typically have deeper books and tighter spreads than ETH markets. This reflects higher trading volume and more market maker participation.

For active BTC 5-minute markets, spreads of 1 to 2 cents during steady-state trading indicate good liquidity. Wider spreads (5+ cents) suggest low participation.

Market makers widen spreads to protect against adverse selection. As resolution approaches, the risk of being on the wrong side of a binary outcome increases.

Yes. Placing a limit order at the best bid or best ask means you are providing liquidity, not crossing the spread. You earn the spread instead of paying it.

Spread is the minimum cost of immediate execution. Slippage is the additional cost when your order walks through multiple price levels.

For a 500-share buy in a liquid BTC 5-minute market, expect 0.5 to 2 cents of slippage. Larger orders or thinner markets will see more.

In theory, yes, if the book moves in your favor between signal and execution. In practice, slippage is almost always positive (unfavorable).

Use limit orders instead of market orders. Split large orders into smaller pieces over time. Trade in liquid markets (BTC 5-minute) where depth is deepest.

Significantly. A strategy that appears profitable on midpoint data may be unprofitable after accounting for spread and slippage. Always include execution cost modeling.

A Chainlink oracle reads the cryptocurrency price at the resolution timestamp and compares it to the opening price. If the price is higher, the market resolves Up.

No. The oracle price is final. Chainlink decentralized network is designed to produce a single, tamper-resistant price that cannot be disputed.

All outstanding orders are cancelled instantly at the resolution timestamp. Your positions are settled at $1 (winning) or $0 (losing).

Yes. Resolved markets remain fully queryable via the API. Every row reflects the winning outcome.

Yes, typically 0.7 to 0.9 during normal conditions. The correlation reflects the underlying relationship between Bitcoin and Ethereum prices.

You can trade relative value by going long one market and short the correlated market when the spread deviates from its mean. This is a pairs-trading approach.

Compute cross-correlation between two price series at different time offsets. BTC typically leads ETH during volatile periods.

Correlation is strongest during steady-state trading. It can break down near resolution when individual market factors dominate.

At least 20 to 50 markets of the same type (e.g., BTC 5-minute) to get statistical significance.

1s resolution for the most accurate fill simulation. 5s is acceptable for strategies that do not depend on sub-second timing.

Use walk-forward analysis, keep parameter counts low (2 to 3 at most), test on out-of-sample data, and validate on markets not used in optimization.

After accounting for spread and slippage, even modest positive P&L is good. Watch for strategies that are only profitable when ignoring execution costs.

Logic arbitrage is rare because market makers actively monitor quotes. Cross-market arbitrage between platforms is more common but requires multi-platform access.

Yes. Monitor the sum of Up and Down ask prices in real-time. When it drops below $1 minus your threshold, trigger a buy signal for both outcomes.

Logic arbitrage on Polymarket typically yields 0.5 to 2 cents per trade before transaction costs. Volume and speed matter more than per-trade profit.

Execution risk, liquidity risk, market maker reaction, and counterparty risk. Automated systems with low latency help mitigate execution risk.

It depends on spread width and volume. In active BTC 5-minute markets, market makers can earn 0.5 to 2 cents per round-trip trade, multiplied by volume.

You need enough capital to provide meaningful quotes on both sides. For Polymarket prediction markets, $500 to $1,000 is a reasonable starting point.

Adjust your quotes to attract the opposite flow when your inventory is one-sided. Widen your spread as inventory grows. Consider hedging on correlated markets.

Adverse selection (trading against informed flow), inventory risk (market moves against your position), and operational risk (latency, system failures).

Python is the most common choice due to its ecosystem (pandas, requests, asyncio). JavaScript/TypeScript works well for real-time bots using Node.js. Choose what you are most productive in.

Run in paper trading mode: generate signals and log them without placing actual orders. Compare your signals against actual market outcomes to validate your strategy.

API rate limits (use exponential backoff), slippage (account for spread in signals), and bugs (circuit breakers prevent runaway losses).

Log the failure and pause trading. Do not retry aggressively. Resume automatically when the API recovers. Most profitable opportunities can wait a few minutes.

Yes, at the cutover: matching stopped, all resting limit orders were canceled, and every order book was rebuilt. Account balances and open positions carried over automatically, and conditional token IDs did not change.

No. Prices stay quoted 0-1, the L2 snapshot shape is unchanged, and archives read as one continuous series. The only adjustment is fee modeling: apply V1 fee semantics before April 28, 2026 and V2 taker-only fees after it.

Yes. V1 packages and V1-signed orders are no longer accepted on production; pre-V2 clients received HTTP 503 cancel-only responses. The constructor also changed to an options object with chain instead of chainId.

You still deposit and withdraw USDC, but settle on-chain in pUSD, Polymarket's ERC-20 redeemable 1:1 for native USDC. API traders must wrap USDC.e into pUSD before placing V2 orders and approve the V2 exchange contracts.

No. V2 fixed nonce- and balance-related failed fills, but it did not change order-book depth. Spreads and slippage are structurally the same after the upgrade.