SDK
Polymarket Python SDK
The marketlens package is a Polymarket Python SDK for historical data: a typed client, sync and async, over every order book, trade, candle, and outcome recorded since March 1, 2026, with pandas at the end of every call and a backtest engine that replays the order books it reads. Python 3.10 and up, MIT licensed, source on GitHub and PyPI.
Install the Polymarket Python SDK
$ pip install marketlens
$ export MARKETLENS_API_KEY=mk_...The key comes from the console after a free sign up, no card. The client reads it from the environment or takes it as MarketLens(api_key=...). Requests retry on rate limits and server errors with backoff, and every error maps to a typed exception.
What the SDK covers
Start from a series slug: it is how the archive is organised and it is the name you already know from Polymarket. Iterators follow pagination cursors on their own, so take=N is how you cap a pull; to_dataframe(), to_list(), and first_page() exist on every list result. Every market carries data_start and data_end, the span it was live in the archive.
Example: from a series to a DataFrame
Leagues and weather cities list their markets with markets.list(series_id=), filtered by close window and bet type; rolling series (crypto up or down) walk in order over a window with series.walk(). Either way the market object is the handle for candles, trades, and books.
from marketlens import MarketLens
client = MarketLens() # MARKETLENS_API_KEY from the environment
# a league: its game winner markets for one day, with the result
for m in client.markets.list(
series_id="mlb", status="resolved", subtype="moneyline",
close_after="2026-09-01T00:00:00Z", close_before="2026-09-02T00:00:00Z", take=3,
):
print(m.question, "->", m.winning_outcome)
# a rolling series: walk it in order over a window
market = next(client.series.walk(
"btc-up-or-down-5m", status="resolved",
after="2026-09-10T12:00:00Z", before="2026-09-10T12:30:00Z",
))
df = client.markets.candles(market.id, resolution="1m",
after=market.data_start, before=market.data_end).to_dataframe()Replay the order book
orderbook.walk() streams the book state by state over a window, for one market or a whole series, rebuilt from the stored snapshots and every price change between them. One minute of a 5 minute BTC series is tens of thousands of states, so keep windows short when printing.
for market, book in client.orderbook.walk(
"btc-up-or-down-5m",
after="2026-09-10T12:00:00Z", before="2026-09-10T12:01:00Z",
):
print(book.as_of, book.best_bid, book.best_ask, book.spread)Backtest a Polymarket strategy
Subclass Strategy, react to books and trades, and the engine fills your orders against the real book with latency, queue position, slippage, and Polymarket fees. on_market_start runs once per market, which is where per market state lives. AlphaStrategy tests a signal one bar per market across thousands of markets when the question is whether it predicts price at all.
from marketlens.backtest import Strategy
class BuyTheDip(Strategy):
def on_market_start(self, ctx, market, book):
self._entered = False
def on_book(self, ctx, market, book):
if not self._entered and book.midpoint < 0.35:
ctx.buy_yes(size=200)
self._entered = True
result = client.backtest(
BuyTheDip(), "btc-up-or-down-5m",
after="2026-09-10T12:00:00Z", before="2026-09-10T12:10:00Z",
initial_cash=10_000, latency_ms=50, fees="polymarket",
)
print(result.summary())Work offline
Download a window once and point every later run at the folder. The export writes one compact Parquet file per market holding its snapshots, price changes, and trades, plus the Binance reference series, so a week of research costs one download.
client.exports.download_series(
"btc-up-or-down-5m", data_dir="data",
after="2026-09-10T12:00:00Z", before="2026-09-10T12:30:00Z",
)
result = client.backtest(
BuyTheDip(), "btc-up-or-down-5m",
after="2026-09-10T12:00:00Z", before="2026-09-10T12:30:00Z",
data_dir="data",
)The official Polymarket Python SDK and this one
Polymarket's own py-sdk and py-clob-client trade and read the live book; this package reads the past and tests strategies. Use both. The same package also runs as a Polymarket MCP server so Claude, Cursor, or any MCP client can query the archive and run backtests in a conversation. The Polymarket API guide explains which official API does what.
FAQ
Polymarket Python SDK questions
Is there a Polymarket Python SDK for historical data?
Yes. The marketlens package is a typed Python client (sync and async) over the Marketlens archive: series, markets, events, the order book at any past moment, trades, candles, implied probability surfaces, Binance reference prices, and Parquet exports, for 903,238 Polymarket markets since March 1, 2026. It also ships the backtest engine and an MCP server.
How is it different from Polymarket's official Python SDK?
Polymarket's own SDK (py-sdk, py-clob-client) trades and reads the live order book. The marketlens package reads history and runs backtests. They do different jobs; a bot typically trades with the first and researches with the second.
Does the SDK return pandas DataFrames?
Every list result exposes to_dataframe(), to_list(), and first_page(), and iterators follow pagination cursors on their own; take=N caps the total. Candles come back indexed by open_time, trades by platform_timestamp. Backtest results return their metrics and ledgers as DataFrames too.
Which Python versions are supported and what does it cost?
Python 3.10 through 3.13, MIT licensed, source on GitHub. The API behind it has a free tier of 600 requests per minute and 25 million rows per day, no card required.
Try it
pip install, then the whole archive
Sync and async clients, pandas everywhere, and a backtest engine on real books. The free tier includes 25M rows per day, no card required.
$ pip install marketlens