> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarketdata.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install polymarketdata-sdk, call discovery and history, and page results with iterators.

Official client for the REST API. It covers the same surface as `/v1` with typed responses, cursor iterators, and retries.

Package: [polymarketdata-sdk](https://pypi.org/project/polymarketdata-sdk/)

## Install

```bash theme={null}
pip install polymarketdata-sdk
```

Dataframe helpers:

```bash theme={null}
pip install "polymarketdata-sdk[dataframe]"
```

## Authenticate

Pass the key, or set `POLYMARKETDATA_API_KEY`.

```python theme={null}
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

```python theme={null}
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