# fireplace-sdk

Python SDK for the [Fireplace](https://pro.fireplace.gg) External API — prediction-market data, wallet analytics, and real-time WebSocket streams.

## Installation

```bash
pip install fireplace-sdk
```

## Quick Start

```python
from fireplace_gg import Fireplace

fp = Fireplace(
    api_key="fp_pk_your_public_key",
    api_secret="fp_sk_your_secret_key",
)

# Search for events
events = fp.search.events(q="Bitcoin", limit=5)

# Get market metadata
market = fp.markets.get_by_id("12345")

# Historical candles with orderbook depth
candles = fp.markets.historical_candles(
    "12345",
    interval="1h",
    include_orderbook=True,
)

# Wallet trades
trades = fp.wallets.trades("0xabc...", side="BUY", limit=20)
```

## Authentication

Get your API key pair from the Fireplace team. Pass them directly or set environment variables:

```bash
export FIREPLACE_API_KEY=fp_pk_your_public_key
export FIREPLACE_API_SECRET=fp_sk_your_secret_key
```

```python
fp = Fireplace()  # reads from env vars automatically
```

## REST API

### Markets

```python
# Discover — get market and event metadata
market = fp.markets.get_by_id("12345")
event = fp.markets.get_event_by_id("67890", show_active=True)

# Candles
latest = fp.markets.latest_candles(["12345", "67890"])
historical = fp.markets.historical_candles(
    "12345",
    interval="1h",
    start_time=1710000000,
    end_time=1710086400,
    include_orderbook=True,
)

# Trades & volume
trades = fp.markets.recent_trades("12345", limit=50, side="BUY")
summary = fp.markets.trades_summary("12345")
volume = fp.markets.get_volume("12345", timescale="24h")
oi = fp.markets.open_interest("12345")

# Orderbook
book = fp.markets.orderbook("12345")

# Positions & holders
top = fp.markets.top_positions("12345", limit=10, amount="1k")
stats = fp.markets.top_positions_stats(["12345", "67890"])
holders = fp.markets.top_holders_stats("12345", all_holders_summary=True)
```

### Wallets

```python
# Trades across wallets
trades = fp.wallets.trades(
    ["0xabc...", "0xdef..."],
    side="BUY",
    min_amount=100,
    start_time="2026-01-01T00:00:00Z",
)

# Net flows — bullish vs bearish signal
flows = fp.wallets.net_flows(
    "0xabc...",
    sort_by="netFlows",
    lookback="7d",
)
```

### Profiles

```python
overview = fp.profiles.overview("0xabc...")
positions = fp.profiles.positions("0xabc...", is_active=True, sort_by="value")
pnl = fp.profiles.historical_pnl("0xabc...", time_period="1w")
activity = fp.profiles.activity("0xabc...", limit=100)
```

### Leaderboard

```python
# Top traders this week
leaders = fp.leaderboard.get(
    timeframe="7d",
    sort_by="total_pnl",
    limit=25,
    min_volume=1000,
)

# Search by username
results = fp.leaderboard.search(q="whale_trader")
```

### Search

```python
events = fp.search.events(
    q="election",
    status="active",
    sort_by="volume",
    volume_min=10000,
    price_min=0.1,
    price_max=0.9,
)
```

## WebSocket Streaming

All streaming methods are async iterators:

```python
import asyncio
from fireplace_gg import Fireplace

fp = Fireplace(api_key="fp_pk_...", api_secret="fp_sk_...")

async def main():
    # Stream trades for specific markets
    async for msg in fp.stream.trades_by_market(["0x123...", "0x456..."]):
        print(f"Trade: {msg['payload']}")

    # Stream trades by wallet
    async for msg in fp.stream.trades_by_wallet(["0xabc..."]):
        print(f"Wallet trade: {msg['payload']}")

    # Stream candle updates
    async for msg in fp.stream.candles(["0x123..."]):
        print(f"Candle: {msg['payload']}")

    # Stream market header updates (price, volume, liquidity)
    async for msg in fp.stream.market_headers(["0x123..."]):
        print(f"Header update: {msg['payload']}")

asyncio.run(main())
```

## Error Handling

```python
from fireplace_gg import (
    Fireplace,
    AuthenticationError,
    RateLimitError,
    BadRequestError,
)

fp = Fireplace(api_key="fp_pk_...", api_secret="fp_sk_...")

try:
    market = fp.markets.get_by_id("12345")
except AuthenticationError:
    print("Invalid API keys")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after:.1f}s")
except BadRequestError as e:
    print(f"Bad request: {e}")
```

## Rate Limits

Default: 5 requests per second (sliding window). After any request you can inspect:

```python
fp.markets.get_by_id("12345")
print(fp.rate_remaining)  # requests left in current window
print(fp.rate_reset)      # unix timestamp when window resets
```

## API Reference

| Namespace | Methods |
|-----------|---------|
| `fp.markets` | `get_by_id`, `get_event_by_id`, `latest_candles`, `historical_candles`, `recent_trades`, `trades_summary`, `get_volume`, `open_interest`, `group_open_interest`, `orderbook`, `top_positions`, `top_positions_stats`, `top_positions_by_event`, `top_holders_stats`, `unique_holders`, `holders_summary` |
| `fp.wallets` | `trades`, `net_flows` |
| `fp.profiles` | `overview`, `positions`, `recent_trades`, `historical_pnl`, `activity` |
| `fp.leaderboard` | `get`, `search` |
| `fp.search` | `events` |
| `fp.stream` | `trades_by_market`, `trades_by_wallet`, `market_headers`, `candles` |

## License

MIT
