Polymarket Python API Quickstart

Related guides: For historical data overviews and downloads, see Polymarket historical data, crypto data, MCP server, and order book data.

This guide walks through account setup, API key creation, discovery, and a historical books request on the hosted API.

Prerequisites

A PolyOrderbooks account (free Starter tier)
curl or any HTTP client
Familiarity with ISO-8601 UTC timestamps

1. Create an account and API key

Verify email

Password sign-ups must confirm email via the link we send. Google sign-ups are verified automatically.

Create a key

Open the dashboard → API keys → Create key. Copy the secret immediately — it is shown only once.

Export your key:

export POLYORDERBOOKS_API_KEY="pob_xxxxxxxxxxxxxxxx"

All data requests use:

X-API-Key: pob_xxxxxxxxxxxxxxxx

You may also send Authorization: Bearer pob_…. Dashboard session tokens from login do not work on data routes. See Authentication for security guidance.

Official Python SDK

For Python projects, use the official client on PyPI instead of hand-rolling HTTP calls:

pip install polyorderbooks

Package: pypi.org/project/polyorderbooks
Source: github.com/polyorderbooks/polyorderbooks-python
Runnable scripts: github.com/polyorderbooks/python-examples

The SDK wraps the same REST endpoints documented here and reads POLYORDERBOOKS_API_KEY from the environment.

2. Confirm your API key

After creating a key, confirm it works and review your plan quota:

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/usage" | jq

Example response:

{
  "plan": "starter",
  "organization": "Acme Research",
  "limits": {
    "requests_per_minute": 60,
    "requests_remaining": 58,
    "granularity_allowed": "1s",
    "max_history_days": 3,
    "data_points": {
      "metrics": true,
      "prices": true,
      "books": true
    }
  },
  "reset_at": 1754140860
}

3. Search the catalog

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=bitcoin&limit=10&sort=updated_at&order=desc" \
  | jq '.data[] | {id, slug, question, status}'

Save a slug from the response for the next step.

4. Fetch order book history

Replace MARKET_SLUG with a value from step 3. 1s resolution works on every plan, including Starter; on Starter, history is limited to the last 3 days:

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=1s" \
  | jq '.data'

The response groups book snapshots by outcome label (Yes, No, etc.) with timestamps in UTC.

5. Paginate long ranges

When metadata.next_cursor is present, pass it on the next request (keep the same start_ts, end_ts, and resolution):

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=1s" \
  --data-urlencode "cursor=CURSOR_FROM_PREVIOUS_RESPONSE"

See Pagination for discovery list cursors.

Python example

import os

from polyorderbooks import PolyOrderbooksClient

client = PolyOrderbooksClient(api_key=os.environ["POLYORDERBOOKS_API_KEY"])

markets = client.list_markets(search="btc", limit=5)
slug = markets["data"][0]["slug"]

books = client.get_market_books(
    slug,
    start_ts="2026-07-26T00:00:00Z",
    end_ts="2026-07-26T06:00:00Z",
    resolution="1s",
)
print(books["data"])

import os
import requests

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

markets = requests.get(
    f"{BASE}/v1/markets",
    params={"search": "btc", "limit": 5},
    headers=headers,
    timeout=60,
)
markets.raise_for_status()

slug = markets.json()["data"][0]["slug"]

books = requests.get(
    f"{BASE}/v1/markets/{slug}/books",
    params={
        "start_ts": "2026-07-26T00:00:00Z",
        "end_ts": "2026-07-26T06:00:00Z",
        "resolution": "1s",
    },
    headers=headers,
    timeout=120,
)
books.raise_for_status()
print(books.json()["data"])

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=btc&limit=5"

Next steps

Plans & limits

Starter, Pro, and Enterprise capabilities.

Discovery filters

Tags, date ranges, sorting, and market detail.

Historical data

Metrics, books, resolutions, and token-level endpoints.

Rate limits

Quotas, 429 handling, and efficient bulk access.

Python SDK

Install polyorderbooks from PyPI.

Python examples

Clone runnable scripts for books and backtests.

Related reading: Polymarket API guide — official Polymarket endpoints, rate limits, and when a historical archive helps. Or download a free BTC 5-minute L2 sample to inspect the data shape before you write any code.

Getting started

Discovery

Historical

Backtest AI

Reference

Polymarket Python API Quickstart

Prerequisites

1. Create an account and API key

Official Python SDK

2. Confirm your API key

3. Search the catalog

4. Fetch order book history

5. Paginate long ranges

Python example

Next steps

Plans & limits

Discovery filters

Historical data

Rate limits

Python SDK

Python examples

​Prerequisites

​1. Create an account and API key

​Official Python SDK

​2. Confirm your API key

​3. Search the catalog

​4. Fetch order book history

​5. Paginate long ranges

​Python example

​Next steps

Plans & limits

Discovery filters

Historical data

Rate limits

Python SDK

Python examples

Prerequisites

1. Create an account and API key

Official Python SDK

2. Confirm your API key

3. Search the catalog

4. Fetch order book history

5. Paginate long ranges

Python example

Next steps