Heisenberg AIdocs
SDK · TypeScript

TypeScript SDK

heisenberg-ai — a typed, read-only client. Node 18+. Zero required runtime dependencies (streaming uses an optional ws package).

Install

npm
npm install heisenberg-ai
npm install ws            # optional, for streaming

Authenticate

Pass a token or set HEISENBERG_TOKEN. The token is only sent as a Bearer header and never logged.

TypeScript
import { Heisenberg } from 'heisenberg-ai';

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

Venues

Every venue exposes the capabilities it supports. Ask with supports(); call an unsupported one and you get a clear error.

TypeScript
const markets = await hb.polymarket.markets({ min_volume: 1000, closed: false });
const book = await hb.polymarket.orderbook({ token_id: '…' });
const kalshi = await hb.kalshi.markets({ status: 'open' });
const hl = await hb.hyperliquid.walletTrades({ address: '0x…' });

hb.polymarket.supports('orderbook'); // true
hb.kalshi.supports('orderbook');     // false

Intelligence

TypeScript
const profile = await hb.wallets.profile('0xabc…', { window_days: 15 }); // Wallet 360
const pnl     = await hb.wallets.pnl('0xabc…', { granularity: '1w' });
const elite   = await hb.leaderboards.heisenberg({ sort_by: 'h_score', limit: 10 });
const pulse   = await hb.smartMoney.pulse('0xcondition…');   // gated (Sport)
const clv     = await hb.sports.closingLine('0xcondition…'); // gated (Sport)

Anything not wrapped is reachable via hb.query(agentId, params). Discover everything with hb.catalog(). Every method maps to an endpoint — see the method → endpoint reference for links into the API reference (params and response fields for each agent).

Pagination

A Query is awaitable (first page) or async-iterable (every row across all pages).

TypeScript
// one page
const page = await hb.polymarket.trades({ condition_id: '0x…' });
console.log(page.results, page.pagination.hasMore);

// every row, auto-paginated
for await (const trade of hb.polymarket.trades({ condition_id: '0x…' })) {
    // …
}

// collect all (use with care on large sets)
const all = await hb.polymarket.trades({ condition_id: '0x…' }).all();

Streaming

TypeScript
for await (const trade of hb.stream.trades({ condition_id: '0x…' })) {
    console.log(trade.price, trade.side);
}
// reconnects with backoff and re-subscribes automatically on disconnect

Errors & gated endpoints

Sport/audience endpoints need a subscription and throw a typed PlanError that preserves the API's message and names the plan. Other failures map to AuthError, RateLimitError, ValidationError, ApiError — all carry a requestId.

TypeScript
import { PlanError } from 'heisenberg-ai';

try {
    await hb.sports.closingLine('0x…');
} catch (e) {
    if (e instanceof PlanError) {
        console.log(e.message, '→ unlock:', e.requiredPlan);
    } else throw e;
}

// check ahead of time
hb.requires(602); // "sport"

Options

TypeScript
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)
});
→ Same, in Python