Workflow
Working with Polymarket data in Python
From pip install to your first order book pull — here is a step-by-step Python workflow for market discovery, price history, L2 books, and liquidity metrics via the PolyOrderbooks API.
What this guide covers
- Official Python SDK on PyPI: pip install polyorderbooks
- Market search, price history, L2 books, and liquidity metrics
- Works with the free Starter tier — 3 days of history included
- Also works with raw requests + X-API-Key header
Setting up your environment
The PolyOrderbooks Python SDK wraps the REST API and handles authentication, pagination, and retries. Install it with pip install polyorderbooks. It requires Python 3.9 or later.
Set your API key via the POLYORDERBOOKS_API_KEY environment variable, or pass it directly to the client constructor. The environment variable approach is recommended for production because it keeps your key out of source code.
If you prefer raw requests, the SDK is optional. All endpoints are REST and documented at docs.polyorderbooks.com. Pass your API key as an X-API-Key header on every request.
Discovering markets
The first step in any workflow is finding the markets you want to analyze. The /markets endpoint returns a list of available markets with slugs, coin identifiers, timeframe tags, and resolution timestamps.
Filter by coin (e.g. ?coin=btc), timeframe (e.g. ?timeframe=5m), or status (active vs resolved). The response includes the slug, which you use for all subsequent API calls.
For batch analysis, paginate through the full market list. The API returns up to 100 markets per request, with a cursor for the next page.
Pulling order books and prices
Once you have a slug, use /markets/{slug}/books for the full L2 order book and /markets/{slug}/prices for the midpoint price series. Both endpoints accept the same resolution parameter (1s to 60s).
The books endpoint returns an array of snapshots, one per second at 1s resolution. Each snapshot contains the complete bid/ask ladder. The prices endpoint returns the midpoint (average of best bid and best ask) at each timestamp.
For a complete market picture, pull both endpoints and join them by timestamp. This gives you depth (from books), price (from prices), and the ability to compute spread, volume-weighted average price, and other metrics.
Working with metrics
The /markets/{slug}/metrics endpoint returns pre-computed liquidity metrics: total bid depth, total ask depth, spread, and volume-weighted average price at each timestamp.
Metrics are computed from the same L2 data you'd get from the books endpoint, but pre-aggregated for convenience. Use them when you need summary statistics without processing raw snapshots.
All three endpoints — books, prices, and metrics — share aligned timestamps, so you can join them in a pandas DataFrame or any analysis tool.
| Endpoint | Returns | Best for |
|---|---|---|
| GET /v1/markets | Market list with slugs | Discovery, filtering |
| GET /v1/markets/{slug}/books | L2 bid/ask snapshots | Backtesting, microstructure |
| GET /v1/markets/{slug}/prices | Midpoint price series | Price charts, trend analysis |
| GET /v1/markets/{slug}/metrics | Liquidity metrics | Spread analysis, depth tracking |
Code examples
from polyorderbooks import PolyOrderbooksClient
import os
client = PolyOrderbooksClient(
api_key=os.environ["POLYORDERBOOKS_API_KEY"],
)
# Discover markets
markets = client.markets.list(coin="btc", limit=5)
slug = markets[0]["slug"]
# Pull data
books = client.markets.books(slug, resolution="1s")
prices = client.markets.prices(slug, resolution="1s")
metrics = client.markets.metrics(slug, resolution="1s")
print(f"{slug}: {len(books)} book snapshots, {len(prices)} price points")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
How do I install the Python SDK?
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.
Can I use requests instead of the SDK?
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.
What is the simplest way to get started?
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.
Does the SDK support async?
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.
Can I use the SDK with Jupyter notebooks?
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.