Metadata-Version: 2.4
Name: polyorderbooks
Version: 0.1.0
Summary: Official Python SDK for the PolyOrderbooks historical Polymarket data API.
Project-URL: Homepage, https://polyorderbooks.com
Project-URL: Documentation, https://docs.polyorderbooks.com
Project-URL: Repository, https://github.com/polyorderbooks/python-sdk
Project-URL: Issues, https://github.com/polyorderbooks/python-sdk/issues
Author-email: PolyOrderbooks <contact@polyorderbooks.com>
License: MIT
License-File: LICENSE
Keywords: api,order-book,polymarket,prediction-markets
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0.0,>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# PolyOrderbooks Python SDK

Official Python client for the [PolyOrderbooks API](https://docs.polyorderbooks.com) — historical Polymarket order books, prices, and liquidity metrics.

[![CI](https://github.com/polyorderbooks/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/polyorderbooks/python-sdk/actions/workflows/ci.yml)

## Install

```bash
pip install polyorderbooks
```

Or install the latest from GitHub:

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

## Quickstart

Get an API key from [polyorderbooks.com/signup](https://polyorderbooks.com/signup), then:

```python
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()
```

Context manager usage:

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

## Pagination

Use `metadata.next_cursor` manually, or helpers:

```python
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

```python
from polyorderbooks import AuthenticationError, NotFoundError, RateLimitError, APIError
```

- `AuthenticationError` — 401
- `NotFoundError` — 404
- `RateLimitError` — 429
- `APIError` — other HTTP failures

## Development

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

## Links

- Product: [polyorderbooks.com](https://polyorderbooks.com)
- Docs: [docs.polyorderbooks.com](https://docs.polyorderbooks.com)
- OpenAPI: [docs.polyorderbooks.com/openapi.json](https://docs.polyorderbooks.com/openapi.json)

## License

MIT — see [LICENSE](LICENSE).
