Heisenberg AIdocs
SDK · Guides

Recipes

Common workflows, end to end. Each runs with a token in HEISENBERG_TOKEN. TypeScript and Python are shown side by side; the shapes returned are documented in Response fields.

Scout a wallet before you copy it

Pull Wallet 360 for skill/risk metrics, then realized PnL history. Check sharpe_ratio, win_rate, and the risk flags before trusting a track record.

TypeScript
const [profile] = (await hb.wallets.profile(wallet, { window_days: 15 })).results;
if (!profile) throw new Error('no Wallet 360 data for this wallet');

console.log({
  roi: profile.roi,
  winRate: profile.win_rate,
  sharpe: profile.sharpe_ratio,          // number | null
  maxDrawdown: profile.max_drawdown,
  sybilRisk: profile.sybil_risk_flag,    // avoid if true
  riskLevel: profile.risk_level,
});

// realized PnL over time
const pnl = await hb.wallets.pnl(wallet, { granularity: '1w' });
Python
rows = hb.wallets.profile(wallet, {"window_days": 15}).page().results
if not rows:
    raise RuntimeError("no Wallet 360 data for this wallet")
p = rows[0]

print(p["roi"], p["win_rate"], p["sharpe_ratio"], p["max_drawdown"],
      p["sybil_risk_flag"], p["risk_level"])

pnl = hb.wallets.pnl(wallet, {"granularity": "1w"}).page()

Read the smart-money picture on a market

Market 360 gives structure and risk; sport Market Pulse (gated) gives sharp-money consensus. Combine them to gauge conviction and liquidity risk before you enter.

TypeScript
const [m360] = (await hb.markets.insights(conditionId)).results;
console.log(m360?.liquidity_tier, m360?.volume_trend, m360?.whale_control_flag);

// sharp-money consensus (requires the Sport plan)
const pulse = await hb.smartMoney.pulse(conditionId);
for (const side of pulse.results) {
  console.log(side.outcome, side.wallet_count, side.avg_entry_price, side.current_price);
}
Python
m = hb.markets.insights(condition_id).page().results
if m:
    print(m[0]["liquidity_tier"], m[0]["volume_trend"], m[0]["whale_control_flag"])

pulse = hb.smart_money.pulse(condition_id).page()   # gated: Sport plan
for side in pulse.results:
    print(side["outcome"], side.get("wallet_count"), side.get("avg_entry_price"))

Find elite wallets by H-Score

Rank wallets by the Heisenberg H-Score, then scout the top few (recipe 1). Remember leaderboard numbers come back as decimal strings.

TypeScript
const board = await hb.leaderboards.heisenberg({ sort_by: 'h_score', limit: 20 });
const top = board.results
  .filter((r) => Number(r.roi_pct_15d) > 0)   // strings -> Number() to compare
  .slice(0, 5);
for (const w of top) console.log(w.leaderboard_rank, w.wallet, w.h_score, w.tier);
Python
board = hb.leaderboards.heisenberg({"sort_by": "h_score", "limit": 20}).page()
top = [r for r in board.results if float(r["roi_pct_15d"]) > 0][:5]
for w in top:
    print(w["leaderboard_rank"], w["wallet"], w["h_score"], w["tier"])

Watch live trades and react

Stream trades for a market (or wallet) and act on them. The stream reconnects and resubscribes automatically. See Streaming for the full filter list.

TypeScript
for await (const t of hb.stream.trades({ condition_id: conditionId })) {
  if (t.size >= 1000) console.log('large fill', t.side, t.price, t.proxy_wallet);
}
Python (needs heisenberg_ai[stream])
for t in hb.stream.trades({"condition_id": condition_id}):
    if (t.get("size") or 0) >= 1000:
        print("large fill", t.get("side"), t.get("price"), t.get("proxy_wallet"))

Handle gated endpoints gracefully

Sport/audience endpoints need a subscription. Check access up front, or catch the typed PlanError. See Errors & limits.

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

if (hb.requires(602)) console.log('closingLine needs a plan:', hb.requires(602));

try {
  const clv = await hb.sports.closingLine(conditionId);
} catch (e) {
  if (e instanceof PlanError) console.log('locked:', e.message, '→', e.requiredPlan);
  else throw e;
}
Python
from heisenberg import PlanError

if hb.requires(602):
    print("closing_line needs a plan:", hb.requires(602))

try:
    clv = hb.sports.closing_line(condition_id).page()
except PlanError as e:
    print("locked:", str(e), "→", e.required_plan)