Python SDK

Official client for the REST API. It covers the same surface as /v1 with typed responses, cursor iterators, and retries. Package: polymarketdata-sdk

Install

pip install polymarketdata-sdk

Dataframe helpers:

pip install "polymarketdata-sdk[dataframe]"

Authenticate

Pass the key, or set POLYMARKETDATA_API_KEY.

from polymarketdata import PolymarketDataClient

with PolymarketDataClient(api_key="YOUR_API_KEY") as client:
    health = client.utility.health()
    usage = client.utility.usage()
    print(health.status)
    print(usage.plan)
    print(usage.limits.requests_remaining)

Surface map

Namespace	Covers	Core methods
`client.utility`	Health and plan status	`health()`, `usage()`
`client.discovery`	Entity lookup	`list_series()`, `list_events()`, `list_markets()`, `get_market()`, `list_tags()`
`client.discovery` iterators	Auto-pagination	`iter_series()`, `iter_events()`, `iter_markets()`
`client.history`	Historical series	`get_market_metrics()`, `get_market_prices()`, `get_token_prices()`, `get_market_books()`, `get_token_books()`
`client.history` iterators	Auto-pagination	`iter_market_metrics()`, `iter_token_prices()`, `iter_token_books()`

Discovery to history

from polymarketdata import PolymarketDataClient, Resolution

with PolymarketDataClient(api_key="YOUR_API_KEY") as client:
    markets = client.discovery.list_markets(search="bitcoin", limit=5)
    market_id = markets.data[0].slug or markets.data[0].id

    metrics = client.history.get_market_metrics(
        market_id,
        start_ts="2025-09-01T00:00:00Z",
        end_ts="2025-11-05T00:00:00Z",
        resolution=Resolution.ONE_DAY,
    )
    print(metrics.market_id, len(metrics.data))

Resolutions

These match the API resolution enum:

Resolution.ONE_MIN (1m)
Resolution.TEN_MIN (10m)
Resolution.ONE_HOUR (1h)
Resolution.SIX_HOUR (6h)
Resolution.ONE_DAY (1d)

Dataframes

If you installed polymarketdata-sdk[dataframe]:

to_dataframe_metrics(...)
to_dataframe_prices(...)
to_dataframe_books(...)

Errors and retries

All SDK exceptions inherit from PolymarketDataError.

Exception	HTTP
`AuthenticationError`	401
`PermissionDeniedError`	403
`NotFoundError`	404
`RateLimitError`	429
`ServerError`	5xx
`NetworkError` / `RequestTimeoutError`	transport

The client retries 429 and 5xx with exponential backoff and jitter. Tune max_retries, retry_backoff_base, retry_backoff_max, and timeout on PolymarketDataClient.

Response metadata

SDK responses include:

.meta — HTTP metadata such as status_code and request_id
.raw — unmodified payload

Getting started

Guides

SDKs

Install

Authenticate

Surface map

Discovery to history

Resolutions

Dataframes

Errors and retries

Response metadata

​Install

​Authenticate

​Surface map

​Discovery to history

​Resolutions

​Dataframes

​Errors and retries

​Response metadata

Install

Authenticate

Surface map

Discovery to history

Resolutions

Dataframes

Errors and retries

Response metadata