API
Below is the full Prediction Market Intelligence catalog (Polymarket, Social): one POST URL, distinct agent_id per endpoint. Each block lists parameters from the official docs, a default JSON body, and a live response after you run it. For MCP, Python SDK, and COOK, use the links in the integration list.
Security
Live calls use a server route (/api/heisenberg-proxy) so the Heisenberg token stays in HEISENBERG_API_TOKEN on the server — not in the browser bundle. Run the app with next dev or next start; pure static hosting of out/ cannot serve this proxy.
Integration options
- Prediction API Quickstart
Log in to view your endpoints, tokens, and request examples for prediction-market intelligence.
- Data Agents Quickstart
Blueprints, instances, simulation, and deploy — the core Heisenberg Data Agents flow.
- REST endpoints
How instances expose API (and related) access after you deploy from COOK or the marketplace.
- Model Context Protocol (MCP)
Plug Data Agents into MCP-compatible clients and multi-step AI workflows.
- Python SDK
Build and extend agents programmatically with the Heisenberg Python SDK.
- COOK launchpad
Visual interface to configure, deploy, and retrieve integration endpoints.
Scopes (typical JWT)
Tokens often include launchpad scopes (agent create/read/update, echo-style flows), retriever scopes (semantic retrieval, echo generation, feature extraction), and user read/write. Match your calls to the operations enabled on your key.
Live requests
Requests go to POST /api/heisenberg-proxy on this app; the server forwards to Heisenberg with your HEISENBERG_API_TOKEN (no token in the browser — avoids CORS). Upstream: https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized
Setup
In .env.local set HEISENBERG_API_TOKEN=… (same JWT as in the Heisenberg dashboard). Restart next dev. Optional: HEISENBERG_API_BASE_URL if upstream URL changes.
Polymarket
Polymarket Markets
agent_id 574Search markets on Polymarket using different filters including market_slug, min_volume, and etc.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| min_volume | string | Minimum trading volume filter |
| condition_id | string | Ethereum condition ID for the market |
| market_slug | string | Market identifier or keyword search |
| event_slug | string | Filter by event slug |
| end_date_min | string | Filter markets ending after this timestamp (inclusive) |
| end_date_max | string | Filter markets ending before this timestamp (inclusive) |
| closed | string | Market status (false = open, true = closed) |
Polymarket Trades
agent_id 556Returns historical trade data from Polymarket with different filters such as trader's address and market slug.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| proxy_wallet | string | Filter by wallet address |
| condition_id | string | Ethereum condition ID for the market |
| market_slug | string | Filter trades by specific market |
| side | string | Trade direction: "BUY" or "SELL" |
| start_time | string | Trades after this timestamp (inclusive) |
| end_time | string | Trades before this timestamp (inclusive) |
Polymarket Candlesticks
agent_id 568Retrieves past candlestick data for a token associated with a market given `token_id` across a specified time interval.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| token_id | string | Blockchain token identifier for the specific market outcome |
| interval | string | Interval of the candlestick. Possible values are `1m` `5m` `15m` `1h` `4h` `1d` `1w` . <br> <br>There are range limits for interval and the end_time will be capped: <br> <br>`1m`: max range 7 days <br>`5m`: max range 15 days <br>`15m`: max range 30 days <br>`1h`: max range 90 days <br>`4h`: max range 180 days <br>`1d`: max range 360 days <br>`1w`: max range 360 days |
| start_time | string | Filter after this timestamp |
| end_time | string | Filter before this timestamp |
Polymarket Price Jumps
agent_id 596Detect significant price jumps on a Polymarket market by scanning candlestick data bucketed at a chosen resolution. Returns all candle-to-candle moves exceeding the configured threshold, sorted by magnitude.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| condition_id | string | Hex condition ID of the market. Use Polymarket Markets (574) to find it. |
| token_id | string | Outcome token ID (side_a_token_id or side_b_token_id from Polymarket Markets for this condition). |
| outcome | string | Exact outcome label (e.g. 'Yes', 'No', 'Lakers') or 'ALL' for all outcomes. |
| resolution | string | Candle bucket size. Options: 1m, 5m, 15m, 1h, 4h, 1d |
| min_change_pct | string | Minimum absolute % price change to qualify as a jump |
| lookback_hours | string | Hours to scan back from now |
Polymarket Orderbook
agent_id 572Gets past order book snapshots for a specific `token_id` during a chosen time range.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| token_id | string | Token ID of the associated Market. |
| start_time | string | Filter after this timestamp |
| end_time | string | Filter before this timestamp |
Polymarket PnL
agent_id 569Retrieves realized profit and loss (PnL) for a given wallet address over a specified time range and aggregation interval. You may optionally filter results to a single market using `condition_id`. Unlike Polymarket’s dashboard, which displays unrealized PnL, this API reports **realized gains only**, calculated from confirmed sell transactions or fully settled (closed) markets.
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| granularity | string | Aggregation interval. Possible values are `1d` `3d` `1w` `1m` `all` |
| wallet | string | Wallet Id. |
| start_time | string | Filter after this timestamp |
| end_time | string | Filter before this timestamp |
Polymarket PnL Leaderboard
agent_id 579# **Leaderboard API**
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| wallet_address | string | Wallet address filter. Use `"ALL"` to return all wallets, or provide a specific address to filter results to that wallet. |
| leaderboard_period | string | Leaderboard time window. Allowed values: `1d`, `3d`, `7d`, `30d`. Each period has an independent ranking. |
Wallet Stats All Time
agent_id 586# **Wallet Stats All Time on Our data (\~9mo)**
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| wallet_address | string | Wallet address filter. This is mandetory. |
Heisenberg Leaderboard
agent_id 584# Heisenberg Leaderboard API
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| min_win_rate_15d | string | Minimum 15-day win rate (0–1) |
| max_win_rate_15d | string | Maximum 15-day win rate (0–1) |
| min_roi_15d | string | Minimum 15-day ROI |
| min_total_trades_15d | string | Minimum trades in 15 days |
| max_total_trades_15d | string | Maximum trades in 15 days |
| min_pnl_15d | string | Minimum realized PnL in USD over 15 days. Default: `"5000"` |
| sort_by | string | Sort metric. Default: `h_score`. Options: `h_score`, `roi`, `pnl`, `win_rate`, `trades`, `sharpe` |
Wallet 360
agent_id 581# Heisenberg Extensive Wallet Profile
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| proxy_wallet | string | Filter by wallet address. Required field. |
| window_days | string | The duration that the metrics are calculated over. Possible values are `"1"`, `"3"`, `"7"`, and `"15"`. Required field. |
Polymarket Market 360
agent_id 575# Market Quality & Structure Endpoint
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| condition_id | string | Ethereum condition ID for the market. This is optional. If you don't pass it, you get insights about all markets ranked by current_volume_24h in desc order. |
| min_volume_24h | string | Minimum 24-hour trading volume required for a market to be included. Use this to remove low-activity or noise markets. |
| min_liquidity_percentile | string | Minimum liquidity percentile relative to all active markets. Higher values indicate deeper books and better exit quality. |
| volume_trend | string | Filters markets by recent activity momentum. Allowed values: `Spiking`, `Normal`, `Declining`, `Dying Interest`, `No Trades`, `ALL`. |
| min_top1_wallet_pct | string | Minimum percentage of total exposure controlled by the largest wallet. Higher values may indicate whale dominance and potential fragility. |
| max_unique_traders_7d | string | Maximum number of unique traders over the last 7 days. Useful for detecting low-participation or weak-consensus markets. |
Social Intelligence
Social Pulse
agent_id 585## Social Pulse
Request body (JSON)
Parameters
| Name | Type | Description |
|---|---|---|
| keywords | string | Filter by keywords |
| hours_back | string | Filter by hours back |