heisenberg-ai 0.1.0

Python SDK for the Heisenberg prediction-market intelligence API.

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. 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.
for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"))

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). Check ahead with hb.requires(agent_id) or hb.catalog().

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.