Heisenberg Python SDK

Python client for the Heisenberg prediction-market intelligence API — generated from the same spec snapshot as the TypeScript SDK, with the same resource model, venue abstraction, gating semantics, and streaming.

Read-only and synchronous (no async client yet). The REST client uses only the Python standard library (no required deps).

Install

pip install heisenberg_ai            # REST
pip install "heisenberg_ai[stream]"  # + real-time streaming (websocket-client)

Quickstart

from heisenberg import Heisenberg

hb = Heisenberg(token="…")  # or set HEISENBERG_TOKEN

# Free tier — no subscription needed.
markets = hb.polymarket.markets({"min_volume": 1000, "closed": False, "limit": 5}).page()
profile = hb.wallets.profile("0xabc…", {"window_days": 15}).page()

# Iterate a Query to auto-paginate every row.
for trade in hb.polymarket.trades({"condition_id": "0x…"}):
    ...

# Real-time trades (Polymarket only; needs the [stream] extra).
for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"))

Pagination & rate limits

Iterating a Query auto-paginates. The API is rate limited (≈50 req/window); each Page carries page.rate_limit ({"limit","remaining","reset"}, reset in seconds) so you can pace bulk .all() calls, and the client backs off by x-ratelimit-reset on a 429.

Two axes

• Venues — hb.polymarket, hb.kalshi, hb.hyperliquid; each exposes the capabilities the spec says it supports (hb.polymarket.supports("orderbook")).
• Intelligence — hb.wallets, hb.smart_money, hb.leaderboards, hb.markets, hb.sports, hb.audience, hb.social.

Escape hatch for anything not wrapped: hb.query(agent_id, params).

Gated endpoints

Sport/audience endpoints require a subscription and raise a typed PlanError (preserving the API message, plus .required_plan / .endpoint). hb.requires(agent_id) and hb.catalog() report the sport/audience add-on plans — but they are not an exhaustive pre-flight check: access is a property of your token, so some venues (e.g. Hyperliquid) and endpoints can still return PlanError. Always be ready to catch it.

Develop

python -m unittest discover -s tests

Generated code lives in heisenberg/_generated/ (produced by ../scripts/generate.mjs from ../spec/source). Never edit it by hand.