Workflow

Polymarket data analysis in Jupyter notebooks

Jupyter notebooks are the fastest way to explore Polymarket order book data interactively. This guide covers notebook setup, using the SDK in notebooks, converting data to pandas DataFrames, and building Plotly visualizations.

What this guide covers

  • Jupyter + polyorderbooks SDK for interactive exploration
  • pandas DataFrames for tabular analysis of book snapshots
  • Plotly charts for spread, depth, and order book heatmaps
  • Works in JupyterLab, Google Colab, and VS Code notebooks

Notebook setup

Start by installing the required packages in a notebook cell: !pip install polyorderbooks pandas plotly. The polyorderbooks SDK handles API communication; pandas structures the data; plotly visualizes it.

Set your API key as an environment variable before importing the client. In Jupyter, use os.environ["POLYORDERBOOKS_API_KEY"] = "your-key" at the top of your notebook.

The SDK works identically in JupyterLab, Google Colab, and VS Code notebooks. No special configuration is needed beyond the API key.

For large datasets, consider using the %%time magic to benchmark query performance. This helps you choose the right resolution and time range.

Loading data into DataFrames

The SDK returns Python lists of dictionaries, which convert directly to pandas DataFrames. After pulling books, prices, or metrics, wrap the result in pd.DataFrame().

For order books, each row is a snapshot with nested bids and asks arrays. To flatten this for analysis, extract the best bid, best ask, spread, and total depth into separate columns.

Timestamps are Unix seconds. Convert them to datetime for readable charts: df["dt"] = pd.to_datetime(df["timestamp"], unit="s").

For multi-market analysis, pull data for several slugs and add a slug column to each DataFrame before concatenating with pd.concat().

Visualizing with Plotly

Plotly’s line charts are ideal for spread and depth time series. Plot spread over time with px.line(df, x="dt", y="spread") to see how liquidity evolves across a market’s lifecycle.

For depth imbalance, compute the ratio (bid_depth - ask_depth) / (bid_depth + ask_depth) and plot it as a line chart. Positive values indicate buying pressure; negative values indicate selling pressure.

Order book heatmaps are powerful for visualizing depth. Use Plotly heatmap trace with price on the y-axis, time on the x-axis, and size as the color intensity.

Combine multiple charts in a single notebook output using Plotly subplots. A common layout is spread on top, depth imbalance in the middle, and a heatmap at the bottom.

Common analysis patterns

Spread lifecycle analysis: plot spread from market open to resolution to see how liquidity tightens or widens as the market matures.

Depth response to events: overlay price moves on depth charts to see how liquidity reacts to large trades or news. Depth often thins before volatile moves and thickens after.

Cross-market comparison: plot metrics for BTC and ETH markets side by side to compare liquidity profiles. BTC markets typically have tighter spreads and deeper books.

All of these patterns are easier to discover interactively in notebooks than in production code. Use notebooks for exploration, then export your analysis logic to production scripts when you’re ready to automate.

Code examples

import os, requests, pandas as pd
import plotly.express as px

BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": os.environ["POLYORDERBOOKS_API_KEY"]}

metrics = requests.get(
    f"{BASE}/markets/btc-updown-5m-1787486400/metrics",
    headers=HEADERS,
    params={"resolution": "1s"},
).json()

df = pd.DataFrame(metrics)
df["dt"] = pd.to_datetime(df["timestamp"], unit="s")
df["imbalance"] = (df["bid_depth"] - df["ask_depth"]) / (df["bid_depth"] + df["ask_depth"])

px.line(df, x="dt", y="imbalance", title="Depth Imbalance Over Time")

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.

Sign up freeView pricing

FAQ

Can I use Google Colab?

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.

How do I handle large datasets in notebooks?

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.

Can I export notebook results to CSV?

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.

How do I share notebook results with my team?

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.