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:

importosfromdatetimeimportdatetime, timedelta, timezonefrompolyorderbooksimportPolyOrderbooksClientclient=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,
)
foroutcome, pointsinbooks["data"].items():
forpointinpoints[:2]:
bids=point.get("b") or []
asks=point.get("a") or []
best_bid=bids[0][0] ifbidselseNonebest_ask=asks[0][0] ifaskselseNoneprint(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:

withPolyOrderbooksClient() asclient:
usage=client.get_usage()
print(usage["plan"], usage["limits"])

Pagination

Use metadata.next_cursor manually, or helpers:

forpageinclient.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

frompolyorderbooksimportAuthenticationError, 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.