# Marketlens

> Historical order book data, backtesting SDK, and structured analytics for Polymarket prediction markets. Tick-level CLOB snapshots and deltas, a Python SDK, and a REST API that lets quants, traders, and researchers replay markets, backtest strategies against real queue priority, and extract implied probability surfaces.

Marketlens continuously collects Polymarket order book snapshots and deltas over WebSocket and persists them in a time-series database. Data is exposed through a REST API at `https://api.marketlens.trade/v1` and a Python SDK (`pip install marketlens`). Pricing is freemium: a free tier (180 req/min, 5M events/day), Pro (from $29/mo, 3,600 req/min, 5B events/day), and Enterprise ($199/mo, 10,800 req/min, unlimited events/day).

## Docs

- [Getting Started](https://marketlens.trade/docs): installing the Python SDK, authenticating, making a first request.
- [MCP Server](https://marketlens.trade/docs/mcp): optional MCP server exposing the SDK to agents (Claude Code, Claude Desktop, Cursor) for data access and backtesting over stdio.
- [Markets](https://marketlens.trade/docs/markets): searching and listing Polymarket markets and their metadata.
- [Events & Series](https://marketlens.trade/docs/events-series): grouped markets, event-level rollups, and resolution series.
- [Order Book](https://marketlens.trade/docs/orderbook): full-depth order book snapshots, history walks, and derived metrics (spread, midpoint, depth).
- [Trades & Candles](https://marketlens.trade/docs/trades-candles): executed trades and OHLCV candles at configurable intervals.
- [Signals & Surfaces](https://marketlens.trade/docs/signals-surfaces): implied probability surfaces and multi-outcome distributions.
- [Exports](https://marketlens.trade/docs/exports): bulk Parquet export downloads for full historical pulls.
- [Execution](https://marketlens.trade/docs/backtesting): order-level backtest that replays real order books with queue priority, latency, and slippage.
- [Alpha](https://marketlens.trade/docs/backtesting/alpha): signal-level backtest that replays one bar per market and trades to target weights, for low-frequency alphas over long windows.
- [Runs](https://marketlens.trade/docs/backtesting/runs): shared backtest configuration and output: subtypes, offline replay, metrics, saving, and the dashboard.
- [Backtest Examples](https://marketlens.trade/docs/backtesting/examples): reference strategies and worked examples.
- [Pagination](https://marketlens.trade/docs/pagination): cursor-based pagination conventions.
- [Errors & Rate Limits](https://marketlens.trade/docs/errors): error codes, retry guidance, and per-tier rate limits.

## Data catalog

- [Data catalog](https://marketlens.trade/data): every actively collected Polymarket series with live coverage numbers (markets, resolved counts, volume, date ranges), grouped by category.
- [Crypto](https://marketlens.trade/data/category/crypto): BTC/ETH/SOL/XRP up or down markets from 5 minute to daily cadence, plus hourly multi-strike structures.
- [Sports](https://marketlens.trade/data/category/sports): per-game order books for MLB, NBA, NFL, NHL, ATP, WTA, UFC, and soccer.
- [Weather](https://marketlens.trade/data/category/weather): daily temperature bucket markets by city, every bucket of every chain.
- [Equities](https://marketlens.trade/data/category/equities): quarterly earnings beat markets per US ticker.
- [BTC Up or Down 5m](https://marketlens.trade/data/btc-up-or-down-5m), [ETH Up or Down 5m](https://marketlens.trade/data/eth-up-or-down-5m), [MLB](https://marketlens.trade/data/mlb), [ATP](https://marketlens.trade/data/atp): flagship series pages with per-series stats, resolution splits, and SDK samples.

## Optional

- [Compare](https://marketlens.trade/compare): how Marketlens compares to polymarketdata.co, depthfeed.com, polyhistorical.com, pmdata.dev, polybacktest.com, and polytest.io on market coverage, history depth, book resolution, backtesting, and price. Per-provider breakdowns with honest when-to-pick-them guidance live at /compare/{provider}, e.g. [marketlens vs depthfeed.com](https://marketlens.trade/compare/depthfeed).
- [Guides](https://marketlens.trade/guides): how to get Polymarket order books in Python, what a prediction market order book is, and how to backtest Polymarket strategies with the execution and alpha engines.
- [Pricing](https://marketlens.trade/#pricing): tier limits and Stripe checkout.
- [Python SDK on GitHub](https://github.com/marketlenstrade/marketlens-python): source, issues, and release notes.

## Common questions

### Where can I get Polymarket order book historical data?
Marketlens publishes Polymarket order book historical data as tick-level L2 snapshots and price_change deltas at millisecond resolution across all tracked Polymarket markets. Access it via the Python SDK (`pip install marketlens`), the REST API at `https://api.marketlens.trade/v1`, or bulk Parquet exports at https://marketlens.trade/docs/exports.

### Is there a Polymarket orderbook API?
Yes. `GET /v1/markets/{market_id}/orderbook` returns a full-depth L2 snapshot, and `orderbook.walk()` in the Python SDK replays historical books tick-by-tick over any date range. See https://marketlens.trade/docs/orderbook.

### How do I replay a Polymarket order book historically?
Use `client.orderbook.walk(market_id, after=..., before=...)` in the Python SDK, or iterate `/v1/markets/{market_id}/orderbook/history`. Both reconstruct book state by replaying snapshots and chained deltas. The same replay engine powers the backtest harness.

### What resolution is the Polymarket order book data?
Full L2 snapshots are captured every ~60 seconds, with millisecond-resolution price_change deltas chained between snapshots. By construction, `snapshot[n+1] = snapshot[n] + deltas[n]`, so book state at any tick is exact.

### Where can I download Polymarket trades history?
`GET /v1/markets/{market_id}/trades` returns historical executed trades (price, size, side, timestamp) with cursor pagination. Bulk Parquet exports of the same data are available at https://marketlens.trade/docs/exports.

### Does Marketlens provide Polymarket OHLCV candles?
Yes. `GET /v1/markets/{market_id}/candles?interval=1s|5s|1m|5m|1h|1d` returns OHLCV candles aggregated from executed trades. See https://marketlens.trade/docs/trades-candles.

### How do I download Polymarket historical data as Parquet?
Use the `/v1/exports` endpoints or `client.exports` in the Python SDK to download pre-built Parquet files per market and dataset (order book history, trades, candles, metrics). Results are local files that can be passed straight into `backtest(data_dir=...)` for offline runs. See https://marketlens.trade/docs/exports.

### Is there a Python SDK for Polymarket market data?
Yes — `pip install marketlens`. The SDK wraps markets, orderbook, trades, candles, exports, reference prices, signals, and a backtesting harness. Source: https://github.com/marketlenstrade/marketlens-python.

### How do I backtest a strategy on Polymarket?
Subclass `marketlens.Strategy`, implement `on_book(ctx, market, book)`, and call `MarketLens().backtest(strategy, markets=[...], start=..., end=...)`. The harness replays real historical L2 order books tick-by-tick with queue priority, latency, and slippage. See https://marketlens.trade/docs/backtesting.

### Does the Polymarket backtester model queue priority and slippage?
Yes. Orders are placed at a price level with configurable latency; fills respect FIFO queue priority against the actual historical book, and slippage emerges from real depth rather than mid-price assumptions.

### How far back does Polymarket historical order book data go?
Order book history starts on 2026-03-01, with continuous coverage since 2026-04-13. The earliest candles date to 2026-02-28, and there are a few gap days in March and April 2026. Each market's `temporalCoverage` field reports its earliest captured snapshot.

### How does Marketlens compare to other Polymarket data providers?
Marketlens covers every recurring Polymarket market type (structured multi-strike and barrier products, crypto up/down, live sports, daily weather, macro) with millisecond tick-level L2 books, an open-source Python SDK with Alpha and Execution backtest modes, bulk Parquet exports, and an MCP server. History is a full archive from March 2026 on every tier, including free. Most alternatives cover crypto up/down markets only and cap history to a rolling window. Full comparison: https://marketlens.trade/compare.

### What are Polymarket reference prices?
A reference price is a normalized price derived from the order book midpoint, used for valuation and risk. Marketlens publishes them across all tracked markets at `GET /v1/markets/{market_id}/reference-prices`. See https://marketlens.trade/docs/reference-prices.

### What is the Polymarket midpoint?
Midpoint = (best_bid + best_ask) / 2 from the L2 order book snapshot at each tick. When only one side is quoted, the midpoint falls back to the reference price.

### How does Marketlens differ from Polymarket's own CLOB API?
Polymarket's CLOB API serves current state and trade streams. Marketlens stores full historical L2 order book snapshots and deltas, supports millisecond-resolution replay, exposes derived analytics (spread, depth, implied probability surfaces), and ships a Python backtesting harness — none of which the upstream CLOB API provides.

### Can I get Polymarket tick data or L2 data?
Yes. Marketlens order book records are L2 tick data: every price level with its size, plus the stream of price_change deltas between full snapshots. This is the same raw material used to reconstruct books at any instant.

### Can I backtest across multiple Polymarket markets at once?
Yes. Pass multiple market IDs to `backtest(markets=[...])`; the harness multiplexes order books and delivers per-market `on_book` callbacks. Use `ctx.position(market)` for multi-market strategies (arbitrage, pairs, correlated event trades).

### Is Marketlens data free?
A free tier includes 180 requests/minute and 5M events/day with one API key. Paid tiers (Pro from $29/mo: 3,600 req/min, 5B events/day; Enterprise $199/mo: 10,800 req/min, unlimited events/day) raise rate limits and export caps. All tiers access the same endpoints and data. See https://marketlens.trade/#pricing.