Metadata-Version: 2.4
Name: depthfeed
Version: 0.1.0
Summary: Python client for DepthFeed — historical order-book depth for prediction markets
Project-URL: Homepage, https://depthfeed.com
Project-URL: Documentation, https://depthfeed.com/docs
Project-URL: API Reference, https://depthfeed.com/data-api
Project-URL: Source, https://gitlab.com/vcorp-dev/depthfeed-python
Project-URL: Changelog, https://depthfeed.com/docs#changelog
Author: DepthFeed
License: MIT
License-File: LICENSE
Keywords: backtesting,historical-data,kalshi,market-data,order-book,polymarket,prediction-markets,quantitative-finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# depthfeed

Python client for [DepthFeed](https://depthfeed.com) — historical order-book **depth** for
prediction markets.

Prediction-market venues publish a live order book and archive none of it. Once a short-dated
market resolves, its depth history is gone and cannot be backfilled by anyone. DepthFeed
records it — full bid/ask ladders on both sides, captured event-driven rather than sampled —
and serves it over a REST API. This is the client for that API.

Coverage: Polymarket, Kalshi and Limitless, across BTC, ETH, SOL, XRP, DOGE, BNB and HYPE.

```bash
pip install depthfeed
```

## Quickstart

Create a free account at [depthfeed.com/signup](https://depthfeed.com/signup) and mint an API
key from the dashboard. Keys look like `df_…` and are shown once.

```python
from depthfeed import DepthFeed

client = DepthFeed()  # reads DEPTHFEED_API_KEY, or pass api_key="df_…"

print(client.whoami())        # your plan, rate limits, history window

markets = client.markets("btc", limit=5)
for market in markets:
    print(market["market_id"])
```

## Order-book depth

The point of the API. Pass `include_orderbook=True` to get the full ladder rather than
summary fields.

```python
snapshots = client.snapshots(
    "btc",
    market_id,
    interval="1m",
    include_orderbook=True,
    start_time="2026-08-01T00:00:00Z",
    end_time="2026-08-02T00:00:00Z",
)

for snap in snapshots:
    best_bid = snap["orderbook"]["bids"][0]
    print(snap["timestamp"], best_bid["price"], best_bid["size"])
```

For the book in force at one instant, `snapshot_at` takes a timestamp directly (crypto coins
only — for the other venues, use `snapshots` with a narrow window):

```python
book = client.snapshot_at("btc", market_id, "2026-08-01T12:00:00Z")
```

## Pagination

List endpoints use opaque keyset cursors. The `iter_*` methods follow them for you and yield
items one at a time, so a long window streams instead of accumulating in memory.

```python
for market in client.iter_markets("btc"):
    ...

for snap in client.iter_snapshots("btc", market_id, include_orderbook=True):
    ...
```

If you want the pages themselves, the single-page methods expose the cursor:

```python
page = client.markets("btc", limit=100)
page.next_cursor   # feed back as cursor=
page.has_more
page.request_id    # from the response meta block, useful in support requests
```

## Venues

Crypto assets are addressed by coin; the other venues have their own roots. The client handles
the path difference — pass the venue as the first argument either way.

```python
client.markets("btc")                       # /v3/btc/markets
client.markets("kalshi")                    # /v3/kalshi/markets
client.markets("limitless")                 # /v3/limitless/markets
client.snapshots("kalshi", "TICKER")        # /v3/kalshi/TICKER/snapshots
client.screener("btc", "15m")               # /v3/screener/btc/15m
client.screener()                           # /v3/screener — cross-asset
```

Binance spot and futures reference data sits on a different path shape and has its own
methods, so the two families don't get confused:

```python
client.reference_latest("btc", "spot")              # /v3/btc/spot/latest
client.reference_snapshots("btc", "futures")        # /v3/btc/futures/snapshots
client.reference_trades("btc", "spot", latest=True) # /v3/btc/spot/trades/latest
```

Any endpoint this client does not wrap yet is reachable directly, with the same auth, retry
and envelope handling:

```python
client.get("/v3/sports/markets", league="mlb", limit=10)
```

## Async

`AsyncDepthFeed` mirrors the sync client method for method.

```python
import asyncio
from depthfeed import AsyncDepthFeed

async def main():
    async with AsyncDepthFeed() as client:
        markets = await client.markets("btc", limit=5)
        async for snap in client.iter_snapshots("btc", markets[0]["market_id"]):
            ...

asyncio.run(main())
```

## Errors

HTTP statuses map to typed exceptions, all deriving from `DepthFeedError`.

| Status | Exception |
|---|---|
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 402 | `PaymentRequiredError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 429 | `RateLimitError` (carries `retry_after`) |
| 5xx | `ServerError` |

```python
from depthfeed import RateLimitError

try:
    client.markets("btc")
except RateLimitError as exc:
    print(exc.retry_after, exc.request_id)
```

`429`, `408` and `5xx` responses are retried automatically with exponential backoff, honouring
`Retry-After`. Set `max_retries=0` to turn that off.

## Configuration

```python
DepthFeed(
    api_key=None,                          # else DEPTHFEED_API_KEY
    base_url="https://api.depthfeed.com",
    timeout=30.0,
    max_retries=3,
)
```

## Links

- Documentation — https://depthfeed.com/docs
- API reference — https://depthfeed.com/data-api
- MCP server — https://depthfeed.com/mcp

Independent project. Not affiliated with Polymarket, Kalshi, Binance, Chainlink or Limitless.

MIT licensed.
