### Install Streaming Extra

Source: https://prediction.heisenberg.so/docs/sdk/streaming

Install the necessary WebSocket dependency for streaming functionality.

```bash
# TypeScript
npm install ws
```

```bash
# Python
pip install "heisenberg_ai[stream]"
```

--------------------------------

### Install Python SDK

Source: https://prediction.heisenberg.so/docs/sdk/python

Install the core Python SDK and the optional streaming extra using pip.

```bash
pip install heisenberg_ai
pip install "heisenberg_ai[stream]"   # optional, for streaming
```

--------------------------------

### Install Heisenberg SDK

Source: https://prediction.heisenberg.so/docs/sdk

Install the Heisenberg SDK using pip for Python or npm for Node.js.

```bash
pip install heisenberg_ai
```

```bash
npm install heisenberg-ai
```

--------------------------------

### Wallet Address Example

Source: https://prediction.heisenberg.so/docs/api-reference/wallet-stats-all-time

Example of a valid wallet address format required for filtering.

```string
"0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
```

--------------------------------

### Install Heisenberg AI SDK and ws

Source: https://prediction.heisenberg.so/docs/sdk/typescript

Install the core SDK package and the optional 'ws' package for streaming capabilities using npm.

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

--------------------------------

### 200 OK Example Response

Source: https://prediction.heisenberg.so/docs/api-reference/wallet-stats-all-time

Example JSON response containing all-time wallet statistics for a given address.

```json
{
  "timestamp": "",
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "avg_pnl_per_trade": "2.26",
        "avg_trade_size": "122.24",
        "last_updated": "2026-03-14T00:00:00Z",
        "proxy_wallet": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e",
        "roi_pct": "1.85",
        "total_invested": "22785473.35",
        "total_pnl": "420395.44",
        "total_trades": 186403
      }
    ]
  }
}
```

--------------------------------

### Example Spot Market Response

Source: https://prediction.heisenberg.so/docs/api-reference/hyperliquid-spot-markets

This is an example of a successful response when querying for spot market data. It includes details for a specific market identified by its index.

```json
{
  "timestamp": "",
  "params": {
    "coin": "@107"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "coin": "@107",
        "index": 107,
        "base_token": "HYPE",
        "quote_token": "USDC",
        "is_canonical": false,
        "prev_day_px": 64.717,
        "mark_px": 65.544,
        "mid_px": 65.5525,
        "day_ntl_vlm": 76912970.31807004,
        "day_base_vlm": 1204106.729999999
      }
    ]
  }
}
```

--------------------------------

### Install and Run Heisenberg MCP for Claude Desktop

Source: https://prediction.heisenberg.so/docs/getting-started/mcp

Run this command in your terminal to install and configure the Heisenberg MCP server for Claude Desktop. Follow the prompts to authenticate.

```bash
npx heisenberg-mcp
```

--------------------------------

### Pagination Example

Source: https://prediction.heisenberg.so/docs/getting-started/response-format

Demonstrates how to paginate through results by checking the 'has_more' flag and incrementing the 'offset' by the 'limit'.

```json
// Page 1
{ "pagination": { "limit": 50, "offset": 0 } }

// Page 2 (if has_more: true)
{ "pagination": { "limit": 50, "offset": 50 } }

// Page 3
{ "pagination": { "limit": 50, "offset": 100 } }
```

--------------------------------

### Example Price Jump Detection Response

Source: https://prediction.heisenberg.so/docs/concepts/intelligence-outputs

This JSON object shows an example of a detected price jump, including time, direction, percentage change, and volume.

```json
{
  "jump_time": "2026-04-06T02:00:00Z",
  "direction": "down",
  "change_pct": "-16.67",
  "price_before": "0.1800",
  "price_after": "0.1500",
  "volume": "7350.07",
  "trade_count": 28
}
```

--------------------------------

### Quickstart: Fetch Markets and Wallet Profile (TypeScript)

Source: https://prediction.heisenberg.so/docs/sdk

Initialize the Heisenberg client with an API token and fetch market data or a wallet profile. The free tier does not require a subscription.

```typescript
import { Heisenberg } 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 });

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

--------------------------------

### Make a Sample API Request

Source: https://prediction.heisenberg.so/docs/api-reference

Send a POST request to the base URL with your API key, agent ID, parameters, pagination, and formatter configuration. This example demonstrates retrieving data with specific filters.

```bash
curl -X POST \
  https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": 574,
    "params": { "min_volume": "1000", "closed": "False" },
    "pagination": { "limit": 10, "offset": 0 },
    "formatter_config": { "format_type": "raw" }
  }'
```

--------------------------------

### Example Perpetual Markets API Response

Source: https://prediction.heisenberg.so/docs/api-reference/hyperliquid-perpetual-markets

This JSON object shows an example response from the Hyperliquid perpetual markets API, detailing market data for '0G' and '2Z'.

```json
{
  "timestamp": "",
  "params": {
    "name": "ALL"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "name": "0G",
        "sz_decimals": 0,
        "max_leverage": 3,
        "only_isolated": false,
        "funding": -0.0000346116,
        "open_interest": 1591008,
        "prev_day_px": 0.20441,
        "day_ntl_vlm": 218606.95021,
        "premium": -0.0002085308,
        "oracle_px": 0.211,
        "mark_px": 0.2105,
        "mid_px": 0.21075,
        "dex": ""
      },
      {
        "name": "2Z",
        "sz_decimals": 0,
        "max_leverage": 3,
        "only_isolated": false,
        "funding": 0.0000125,
        "open_interest": 12323774,
        "prev_day_px": 0.065772,
        "day_ntl_vlm": 309957.282051,
        "premium": 0,
        "oracle_px": 0.06664,
        "mark_px": 0.066594,
        "mid_px": 0.066641,
        "dex": ""
      }
    ]
  }
}
```

--------------------------------

### Quickstart: Fetch Markets and Wallet Profile (Python)

Source: https://prediction.heisenberg.so/docs/sdk

Initialize the Heisenberg client with an API token and fetch market data or a wallet profile. Use .page() for paginated results or iterate directly for auto-pagination.

```python
from heisenberg import Heisenberg

hb = Heisenberg(token="…")  # or set HEISENBERG_TOKEN

markets = hb.polymarket.markets({"min_volume": 1000, "closed": False, "limit": 5}).page()
profile = hb.wallets.profile("0xabc…", {"window_days": 15}).page()

for trade in hb.polymarket.trades({"condition_id": "0x…"}):  # auto-paginates
    ...
```

--------------------------------

### Example API Response for Market Search

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-markets

This is an example of a successful JSON response when searching for markets. It includes the parameters used for the query, pagination details, and the market data results.

```json
{
  "timestamp": "",
  "params": {
    "closed": "True",
    "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
    "end_date_max": "1769213303",
    "end_date_min": "1768467703",
    "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "min_volume": "100"
  },
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "closed": true,
        "closed_date": "2026-01-17T22:07:24Z",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "end_date": "2026-01-17T21:00:00Z",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "question": "Bitcoin Up or Down - January 17, 3PM ET",
        "side_a_outcome": "Up",
        "side_a_token_id": "54962395221233298907357564706944806093710338832907683007646483576474886134345",
        "side_b_outcome": "Down",
        "side_b_token_id": "99436386356623686771311452414494038846982778884699006473918967429453507432222",
        "slug": "bitcoin-up-or-down-january-17-3pm-et",
        "start_date": "2026-01-15T20:01:06.506385Z",
        "volume_total": 104456.760687,
        "winning_outcome": "Up"
      }
    ]
  }
}
```

--------------------------------

### Market 360 API Example Response

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-market-360

This is an example of a successful response from the Market 360 API, detailing a specific market's attributes and performance metrics.

```json
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "max_unique_traders_7d": "0",
    "min_liquidity_percentile": "0",
    "min_top1_wallet_pct": "0",
    "min_volume_24h": "0",
    "volume_trend": "ALL"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0x24fb7c2d95c93a68018e6c4a90d88043bb67d32fd1454924cef8ebdd550228f3",
        "created_at": "2026-02-09T16:53:53.025942Z",
        "current_volume_24h": "44646247.155082",
        "current_volume_7d": "116971972.905561",
        "end_date": "2026-03-31T00:00:00Z",
        "liquidity_percentile": "100.00",
        "liquidity_risk_flag": false,
        "liquidity_tier": "Top 5%",
        "market_active": true,
        "market_closed": false,
        "net_pnl": "102441.064396",
        "no_avg_pnl": "-13.643443",
        "peak_hour_trades": 391,
        "profit_loss_ratio": "2.43",
        "question": "Will Israel launch a major ground offensive in Lebanon by March 31?",
        "slug": "will-israel-launch-a-major-ground-offensive-in-lebanon-by-march-31",
        "snapshot_time": "2026-03-25T18:00:00.010272Z",
        "squeeze_risk_flag": false,
        "top10_wallet_pct": "65.45",
        "top1_wallet_pct": "18.28",
        "top3_wallet_pct": "36.24",
        "trade_concentration_flag": false,
        "trades_per_hour_avg": "213.08",
        "unique_traders_7d": 4941,
        "updated_at": "2026-03-25T18:00:00.010272Z",
        "volume_collapse_risk_flag": false,
        "volume_ratio_24h_to_7d": "267.18",
        "volume_trend": "Spiking",
        "whale_control_flag": false,
        "winning_side": "Yes",
        "yes_avg_pnl": "44.593246"
      }
    ]
  },
  "request_id": ""
}
```

--------------------------------

### Example Response for Wallet Trades

Source: https://prediction.heisenberg.so/docs/api-reference/hyperliquid-wallet-trades

This is an example JSON response when successfully retrieving wallet trades. It includes trade details, pagination information, and the parameters used for the query. The 'data.results' array contains individual trade objects.

```json
{
  "timestamp": "",
  "params": {
    "address": "0x5a7581618829f377a16be2338eabdd03fece0eaf",
    "symbol": "ALL",
    "market_type": "ALL",
    "start_time": "1600000000",
    "end_time": "2200000000"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "tid": 563178213904701,
        "symbol": "BTC",
        "side": "B",
        "price": 78170,
        "size": 0.00217,
        "trade_time": "2026-05-17T18:53:55.967000Z",
        "hash": "0xed931b90908e03bdef0c043b9fa8150202f700762b81228f915bc6e34f81dda8",
        "buyer": "0x5a7581618829f377a16be2338eabdd03fece0eaf",
        "seller": "0xb668858ff53322d5511651a2cd92391eb5d60ee3",
        "is_liquidation": false,
        "market_type": "perp",
        "trade_type": "buyer",
        "counterparty": "0xb668858ff53322d5511651a2cd92391eb5d60ee3",
        "address": "0x5a7581618829f377a16be2338eabdd03fece0eaf"
      }
    ]
  }
}
```

--------------------------------

### Migrate Polymarket Markets GET Request

Source: https://prediction.heisenberg.so/docs/getting-started/migration

Shows the direct Polymarket API GET request for markets.

```http
GET https://clob.polymarket.com/markets
  ?closed=false
  &limit=10
Headers: ...
```

--------------------------------

### Polymarket Trades API Response Example

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-trades

This is an example of a successful response when retrieving Polymarket trade data. It includes details about the trade parameters, pagination, and a list of trade results.

```json
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "start_time": "1767973812",
    "wallet_proxy": "ALL"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 225.23,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0xb07225fa95a2b5dd0f15b3f41f07657d9eb9e928268d4e5ae9fdf7e178049ac7",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 14.99,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      }
    ]
  }
}
```

--------------------------------

### cURL Example for API Request

Source: https://prediction.heisenberg.so/docs/getting-started/authentication

This cURL command demonstrates how to make a POST request to the API, including the necessary Authorization and Content-Type headers, and a sample JSON payload.

```bash
curl -X POST \
  https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"agent_id": 574, "params": {"min_volume": "1000"}}'
```

--------------------------------

### Polymarket PnL API Response Example

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-pnl

This is an example of a successful response from the Polymarket PnL API. It includes aggregated performance metrics such as invested amount, PnL, trades, wins, losses, and win rate for each day within the specified range.

```json
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "2026-02-28",
    "granularity": "1d",
    "start_time": "2026-02-10",
    "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "date": "2026-02-19T00:00:00Z",
        "invested": "830494.18",
        "losses": 0,
        "pnl": "0.00",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 3342,
        "win_rate": "0.00",
        "wins": 0
      },
      {
        "date": "2026-02-20T00:00:00Z",
        "invested": "241245.70",
        "losses": 18,
        "pnl": "-302209.22",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 406,
        "win_rate": "0.49",
        "wins": 2
      }
    ]
  }
}
```

--------------------------------

### Subscribe to Trades (TypeScript)

Source: https://prediction.heisenberg.so/docs/sdk/streaming

Iterate over live trades for a specific condition ID. Ensure the 'ws' package is installed.

```typescript
for await (const trade of hb.stream.trades({ condition_id: '0x…' })) {
    console.log(trade.price, trade.side, trade.proxy_wallet);
}
```

--------------------------------

### Example API Response for Trades

Source: https://prediction.heisenberg.so/docs/api-reference/kalshi-trades

This is an example of a successful API response when retrieving trade data. It includes details such as trade count, creation time, prices, taker side, ticker, and trade ID.

```json
{
  "timestamp": "",
  "params": {
    "end_time": "1774021812",
    "start_time": "1773589812",
    "ticker": "KXSOL15M-26MAR180730-30"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "count": 9,
        "created_time": "2026-03-18T11:29:25.354888Z",
        "no_price": 99.9,
        "taker_side": "yes",
        "ticker": "KXSOL15M-26MAR180730-30",
        "trade_id": "cba52037-21c4-6b04-6544-a2be4124d98e",
        "yes_price": 0.1
      },
      {
        "count": 200,
        "created_time": "2026-03-18T11:29:23.814603Z",
        "no_price": 99.9,
        "taker_side": "no",
        "ticker": "KXSOL15M-26MAR180730-30",
        "trade_id": "4143238d-eb74-75c4-3607-d1b2ea1f0abc",
        "yes_price": 0.1
      }
    ]
  }
}
```

--------------------------------

### Example PnL Leaderboard Response

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-pnl-leaderboard

This is an example JSON response for a PnL leaderboard query. It includes user addresses, ranks, PnL, ROI, win rate, and other performance metrics for the specified period.

```json
{
  "timestamp": "",
  "params": {
    "leaderboard_period": "1d",
    "max_sharpe_ratio": "-1.0",
    "max_total_pnl": "-1.0",
    "max_win_rate": "-1.0",
    "min_sharpe_ratio": "-1.0",
    "min_total_pnl": "-1.0",
    "min_win_rate": "-1.0",
    "wallet_address": "ALL"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "address": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
        "markets_traded": 1,
        "rank": 1,
        "roi": "0.414952",
        "sharpe_ratio": null,
        "total_pnl": "1494121.7168",
        "total_trades": 69,
        "total_volume": "3600711.99",
        "win_rate": "1.0000"
      },
      {
        "address": "0xe90bec87d9ef430f27f9dcfe72c34b76967d5da2",
        "markets_traded": 50,
        "rank": 2,
        "roi": "0.355880",
        "sharpe_ratio": "0.2847",
        "total_pnl": "1092294.3287",
        "total_trades": 1829,
        "total_volume": "3069274.68",
        "win_rate": "0.6290"
      }
    ]
  }
}
```

--------------------------------

### Response for Event Types (Abridged)

Source: https://prediction.heisenberg.so/docs/websockets

An example response from the /event-types endpoint, showing the schema for the 'polymarket.trade' event. The schema details available fields and their filterability.

```json
[
  {
    "name": "polymarket.trade",
    "label": "polymarket_trades_realtime",
    "description": "",
    "schema": {
      "fields": [
        { "name": "slug",         "type": "string", "filterable": true },
        { "name": "proxy_wallet", "type": "string", "filterable": true },
        { "name": "outcome",      "type": "string", "filterable": true },
        { "name": "price",        "type": "float",  "filterable": false }
      ]
    }
  }
]
```

--------------------------------

### Example API Response for Orderbook Data

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-orderbook

This is an example of a successful JSON response when retrieving order book data. It includes the requested parameters, pagination details, and a list of results, each containing asks, bids, timestamp, and token ID for a specific snapshot.

```json
{
  "timestamp": "",
  "params": {
    "end_time": "1770034843377",
    "start_time": "1769902905868",
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "asks": "[{"size": "60", "price": "0.99"}, {"size": "723.17", "price": "0.93"}, {"size": "12", "price": "0.91"}]",
        "bids": "[{"size": "60", "price": "0.01"}, {"size": "25", "price": "0.02"}, {"size": "5.63", "price": "0.03"}, {"size": "12", "price": "0.09"}, {"size": "12", "price": "0.19"}, {"size": "200", "price": "0.28"}, {"size": "29.48", "price": "0.29"}]",
        "timestamp": "2026-02-02T12:01:20.885Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      },
      {
        "asks": "[{"size": "60", "price": "0.99"}, {"size": "5", "price": "0.98"}, {"size": "723.17", "price": "0.93"}, {"size": "12", "price": "0.91"}]",
        "bids": "[{"size": "60", "price": "0.01"}, {"size": "30", "price": "0.02"}, {"size": "5.63", "price": "0.03"}, {"size": "12", "price": "0.09"}, {"size": "12", "price": "0.19"}, {"size": "200", "price": "0.28"}, {"size": "29.48", "price": "0.29"}]",
        "timestamp": "2026-02-02T10:29:08.324Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      }
    ]
  }
}
```

--------------------------------

### Example Response for Outcome Markets

Source: https://prediction.heisenberg.so/docs/api-reference/hyperliquid-outcome-markets

This is an example JSON response when querying for outcome markets. It includes details like outcome ID, market name, description, underlying asset, expiry, and coin leg information.

```json
{
  "timestamp": "",
  "params": {
    "coin": "#350"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "outcome_id": 35,
        "name": "Recurring",
        "description": "class:priceBinary|underlying:BTC|expiry:20260514-0600|targetPrice:80983|period:1d",
        "underlying": "BTC",
        "expiry": "20260514-0600",
        "target_price": 80983,
        "period": "1d",
        "market_class": "priceBinary",
        "yes_coin": "#350",
        "no_coin": "#351",
        "yes_asset_id": 100000350,
        "no_asset_id": 100000351,
        "side": "yes",
        "coin": "#350",
        "coin_counterparty": "#351"
      }
    ]
  }
}
```

--------------------------------

### Example Kalshi Markets API Response

Source: https://prediction.heisenberg.so/docs/api-reference/kalshi-markets

This is a sample JSON response when successfully retrieving market data. It includes details about the market's status, pricing, and trading volume.

```json
{
  "timestamp": "",
  "params": {
    "close_time_max": "1774021812",
    "close_time_min": "1773589812",
    "event_ticker": "KXSOL15M-26MAR180800",
    "status": "finalized",
    "ticker": "KXSOL15M-26MAR180800-00",
    "title": "SOL price"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "close_time": "2026-03-18T12:00:00Z",
        "created_time": "2026-03-18T00:01:21.613032Z",
        "event_ticker": "KXSOL15M-26MAR180800",
        "expiration_time": "2026-03-25T12:00:00Z",
        "last_price": 0.8,
        "open_time": "2026-03-18T11:45:00Z",
        "result": "no",
        "status": "finalized",
        "ticker": "KXSOL15M-26MAR180800-00",
        "title": "SOL price up in next 15 mins?",
        "volume": 4422,
        "volume_24h": 4422
      }
    ]
  }
}
```

--------------------------------

### Subscribe to Trades (Python)

Source: https://prediction.heisenberg.so/docs/sdk/streaming

Iterate over live trades for a specific condition ID. Ensure the 'heisenberg_ai[stream]' package is installed.

```python
for trade in hb.stream.trades({"condition_id": "0x…"}):
    print(trade.get("price"), trade.get("side"), trade.get("proxy_wallet"))
```

--------------------------------

### Standard API Response Format

Source: https://prediction.heisenberg.so/docs/api-reference

All endpoints return a consistent JSON structure. This example shows the basic fields including timestamp, parameters, pagination details, data results, and request ID.

```json
{
  "timestamp": "...",
  "params": { ... },
  "pagination": { "limit": 10, "offset": 0, "has_more": false },
  "data": { "results": [ ... ] },
  "request_id": "..."
}
```

--------------------------------

### Make Your First API Request

Source: https://prediction.heisenberg.so/docs/getting-started

Use this cURL command to send a POST request to the API to retrieve prediction market data. Ensure you replace 'YOUR_API_TOKEN' with your actual API key.

```bash
curl -X POST \
  https://narrative.agent.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "agent_id": 574,
    "params": {
      "min_volume": "1000",
      "closed": "False"
    },
    "pagination": { "limit": 10, "offset": 0 },
    "formatter_config": { "format_type": "raw" }
  }'
```

--------------------------------

### Candlestick Data Response Example

Source: https://prediction.heisenberg.so/docs/api-reference/polymarket-candlesticks

This is an example of a successful JSON response when requesting candlestick data. It includes details for each candle such as open, high, low, close prices, volume, and trade count.

```json
{
  "timestamp": "",
  "params": {
    "end_time": "1770083100",
    "interval": "4h",
    "start_time": "1769910300",
    "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "ask_close": "0.5100",
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": "0.5000",
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": "0.0100",
        "candle_time": "2026-02-01T00:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5033",
        "open": "0.5000",
        "outcome": "No",
        "spread": "0.0100",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 6,
        "volume": "135.97"
      },
      {
        "ask_close": "0.5100",
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": "0.5000",
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": "0.0100",
        "candle_time": "2026-02-01T04:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5038",
        "open": "0.5000",
        "outcome": "No",
        "spread": "0.0100",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 15,
        "volume": "1020.08"
      }
    ]
  },
  "request_id": ""
}
```

--------------------------------

### Wallet 360 API Example Response

Source: https://prediction.heisenberg.so/docs/api-reference/wallet-360

This is a sample JSON response from the Wallet 360 API, showing detailed metrics for a given wallet address and time window. The response includes performance indicators, market data, and trade statistics.

```json
{
  "timestamp": "",
  "params": {
    "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
    "window_days": "3"
  },
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "annualized_return": 4.7138,
        "avg_position_size": 2379.96,
        "best_trade": 75126.54,
        "calculation_window_days": 3,
        "calmar_ratio": null,
        "category_diversity_score": 1.6501,
        "coefficient_of_variation": 3.9035,
        "combined_risk_score": 10,
        "curve_smoothness": 0.0292,
        "date": "2026-03-15T00:00:00Z",
        "date_range_end": "2026-03-15T00:00:00Z",
        "date_range_start": "2026-03-13T00:00:00Z",
        "days_active": 3,
        "dominant_market_id": "0x42a016b0a4bdf4de840334551b04bda95fcf02e4626c60bb49e3b1f1530067a3",
        "dominant_market_pnl": -68490.68,
        "drawdown_frequency": 0,
        "edge_decay": null,
        "equity_curve_pattern": "volatile",
        "flagged_metrics": "{position_size_volatility}",
        "gain_to_pain_ratio": 100,
        "last_active": "2026-03-15T23:59:59.999999Z",
        "losing_trades": 2086,
        "market_concentration_ratio": 0.029,
        "markets_traded": 3146,
        "max_drawdown": 0,
        "max_position_pct": 0.3048,
        "num_markets_traded": 3146,
        "perfect_entry_count": 1204,
        "perfect_exit_count": 0,
        "perfect_timing_flag": false,
        "perfect_timing_score": 0.2258,
        "performance_by_category": "W3sicG5sIjogMTYxNzE3LjY4LCAidHJhZGVzIjogNjQwMCwgImNhdGVnb3J5IjogIk90aGVyIn0sIHsicG5sIjogNTgzMDguNTgsICJ0cmFkZXMiOiAyODUsICJjYXRlZ29yeSI6ICJXb3JsZCBFdmVudHMifSwgeyJwbmwiOiA0NzI1OS45OSwgInRyYWRlcyI6IDkzNSwgImNhdGVnb3J5IjogIlNwb3J0cyJ9LCB7InBubCI6IDIyNzk5LjEyLCAidHJhZGVzIjogODIsICJjYXRlZ29yeSI6ICJTY2llbmNlICYgVGVjaCJ9XQ==",
        "performance_trend": "improving",
        "position_size_consistency": 0,
        "position_size_volatility_flag": true,
        "profit_factor": 1.0972,
        "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
        "recovery_time_avg": 0,
        "risk_level": "LOW",
        "roi": 3.8743,
        "sharpe_ratio": 50,
        "similar_wallets_count": 0,
        "single_market_dependence_flag": false,
        "sortino_ratio": null,
        "statistical_confidence": 0.9966,
        "stddev_position_size": 4645.09,
        "suspicious_timing_trades": 0,
        "suspicious_win_rate_flag": false,
        "sybil_risk_flag": false,
        "sybil_risk_score": 0,
        "timing_anomaly_flag": false,
        "timing_hit_rate": 0,
        "timing_z_score": 0.61,
        "total_closed_positions": 2666,
        "total_invested": 7487360.92,
        "total_pnl": 290085.37,
        "total_timed_trades": 85719,
        "total_trades": 85719,
        "trade_size_stdev": 418.9442,
        "trade_timing_correlation_max": 0,
        "ulcer_index": 0,
        "win_rate": 0.522,
        "win_rate_last_30d": 0.5133,
        "win_rate_z_score": -5.37,
        "winning_trades": 2278,
        "worst_trade": -83113.9
      },
      {
        "annualized_return": -8.6915,
        "avg_position_size": 2045.27,
        "best_trade": 51771.41,
        "calculation_window_days": 3,
        "calmar_ratio": -86.6618,
        "category_diversity_score": 0.6255,
        "coefficient_of_variation": 4.0603,
        "combined_risk_score": 10,
        "curve_smoothness": 0.1176,
        "date": "2026-03-14T00:00:00Z",
        "date_range_end": "2026-03-14T00:00:00Z",
        "date_range_start": "2026-03-12T00:00:00Z",
        "days_active": 3,
        "dominant_market_id": "0x09eb95f347c8ca17d639371297175ed15f397c531e8ef13286382cda2a2595d1",
        "dominant_market_pnl": -178633.03,
        "drawdown_frequency": 0.3333,
        "edge_decay": null,
        "equity_curve_pattern": "volatile"
      }
    ]
  }
}
```

--------------------------------

### Fetch Market Data with Python SDK

Source: https://prediction.heisenberg.so/docs/sdk/python

Retrieve market data for Polymarket, Kalshi, and Hyperliquid. Supports checking API endpoint support.

```python
markets = hb.polymarket.markets({"min_volume": 1000, "closed": False}).page()
book    = hb.polymarket.orderbook({"token_id": "…"}).page()
kalshi  = hb.kalshi.markets({"status": "open"}).page()
hl      = hb.hyperliquid.wallet_trades({"address": "0x…"}).page()

hb.polymarket.supports("orderbook")  # True
hb.kalshi.supports("orderbook")      # False
```

--------------------------------

### Authenticate Python SDK

Source: https://prediction.heisenberg.so/docs/sdk/python

Initialize the Heisenberg client with an API token or by setting the HEISENBERG_TOKEN environment variable.

```python
from heisenberg import Heisenberg

hb = Heisenberg(token="…")  # or HEISENBERG_TOKEN
```

--------------------------------

### Timestamp Format Example

Source: https://prediction.heisenberg.so/docs/getting-started/response-format

All timestamps in responses adhere to the ISO 8601 format in UTC.

```string
2026-04-06T12:00:00Z
```

--------------------------------

### Example H-Score Response

Source: https://prediction.heisenberg.so/docs/concepts/intelligence-outputs

This JSON object represents a typical response for an H-Score, indicating a wallet's trading skill, tier, and trajectory.

```json
{
  "wallet": "0x1a2b...3c4d",
  "h_score": 87,
  "tier": "Elite",
  "trajectory": "rising"
}
```

--------------------------------

### Configure Python SDK Options

Source: https://prediction.heisenberg.so/docs/sdk/python

Customize the Heisenberg client with options for token, timeout, retries, base URL, and transport.

```python
Heisenberg(
    token=None,        # or HEISENBERG_TOKEN
    timeout=30.0,      # seconds
    max_retries=2,     # 429/5xx/network
    base_url=None,     # override the API base
    transport=None,    # inject a transport (tests)
)
```