# SmaugLabs Python SDK

Typed Python client for the [SmaugLabs](https://api.smauglabs.com) historical Polymarket data API.

## Install

```bash
pip install smauglabs
```

## Quick Start

```python
from smauglabs import SmaugLabs

client = SmaugLabs(api_key="sl_live_...")

# discover markets
events = client.list_events(limit=5)
results = client.search_markets("Trump", limit=3)
trending = client.trending_markets()

# historical orderbook
chart = client.sovereign_chart("TOKEN_ID", granularity="5m")
snap = client.orderbook_snapshot("TOKEN_ID")
spread = client.spread_history("TOKEN_ID", granularity="1h", limit=50)

# crypto reference prices
btc = client.crypto_klines("BTC", interval="1h", limit=200)
eth = client.crypto_chart("ETH", interval=300, limit=100)

# event correlation
tl = client.event_timeline("EVENT_ID", interval_minutes=5)
news = client.event_news("EVENT_ID")

# trader activity
lb = client.leaderboard(limit=10)
signals = client.latest_signals()
profile = client.trader_profile("0xABC...")

# bulk export for backtesting
data = client.export_klines("BTC", interval="1h", limit=50000)

client.close()
```

### Context Manager

```python
with SmaugLabs(api_key="sl_live_...") as client:
    events = client.list_events()
```

### Custom Base URL

```python
client = SmaugLabs(api_key="...", base_url="http://localhost:8000")
```

## API Reference

Full endpoint docs at [api.smauglabs.com/docs](https://api.smauglabs.com/docs).

| Group | Methods |
|-------|---------|
| Market Discovery | `search_markets` · `list_events` · `get_event` · `trending_markets` · `market_categories` |
| Historical Orderbook | `orderbook_snapshot` · `orderbook_history` · `orderbook_depth` · `spread_history` · `sovereign_chart` · `list_tokens` · `data_coverage` · `cross_market_correlation` · `query` |
| Crypto Reference | `crypto_history` · `crypto_chart` · `crypto_klines` · `crypto_ticks` · `crypto_tick_ohlcv` · `crypto_depth` · `btc_price` |
| Event Correlation | `event_timeline` · `event_news` · `event_metadata` |
| Trader Activity | `leaderboard` · `latest_signals` · `list_traders` · `trader_profile` · `trader_signals` · `trader_trades` · `trader_pnl` |
| Data Export | `export_orderbook` · `export_klines` · `export_catalog` · `list_parquet_files` |

## License

MIT
