### Missing Authorization header

Source: https://polygunllc.mintlify.app/reference/error-handling

Wrong example omits the Authorization header; correct example includes it. Every request requires the Bearer token header.

```bash
curl -X POST ... -d '{"agent_id": 574}'
```

```bash
curl -X POST ... -H "Authorization: Bearer YOUR_TOKEN" -d '...'
```

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

### Python Example Request to Market 360 Endpoint

Source: https://polygunllc.mintlify.app/market-intelligence/market-360

Use this Python script to call the Market 360 endpoint. It uses the requests library and prints the response JSON. Ensure you have the requests library installed.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 575,
    "params": {
        "condition_id": "ALL",
        "min_volume_24h": "0",
        "min_liquidity_percentile": "0",
        "volume_trend": "ALL",
        "min_top1_wallet_pct": "0",
        "max_unique_traders_7d": "0"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

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

### Search Kalshi Markets via cURL

Source: https://polygunllc.mintlify.app/market-data/kalshi-markets

Example request to search markets using the cURL command-line tool.

```bash
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 565,
  "params": {
    "ticker": "KXSOL15M-26MAR180800-00",
    "event_ticker": "KXSOL15M-26MAR180800",
    "title": "SOL price",
    "status": "finalized",
    "close_time_min": "1773589812",
    "close_time_max": "1774021812"
  },
  "pagination": { "limit": 10, "offset": 0 },
  "formatter_config": { "format_type": "raw" }
}'
```

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

### Wallet 360 POST /v2/semantic/retrieve/parameterized example (cURL, Python, JavaScript)

Source: https://polygunllc.mintlify.app/market-intelligence/wallet-360

Example request to the Wallet 360 endpoint (agent_id 581) using cURL, Python, and JavaScript. All three languages send the same payload with proxy_wallet and window_days parameters, and require a Bearer token. The response is printed or parsed as JSON.

```bash
curl --request POST \
    --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "agent_id": 581,
    "params": {
      "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
      "window_days": "3"
    },
    "pagination": {
      "limit": 10,
      "offset": 0
    },
    "formatter_config": {
      "format_type": "raw"
    }
  }'
```

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 581,
    "params": {
        "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
        "window_days": "3"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

```javascript
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 581,
  "params": {
    "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
    "window_days": "3"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```

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

### Example JSON Response from Polymarket Markets API

Source: https://polygunllc.mintlify.app/market-data/polymarket-markets

Example response from the Polymarket markets endpoint. Shows pagination parameters and a market result with fields like condition_id, question, slug, end_date, volume, liquidity, and token IDs.

```json
{
  "timestamp": "",
  "params": {
    "market_slug": "nba-",
    "min_volume": "10000",
    "closed": "False",
    "end_date_min": "1600000000",
    "end_date_max": "2200000000"
  },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0xabc123def456...",
        "question": "Cavaliers vs. Celtics",
        "slug": "nba-cle-bos-2026-04-11",
        "end_date": "2026-04-12T00:00:00Z",
        "volume": "523890.44",
        "liquidity": "842190.55",
        "closed": false,
        "side_a_token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        "side_b_token_id": "98765432109876543210",
        "outcome_a": "Cavaliers",
        "outcome_b": "Celtics",
        "current_price_a": "0.4200",
        "current_price_b": "0.5800"
      }
    ]
  }
}
```

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

### Search Kalshi Markets via Python

Source: https://polygunllc.mintlify.app/market-data/kalshi-markets

Example request to search markets using the Python requests library.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 565,
        "params": {
            "ticker": "KXSOL15M-26MAR180800-00",
            "event_ticker": "KXSOL15M-26MAR180800",
            "title": "SOL price",
            "status": "finalized",
            "close_time_min": "1773589812",
            "close_time_max": "1774021812",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())
```

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

### Leaderboard API Example Response (JSON)

Source: https://polygunllc.mintlify.app/market-intelligence/leaderboard

Example JSON response from the leaderboard endpoint. Shows the response structure with params, pagination, data.results array, and request_id. The result includes trader metrics such as roi_pct_15d, win_rate_pct_15d, sharpe_ratio_15d, total_trades_15d, and trajectory.

```json
{
  "timestamp": "2025-01-15T12:00:00Z",
  "params": {
    "min_win_rate_15d": "0.45",
    "max_win_rate_15d": "0.95",
    "min_roi_15d": "0",
    "min_total_trades_15d": "50",
    "max_total_trades_15d": "100000",
    "min_pnl_15d": "5000",
    "sort_by": "roi"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "leaderboard_rank": 1,
        "wallet": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
        "tier": "A",
        "f_score": 87.4,
        "roi_pct_15d": 41.5,
        "win_rate_pct_15d": 0.72,
        "sharpe_ratio_15d": 1.25,
        "total_trades_15d": 120,
        "markets_traded_15d": 18,
        "total_pnl_15d": 12500.5,
        "total_volume_15d": 3600711.99,
        "trajectory": "Improving"
      }
    ]
  },
  "request_id": "req_abc123"
}
```

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

### Passing numbers instead of strings in params

Source: https://polygunllc.mintlify.app/reference/error-handling

Wrong example uses a numeric value for min_volume; correct example uses a string. All param values must be strings, even numeric ones.

```json
"min_volume": 1000
```

```json
"min_volume": "1000"
```

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

### Kalshi Trades API Example Response

Source: https://polygunllc.mintlify.app/trade-data/kalshi-trades

Example response from the Kalshi trades endpoint. Shows two trade records with fields like count, created_time, no_price, taker_side, ticker, trade_id, and yes_price. The pagination object indicates has_more is true, suggesting additional results are available.

```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
      }
    ]
  }
}
```

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

### Response format example

Source: https://polygunllc.mintlify.app/getting-started/quickstart

Shows the consistent structure returned by all endpoints, including timestamp, params, pagination, data, and request_id.

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

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

### Orderbook snapshots example response

Source: https://polygunllc.mintlify.app/market-data/orderbook

Example response for the orderbook snapshots endpoint. Shows the structure with timestamp, params, pagination, and data.results array. Each result contains token_id, ISO 8601 timestamp, best_bid, best_ask, spread, bid_depth, and ask_depth as decimal strings.

```json
{
  "timestamp": "",
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        "timestamp": "2026-04-10T18:00:00Z",
        "best_bid": "0.5750",
        "best_ask": "0.5850",
        "spread": "0.0100",
        "bid_depth": "125400.30",
        "ask_depth": "98200.15"
      }
    ]
  }
}
```

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

### API Request in JavaScript

Source: https://polygunllc.mintlify.app/introduction/api-integration

Example of using the fetch API to send a POST request with authentication and payload parameters.

```javascript
const response = await fetch(
  "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agent_id: 574,
      params: { closed: "False" },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" }
    })
  }
);

const data = await response.json();
console.log(data);
```

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

### Search Kalshi Markets via JavaScript

Source: https://polygunllc.mintlify.app/market-data/kalshi-markets

Example request to search markets using the native JavaScript fetch API.

```javascript
const response = await fetch(
  "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: 565,
      params: {
        ticker: "KXSOL15M-26MAR180800-00",
        event_ticker: "KXSOL15M-26MAR180800",
        title: "SOL price",
        status: "finalized",
        close_time_min: "1773589812",
        close_time_max: "1774021812",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);
```

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

### Retrieve Lifetime Performance via Python

Source: https://polygunllc.mintlify.app/traders/lifetime-performance

Example request using the Python requests library to fetch lifetime performance data.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 586,
    "params": {
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

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

### API Request with cURL

Source: https://polygunllc.mintlify.app/introduction/api-integration

Example of using cURL to send a POST request with authentication and payload parameters.

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

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

### API Request in Python

Source: https://polygunllc.mintlify.app/introduction/api-integration

Example of using the requests library to send a POST request with authentication and payload parameters.

```python
import requests

url = "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": 574,
    "params": {"closed": "False"},
    "pagination": {"limit": 10, "offset": 0},
    "formatter_config": {"format_type": "raw"}
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

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

### Retrieve Kalshi Trades via Python

Source: https://polygunllc.mintlify.app/trade-data/kalshi-trades

Example request to the Kalshi Trades endpoint using the Python requests library.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 573,
        "params": {
            "ticker": "KXSOL15M-26MAR180730-30",
            "start_time": "1773589812",
            "end_time": "1774021812",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())
```

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

### Python Request for Price Jumps

Source: https://polygunllc.mintlify.app/market-data/polymarket-price-jumps

Example Python code using the requests library to query the Price Jumps endpoint.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 596,
        "params": {
            "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
            "resolution": "15m",
            "min_change_pct": "10",
            "lookback_hours": "24",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())
```

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

### Python Request for Profit & Loss

Source: https://polygunllc.mintlify.app/traders/profit-and-loss

Example using the requests library to fetch PnL data. Replace YOUR_TOKEN with your actual Bearer token.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 569,
        "params": {
            "granularity": "1d",
            "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
            "start_time": "2026-02-10",
            "end_time": "2026-02-28",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())
```

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

### Request Polymarket Trades via Python

Source: https://polygunllc.mintlify.app/trade-data/polymarket-trades

Example request to the Polymarket trades endpoint using the Python requests library.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

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

### cURL Request for Price Jumps

Source: https://polygunllc.mintlify.app/market-data/polymarket-price-jumps

Example cURL command to retrieve price jumps. Replace YOUR_TOKEN with your actual Bearer token.

```bash
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 596,
  "params": {
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
    "resolution": "15m",
    "min_change_pct": "10",
    "lookback_hours": "24"
  },
  "pagination": { "limit": 10, "offset": 0 },
  "formatter_config": { "format_type": "raw" }
}'
```

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

### POST /api/v2/semantic/retrieve/parameterized

Source: https://polygunllc.mintlify.app/market-data/fscore-leaderboards

Example request for the parameterized semantic retrieval endpoint, showing how to query leaderboard data with filters and pagination.

```APIDOC
## POST /api/v2/semantic/retrieve/parameterized

### Description
Retrieves parameterized semantic data for a given agent based on specified filters and pagination. This endpoint allows users to query leaderboard data with custom parameters.

### Method
POST

### Endpoint
https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized

### Parameters
#### Request Body
- **agent_id** (integer) - Required - The ID of the agent for which to retrieve data.
- **params** (object) - Required - Object containing filter parameters.
  - **min_win_rate_15d** (string) - Optional - Minimum win rate over the last 15 days.
  - **max_win_rate_15d** (string) - Optional - Maximum win rate over the last 15 days.
  - **min_roi_15d** (string) - Optional - Minimum ROI over the last 15 days.
  - **min_total_trades_15d** (string) - Optional - Minimum total trades over the last 15 days.
  - **max_total_trades_15d** (string) - Optional - Maximum total trades over the last 15 days.
  - **min_pnl_15d** (string) - Optional - Minimum PnL over the last 15 days.
  - **sort_by** (string) - Optional - Field to sort results by (e.g., "roi").
- **pagination** (object) - Required - Pagination settings.
  - **limit** (integer) - Required - Maximum number of results to return.
  - **offset** (integer) - Required - Number of results to skip.
- **formatter_config** (object) - Required - Configuration for response formatting.
  - **format_type** (string) - Required - Format type for the response (e.g., "raw").

### Request Example
```json
{
  "agent_id": 584,
  "params": {
    "min_win_rate_15d": "0.45",
    "max_win_rate_15d": "0.95",
    "min_roi_15d": "0",
    "min_total_trades_15d": "50",
    "max_total_trades_15d": "100000",
    "min_pnl_15d": "5000",
    "sort_by": "roi"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}
```

### Response
#### Success Response (200)
- Response body contains the retrieved data in the format specified by `formatter_config`.

#### Response Example
(No explicit response example provided in the source.)
```

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

### Retrieve Lifetime Performance via JavaScript

Source: https://polygunllc.mintlify.app/traders/lifetime-performance

Example request using the JavaScript fetch API to retrieve lifetime performance data.

```javascript
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 586,
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```

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

### Apply Time Filters

Source: https://polygunllc.mintlify.app/reference/core-concepts

Example JSON structure for passing start and end time filters as Unix timestamp strings within the params object.

```json
{
  "params": {
    "start_time": "1703719954",
    "end_time": "1704067199"
  }
}
```

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

### Node.js WebSocket client implementation

Source: https://polygunllc.mintlify.app/reference/websocket

A complete Node.js example using the 'ws' library to connect, authenticate, subscribe to trades, and handle incoming messages or errors.

```javascript
const WebSocket = require('ws');

const SUBSCRIBE = {
  action: 'subscribe',
  subscriptions: [
    {
      type: 'polymarket.trade',
      filters: { slug: 'btc-updown-5m-1779889800' },
    },
  ],
};

function connect() {
  const ws = new WebSocket('wss://ripple.heisenberg.so/ws', {
    headers: { Authorization: 'Bearer ' + process.env.FALCON_API_TOKEN },
  });

  ws.on('open', () => {
    ws.send(JSON.stringify(SUBSCRIBE));
  });

  ws.on('message', (raw) => {
    const msg = JSON.parse(raw);

    if (msg.action === 'subscribed') {
      console.log('subscribed:', msg.subscriptions.map((s) => s.id));
      return;
    }
    if (msg.action === 'error' || msg.action === 'rate_limit') {
      console.warn(msg.action, msg.message);
      return;
    }
    if (msg.type === 'polymarket.trade') {
      const t = msg.data;
      console.log(t.side, t.size, '@', t.price, '-', t.slug);
    }
  });

  ws.on('close', (code) => {
    if (code === 4001) setTimeout(connect, 1000);
  });
}

connect();
```

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

### Using an invalid agent_id

Source: https://polygunllc.mintlify.app/reference/error-handling

Wrong example uses agent_id 999; correct example uses 574. Check the API Reference sidebar for valid endpoint IDs.

```json
"agent_id": 999
```

```json
"agent_id": 574
```

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

### Pagination request examples with limit and offset

Source: https://polygunllc.mintlify.app/reference/api-structure

Shows three sequential pagination requests. Check has_more in the response and increment offset by limit (50) for each subsequent page.

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

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

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

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

### Falcon API Response JSON Example

Source: https://polygunllc.mintlify.app/reference/api-structure

Example JSON response from a Falcon API endpoint. Shows the structure with timestamp, params echo, pagination object, data.results array, and request_id. Note that params values are strings and pagination.has_more indicates more results.

```json
{
  "timestamp": "2026-04-06T12:00:00Z",     // Server timestamp
  "params": {                                // Echo of your request params
    "min_volume": "1000",
    "closed": "False"
  },
  "pagination": {
    "limit": 10,                             // Your requested limit
    "offset": 0,                             // Your requested offset
    "has_more": true                         // More results available?
  },
  "data": {
    "results": [                             // Array of result objects
      { ... },
      { ... }
    ]
  },
  "request_id": "abc-123-def"               // Unique request identifier
}
```

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

### WebSocket Connection and Subscription (Node.js)

Source: https://polygunllc.mintlify.app/reference/websocket

Example Node.js client using the ws library to connect to the WebSocket gateway, authenticate with a bearer token, subscribe to polymarket.trade events, and handle incoming messages.

```APIDOC
## WebSocket Connection and Subscription

### Description
Connects to the WebSocket gateway at wss://ripple.heisenberg.so/ws, authenticates with a bearer token, and subscribes to polymarket.trade events with a filter on slug.

### Connection
- **URL**: wss://ripple.heisenberg.so/ws
- **Authentication**: Bearer token in the Authorization header (required)

### Subscribe Message
```json
{
  "action": "subscribe",
  "subscriptions": [
    {
      "type": "polymarket.trade",
      "filters": { "slug": "btc-updown-5m-1779889800" }
    }
  ]
}
```

### Message Handling
- **subscribed**: Logs subscription IDs from msg.subscriptions
- **error**: Logs warning with msg.action and msg.message
- **rate_limit**: Logs warning with msg.action and msg.message
- **polymarket.trade**: Logs trade data (side, size, price, slug)

### Reconnection
- On close code 4001, reconnects after 1 second.

### Error Message Format
Server sends error messages with the following structure:
```json
{
  "action": "error",
  "types": ["polymarket.does_not_exist"],
  "message": "unauthorized: polymarket.does_not_exist"
}
```

### Authentication Failure
- Connection upgrade returns standard HTTP 401 for invalid tokens.
```

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

### Wallet 360 API Response Example

Source: https://polygunllc.mintlify.app/market-intelligence/wallet-360

A sample JSON response containing performance data, risk metrics, and trade history for a proxy wallet. The response includes pagination metadata and a list of results with detailed financial indicators.

```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",
        "flagged_metrics": "{position_size_volatility}",
        "gain_to_pain_ratio": -0.776,
        "last_active": "2026-03-14T23:59:59.999999Z",
        "losing_trades": 1452,
        "market_concentration_ratio": 0.0507,
        "markets_traded": 2704,
        "max_drawdown": 0.1003,
        "max_position_pct": 0.4194,
        "num_markets_traded": 2704,
        "perfect_entry_count": 772,
        "perfect_exit_count": 0,
        "perfect_timing_flag": false,
        "perfect_timing_score": 0.172,
        "performance_by_category": "W3sicG5sIjogMjI3MzMuMjIsICJ0cmFkZXMiOiA1NiwgImNhdGVnb3J5IjogIlNjaWVuY2UgJiBUZWNoIn0sIHsicG5sIjogMTY5MzcuNDYsICJ0cmFkZXMiOiAyMTMsICJjYXRlZ29yeSI6ICJXb3JsZCBFdmVudHMifSwgeyJwbmwiOiAtODU5Mi43OSwgInRyYWRlcyI6IDUzODMsICJjYXRlZ29yeSI6ICJPdGhlciJ9LCB7InBubCI6IC00MjYxNTQuMzgsICJ0cmFkZXMiOiA4NjMsICJjYXRlZ29yeSI6ICJTcG9ydHMifV0=",
        "performance_trend": "improving",
        "position_size_consistency": 0,
        "position_size_volatility_flag": true,
        "profit_factor": 0.8539
```

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

### Configure Pagination Request

Source: https://polygunllc.mintlify.app/reference/core-concepts

Example JSON structure for a pagination request fetching page 3 with 25 results per page, resulting in an offset of 50.

```json
{
  "pagination": {
    "limit": 25,
    "offset": 50
  }
}
```

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

### Error response for non-filterable field

Source: https://polygunllc.mintlify.app/reference/websocket

Example of an error message returned when attempting to filter on a field that does not support filtering.

```json
{
  "action": "error",
  "types": ["polymarket.trade"],
  "message": "non-filterable keys for polymarket.trade: not_a_real_field"
}
```

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

### Error response for missing type

Source: https://polygunllc.mintlify.app/reference/websocket

Example of an error message returned when requesting a type not included in the current plan.

```json
{
  "action": "error",
  "types": ["polymarket.does_not_exist"],
  "message": "unauthorized: polymarket.does_not_exist"
}
```

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

### Example JSON request body

Source: https://polygunllc.mintlify.app/reference/api-structure

Shows the unified request structure. agent_id is required; params, pagination, and formatter_config are optional. The comment notes that 'raw' returns structured JSON.

```json
{
  "agent_id": 574,              // Required — selects the endpoint
  "params": {                   // Optional — filter parameters
    "min_volume": "1000",
    "closed": "False"
  },
  "pagination": {               // Optional — control result size
    "limit": 10,                // 1–200, default varies by endpoint
    "offset": 0                 // Skip N results for pagination
  },
  "formatter_config": {         // Optional — response formatting
    "format_type": "raw"        // "raw" returns structured JSON
  }
}
```

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

### Batch Market Resolution API Request (Python)

Source: https://polygunllc.mintlify.app/composite-workflows/batch-market-resolution

Python example using requests.post to the same endpoint with Bearer token and JSON payload. Prints the response JSON. Requires YOUR_TOKEN placeholder.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 0,
    "params": {
        "condition_ids": "0xabc123...,0xdef456..."
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

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

### JavaScript Request for PnL Leaderboard

Source: https://polygunllc.mintlify.app/market-intelligence/leaderboard

Example JavaScript code using the fetch API to retrieve the PnL leaderboard.

```javascript
const response = await fetch(
  "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: 579,
      params: {
        wallet_address: "ALL",
        leaderboard_period: "1d",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);
```

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

### Python Request for PnL Leaderboard

Source: https://polygunllc.mintlify.app/market-intelligence/leaderboard

Example Python code using the requests library to fetch the PnL leaderboard.

```python
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 579,
        "params": {
            "wallet_address": "ALL",
            "leaderboard_period": "1d",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())
```

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

### Calculate 24-Hour Time Range

Source: https://polygunllc.mintlify.app/reference/core-concepts

Formula to calculate the start time for a query covering the last 24 hours.

```text
start_time = current_time - 86400
```

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

### Example JSON Response from Kalshi Markets API

Source: https://polygunllc.mintlify.app/market-data/kalshi-markets

Shows the JSON structure returned by the Kalshi Markets API for a market query. Includes params, pagination, and a results array with market details. The response fields are documented in the table below.

```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
      }
    ]
  }
}
```

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

### Connect and Subscribe with Python websockets

Source: https://polygunllc.mintlify.app/reference/websocket

Establishes a WebSocket connection using the websockets library and subscribes to polymarket.trade events. Requires the FALCON_API_TOKEN environment variable for authentication.

```python
import asyncio, json, os
import websockets

async def main():
    url = "wss://ripple.heisenberg.so/ws"
    headers = {"Authorization": f"Bearer {os.environ['FALCON_API_TOKEN']}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "action": "subscribe",
            "subscriptions": [
                {"type": "polymarket.trade", "filters": {"slug": "btc-updown-5m-1779889800"}},
            ],
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if "action" in msg:              # subscribed / error / rate_limit
                print(msg)
            elif msg.get("type") == "polymarket.trade":
                t = msg["data"]
                print(t["side"], t["size"], "@", t["price"], "-", t["slug"])

asyncio.run(main())
```