fireplace-sdk 0.2.0

Python SDK for the Fireplace External API — prediction-market data, wallets, and real-time WebSocket streams.

fireplace-sdk

Python SDK for the Fireplace External API — prediction-market data, wallet analytics, and real-time WebSocket streams.

Installation

pip install fireplace-sdk

Quick Start

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:

export FIREPLACE_API_KEY=fp_pk_your_public_key
export FIREPLACE_API_SECRET=fp_sk_your_secret_key

fp = Fireplace()  # reads from env vars automatically

REST API

Markets

# 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

# 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

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

# 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

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:

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

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:

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