Reference

SDKs & Libraries

Use the official Heisenberg SDK for a fully typed client, or call the single POST endpoint directly with the lightweight wrappers below.

Official SDK — TypeScript & Python

Typed resources, venues, auto-pagination, streaming, and gating built in

One client for the whole intelligence API — hb.polymarket.markets(), hb.wallets.profile(), hb.smartMoney.pulse(), hb.stream.trades() — generated from a single spec so TypeScript and Python stay identical. Read-only; your token is only ever sent as a Bearer header.

Get started with the SDK

Roll your own

The API is a single POST endpoint — no SDK required. Drop one of these lightweight wrappers into any project to get going fast.

Python

requests or httpx — zero dependencies beyond stdlib

heisenberg.py — drop into your project

import requests

class Heisenberg:
    URL = "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized"

    def __init__(self, token: str):
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def query(self, agent_id: int, params: dict = None,
              limit: int = 10, offset: int = 0):
        body = {
            "agent_id": agent_id,
            "params": params or {},
            "pagination": {"limit": limit, "offset": offset},
            "formatter_config": {"format_type": "raw"}
        }
        resp = requests.post(self.URL, json=body, headers=self.headers)
        resp.raise_for_status()
        return resp.json()

# Usage
h = Heisenberg("YOUR_API_TOKEN")
markets = h.query(574, {"min_volume": "1000", "closed": "False"})
print(markets["data"]["results"])

JavaScript / TypeScript

Fetch API — works in Node.js, Deno, Bun, and browsers

heisenberg.ts — drop into your project

const URL = "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized";

export async function query(
  token: string,
  agentId: number,
  params: Record<string, string> = {},
  limit = 10,
  offset = 0
) {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agentId,
      params,
      pagination: { limit, offset },
      formatter_config: { format_type: "raw" },
    }),
  });
  if (!resp.ok) throw new Error(`${resp.status}: ${await resp.text()}`);
  return resp.json();
}

// Usage
const data = await query("YOUR_TOKEN", 574, { min_volume: "1000" });
console.log(data.data.results);

cURL

Quick testing from the command line

Shell

# Set your token once
export HEISENBERG_TOKEN="YOUR_API_TOKEN"

# Query any endpoint by changing agent_id and params
curl -s -X POST https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  -H "Authorization: Bearer $HEISENBERG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 574,
    "params": {"min_volume": "1000"},
    "pagination": {"limit": 5, "offset": 0},
    "formatter_config": {"format_type": "raw"}
  }' | python3 -m json.tool

No Code? Use Claude MCP

Skip the code entirely. Connect Heisenberg AI as an MCP server and query prediction markets in natural language directly inside Claude.

Set up Claude MCP →

Community Contributions

Building a wrapper, SDK, or integration? We'd love to feature it here. Reach out at contact@heisenberg.so.