heisenberg-ai

TypeScript client for the Heisenberg prediction-market intelligence API — smart money, wallet 360, H-Score, CLV, and market-quality signals across Polymarket, Kalshi, and Hyperliquid.

A typed, read-only client, generated from the shared spec (see the repo root).

Install

npm install heisenberg-ai
# optional, for real-time streaming:
npm install ws

Quickstart

import { Heisenberg, PlanError } from 'heisenberg-ai';

const hb = new Heisenberg({ token: process.env.HEISENBERG_TOKEN });

// Free tier — no subscription needed.
const markets = await hb.polymarket.markets({ min_volume: 1000, closed: false, limit: 5 });
const profile = await hb.wallets.profile('0xabc…', { window_days: 15 }); // Wallet 360

// A Query is awaitable (first page) or async-iterable (auto-paginates all pages).
for await (const trade of hb.polymarket.trades({ condition_id: '0x…' })) {
    // …
}

// Real-time trade stream (needs the optional `ws` package).
for await (const trade of hb.stream.trades({ condition_id: '0x…' })) {
    console.log(trade.price, trade.side);
}

// Gated endpoints throw a typed PlanError (the API message is preserved).
try {
    await hb.sports.closingLine('0x…');
} catch (e) {
    if (e instanceof PlanError) console.log(e.message, '→ unlock:', e.requiredPlan);
}

Two axes

• Venues — hb.polymarket, hb.kalshi, hb.hyperliquid. Each exposes the capabilities the venue supports (.markets, .trades, .candlesticks, …), derived from the spec. hb.polymarket.supports('orderbook') tells you what exists.
• Intelligence — hb.wallets, hb.smartMoney, hb.leaderboards, hb.markets, hb.sports, hb.audience, hb.social. Curated, typed methods over the highest-value signal endpoints.

Escape hatch for anything not wrapped: hb.query(agentId, params). Discover endpoints and gating with hb.catalog() / hb.requires(agentId).

What the client handles for you

Native param types → the API's string wire format (booleans → "True"/"False", Date → the right per-param format), the "ALL" sentinel, base64/JSON response columns, envelope unwrapping, auto-pagination, retries with backoff, and typed errors.

Options

new Heisenberg({
    token,          // or HEISENBERG_TOKEN
    timeoutMs,      // default 30000
    maxRetries,     // default 2 (429/5xx/network)
    baseUrl,        // override the API base
    fetch,          // inject a fetch impl (tests / Node < 18)
});

Develop

npm install
npm run build   # regenerate the registry from the spec, then compile
npm test        # unit tests (fake transport; no network)

Generated code lives in src/generated/ and is never edited by hand.

MIT © Seshat Labs