PolyOrderbooks Python SDK

Official Python client for the PolyOrderbooks API — historical Polymarket order books, prices, and liquidity metrics.

Install

pip install polyorderbooks

Or install the latest from GitHub:

pip install git+https://github.com/polyorderbooks/python-sdk.git

Quickstart

Get an API key from polyorderbooks.com/signup, then:

import os
from datetime import datetime, timedelta, timezone

from polyorderbooks import PolyOrderbooksClient

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

# Or rely on POLYORDERBOOKS_API_KEY in the environment:
# client = PolyOrderbooksClient()

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

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

books = client.get_market_books(
    slug,
    start_ts=start.isoformat().replace("+00:00", "Z"),
    end_ts=end.isoformat().replace("+00:00", "Z"),
    resolution="60s",
    limit=100,
)

for outcome, points in books["data"].items():
    for point in points[:2]:
        bids = point.get("b") or []
        asks = point.get("a") or []
        best_bid = bids[0][0] if bids else None
        best_ask = asks[0][0] if asks else None
        print(point["t"], outcome, "bid", best_bid, "ask", best_ask)

client.close()

markets["data"] is a list of market objects. Each item includes more fields (public_id, volume, event_slug, …); the essentials look like:

[
    {
        "slug": "will-bitcoin-hit-150k-in-2026",
        "question": "Will Bitcoin hit $150k in 2026?",
        "status": "active"
    },
    {
        "slug": "fed-rate-cut-september-2026",
        "question": "Will the Fed cut rates in September 2026?",
        "status": "active"
    }
]

Context manager usage:

with PolyOrderbooksClient() as client:
    usage = client.get_usage()
    print(usage["plan"], usage["limits"])

Pagination

Use metadata.next_cursor manually, or helpers:

for page in client.iter_market_books(
    slug,
    start_ts="2026-04-01T00:00:00Z",
    end_ts="2026-04-02T00:00:00Z",
    resolution="60s",
):
    process(page["data"])

API coverage

Method	Endpoint
get_usage()	GET /v1/usage
list_series(...)	GET /v1/series
list_events(...)	GET /v1/events
list_markets(...)	GET /v1/markets
get_market(id_or_slug)	GET /v1/markets/{id_or_slug}
list_tags()	GET /v1/tags
get_market_metrics(...)	GET /v1/markets/{id_or_slug}/metrics
get_market_prices(...)	GET /v1/markets/{id_or_slug}/prices
get_market_books(...)	GET /v1/markets/{id_or_slug}/books
get_token_prices(...)	GET /v1/tokens/{token_id}/prices
get_token_books(...)	GET /v1/tokens/{token_id}/books

Authentication

Send your API key via the client constructor or POLYORDERBOOKS_API_KEY. The SDK sets X-API-Key on every request (the API also accepts Authorization: Bearer pob_…).

Errors

from polyorderbooks import AuthenticationError, NotFoundError, RateLimitError, APIError

• AuthenticationError — 401
• NotFoundError — 404
• RateLimitError — 429
• APIError — other HTTP failures

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Links

• Product: polyorderbooks.com
• Docs: docs.polyorderbooks.com
• OpenAPI: docs.polyorderbooks.com/openapi.json

License

MIT — see LICENSE.