Falcon API

https://falcon-bot.gitbook.io
Admin
Unified API for prediction market data across platforms, providing real-time market data, trade...
Tokens:37,652
Snippets:241
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Pagination Parameters Example

Source: https://falcon-bot.gitbook.io/falcon-api/reference/core-concepts.md

Configure pagination to control the number of records returned and the starting point of the result set. The 'limit' parameter specifies the number of records per request, and 'offset' determines how many records to skip.

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

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

### Example Lifetime Performance Response

Source: https://falcon-bot.gitbook.io/falcon-api/traders/lifetime-performance.md

An example response from the Lifetime Performance API, showing detailed trading metrics for a given wallet 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
      }
    ]
  }
}
```

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

### Full Example Request Body

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

This is a complete example of a Falcon API request body, including all optional fields.

```json
{
  "agent_id": 555,
  "params": {
    "closed": "false",
    "market_slug": "bitcoin"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}
```

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

### Example Market Data Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/markets/polymarket-markets.md

This is an example of the JSON response received when querying for market data. It includes parameters used for the query and the detailed results for markets.

```bash
{
  "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"
      }
    ]
  }
}
```

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

### cURL Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Execute a POST request to the Falcon API using cURL. Replace 'YOUR_TOKEN' with your valid API key.

```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": 555, \
    "params": {"closed": "False"}, \
    "pagination": {"limit": 10, "offset": 0}, \
    "formatter_config": {"format_type": "raw"} \
  }'
```

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

### Example Response Body

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

This is an example of a Falcon API response body, showing the structure with pagination metadata and an empty data results array.

```json
{
  "timestamp": "2025-01-09T19:12:50Z",
  "params": {},
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": []
  }
}
```

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

### Python Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Make a POST request to the Falcon API using the Python requests library. Ensure you replace 'YOUR_TOKEN' with your actual API key.

```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": 555,
    "params": {"closed": "False"},
    "pagination": {"limit": 10, "offset": 0},
    "formatter_config": {"format_type": "raw"}
}

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

print(response.json())
```

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

### Example Polymarket Trades Response

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/polymarket-trades.md

This is an example of the JSON response you might receive when querying Polymarket trades. It includes trade details and pagination information.

```json
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "side": "BUY",
    "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,

```

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

### Example Candlestick Request (cURL)

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/candlesticks.md

Demonstrates how to make a cURL request to the API for candlestick data with specific parameters.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 568,
    "params": {
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "interval": "4h",
        "start_time": "1769910300",
        "end_time": "1770083100"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

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

### Kalshi Markets API Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/markets/kalshi-markets.md

This is an example of a successful response from the Kalshi markets API, detailing market information such as close time, ticker, status, and 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
      }
    ]
  }
}
```

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

### Orderbook API Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md

This is an example of a successful response from the Orderbook API. It includes pagination details and a list of order book snapshots, each containing asks and bids.

```json
{
  "timestamp": "",
  "params": {
    "end_time": "1770034843377",
    "start_time": "1769902905868",
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "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"
      },
      {
        "asks": "[{{\"size\": \"60\", \"price\": \"0.99\"}}, {\"size\": \"5\", \"price\": \"0.98\"}, {\"size\": \"714.29\", \"price\": \"0.93\"}, {\"size\": \"23.1\", \"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-02T09:53:57.168Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      },
      {
        "asks": "[{{\"size\": \"60\", \"price\": \"0.99\"}}, {\"size\": \"5\", \"price\": \"0.98\"}, {\"size\": \"714.29\", \"price\": \"0.93\"}, {\"size\": \"357\", \"price\": \"0.92\"}, {\"size\": \"23.1\", \"price\": \"0.91\"}]",

```

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

### JavaScript Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Send a POST request to the Falcon API using the Fetch API in JavaScript. Remember to replace 'YOUR_TOKEN' with your API key.

```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: 555,
      params: { closed: "False" },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" }
    })
  }
);

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

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

### Kalshi Trades API Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/kalshi-trades.md

This is an example of a successful response from the Kalshi trades API, showing trade details such as outcome, price, and timestamp.

```bash
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "side": "BUY",
    "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"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",

```

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

### Orderbook API Request Example (curl)

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md

This curl command demonstrates how to make a request to the Orderbook API. Ensure you replace 'Bearer ' with your actual authentication token.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ \
    "agent_id": 572, \
    "params": { \
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235", \
        "start_time": "1769902905868", \
        "end_time": "1770034843377" \
    }, \
    "formatter_config": { \
        "format_type": "raw" \
    } \
}'
```

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

### Example cURL Request for Lifetime Performance

Source: https://falcon-bot.gitbook.io/falcon-api/traders/lifetime-performance.md

A cURL command to make a request to the Lifetime Performance API. Ensure the Authorization header is correctly set.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ \
    "agent_id": 586, \
    "params": { \
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e" \
    }, \
    "pagination": { \
        "limit": 50, \
        "offset": 0 \
    }, \
    "formatter_config": { \
        "format_type": "raw" \
    } \
}'
```

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

### Candlestick Market Data Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/candlesticks.md

This example demonstrates the structure of a candlestick market data response. It includes parameters used for the request and the resulting candlestick data, such as open, high, low, close prices, volume, and trade count.

```bash
{
  "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": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "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",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 6,
        "volume": "135.97"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": null,
        "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",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 15,
        "volume": "1020.08"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "candle_time": "2026-02-01T08:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5095",
        "open": "0.5100",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 62,
        "volume": "1137.14"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "candle_time": "2026-02-01T12:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5046",
        "open": "0.5100",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 137,
        "volume": "2748.29"
      }
    ]
  }
}
```

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

### Example Market Insights API Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-intelligence/market-insights.md

This is an example of the JSON response structure for market insights. It includes parameters for filtering and pagination, along with a list of market data results.

```bash
{
  "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": "0x3488f31e6449f9803f99a8b5dd232c7ad883637f1c86e6953305a2ef19c77f20",
        "created_at": "2026-02-09T16:53:53.025942Z",
        "current_volume_24h": "33167793.852374",
        "current_volume_7d": "232174556.966617",
        "end_date": "2026-01-31T00:00:00Z",
        "liquidity_percentile": "99.99",
        "liquidity_tier": "Top 5%",
        "market_active": true,
        "market_closed": false,
        "peak_hour_trades": 0,
        "question": "US strikes Iran by February 28, 2026?",
        "slug": "us-strikes-iran-by-february-28-2026-227-967-547-688-589-491-592-418-452-924-384-915-464-672-196-157-993-596-269-535-381-391-471-256-988-997-296-225-762-973-292-827-345-182-558-215-794-879-189-761",
        "snapshot_time": "2026-03-15T18:00:00.009086Z",
        "top1_wallet_pct": "0.00",
        "top3_wallet_pct": "0.00",
        "trade_concentration_flag": false,
        "trades_per_hour_avg": "0.00",
        "unique_traders_7d": 0,
        "updated_at": "2026-03-15T18:00:00.009086Z",
        "volume_trend": "No Trades",
        "whale_control_flag": false
      },
      {
        "condition_id": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38",
        "created_at": "2026-02-09T16:53:53.025942Z",
        "current_volume_24h": "16256726.751000",
        "current_volume_7d": "113011287.577520",
        "end_date": "2026-03-18T00:00:00Z",
        "liquidity_percentile": "100.00",
        "liquidity_tier": "Top 5%",
        "market_active": true,
        "market_closed": false,
        "peak_hour_trades": 234,
        "question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?",
        "slug": "will-the-fed-increase-interest-rates-by-25-bps-after-the-march-2026-meeting",
        "snapshot_time": "2026-03-15T18:00:00.009086Z",
        "top1_wallet_pct": "17.92",
        "top3_wallet_pct": "43.57",
        "trade_concentration_flag": false,
        "trades_per_hour_avg": "74.75",
        "unique_traders_7d": 3990
      }
    ]
  }
}
```

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

### Example Request Body for Retrieve

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

This JSON object defines the parameters for a data retrieval request, including agent ID, custom parameters, pagination, and formatting configuration.

```json
{
  "agent_id": 555,
  "params": {
    "closed": "False"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}
```

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

### cURL Request for Top Traders

Source: https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md

Example cURL command to fetch top trader data. Ensure to replace the placeholder bearer token with your actual API key.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ \
    "agent_id": 579, \
    "params": { \
        "wallet_address": "ALL", \
        "leaderboard_period": "1d" \
    }, \
    "pagination": { \
        "limit": 50, \
        "offset": 0 \
    }, \
    "formatter_config": { \
        "format_type": "raw" \
    } \
}'
```

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

### Social Pulse API cURL Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/market-intelligence/social-pulse.md

This cURL command demonstrates how to make a request to the Social Pulse API, including authentication and the JSON request body.

```bash
curl --location '/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ \
    "agent_id": 585, \
    "params": { \
        "keywords": "{Trump,election,MAGA}", \
        "hours_back": "12" \
    }, \
    "formatter_config": { \
        "format_type": "raw" \
    }' \
}'
```

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

### Ask a Question via Documentation Index

Source: https://falcon-bot.gitbook.io/falcon-api/llms.txt

Use this GET request to query the documentation index with a specific question and an optional broader goal. The response includes a direct answer and relevant sources.

```http
GET https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md?ask=<question>&goal=<end_goal>
```

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

### Get Candlestick Data

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/candlesticks.md

Fetches historical candlestick data for a specified token. You can filter by start and end times and specify the interval for the candlesticks.

```APIDOC
## GET /market-data/candlesticks

### Description
Retrieves historical candlestick data for a specified token, including open, high, low, close prices, volume, trade counts, and bid/ask information. Allows filtering by time range and interval.

### Method
GET

### Endpoint
`/market-data/candlesticks`

### Parameters
#### Query Parameters
- **token_id** (string) - Required - The unique identifier for the token.
- **start_time** (string) - Required - The start timestamp for the data retrieval (Unix timestamp or ISO 8601 format).
- **end_time** (string) - Required - The end timestamp for the data retrieval (Unix timestamp or ISO 8601 format).
- **interval** (string) - Required - The interval for the candlesticks (e.g., "1h", "4h", "1d").

### Response
#### Success Response (200)
- **candle_time** (string) - Start time of the candlestick (ISO 8601).
- **open** (string) - Opening price (Decimal).
- **high** (string) - Highest price (Decimal).
- **low** (string) - Lowest price (Decimal).
- **close** (string) - Closing price (Decimal).
- **mean** (string) - Average traded price (Decimal).
- **volume** (string) - Total traded volume (Decimal).
- **trade_count** (integer) - Number of trades.
- **outcome** (string) - Market outcome (e.g., "Yes", "No").
- **condition_id** (string) - Ethereum condition ID.
- **token_id** (string) - Token identifier.
- **ask_open** (string) - Opening ask price (Decimal).
- **ask_high** (string) - Highest ask price (Decimal).
- **ask_low** (string) - Lowest ask price (Decimal).
- **ask_close** (string) - Closing ask price (Decimal).
- **bid_open** (string) - Open bid price (Decimal).
- **bid_high** (string) - Highest bid price (Decimal).
- **bid_low** (string) - Lowest bid price (Decimal).
- **bid_close** (string) - Closing bid price (Decimal).

#### Response Example
```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": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "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",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 6,
        "volume": "135.97"
      }
    ]
  }
}
```
```

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

### Get Orderbook Data

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md

Fetches order book snapshots for a given token ID between specified start and end times. The request body includes agent ID, parameters for filtering (token ID, start time, end time), and formatter configuration.

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

### Description
Retrieves historical order book data for a specified token ID within a given time range. The response includes timestamps, token IDs, and lists of ask and bid orders.

### 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.
- **params** (object) - Required - Parameters for the query.
  - **token_id** (string) - Required - Token ID of the market outcome.
  - **start_time** (string) - Optional - Snapshots after this timestamp (inclusive, Unix ms timestamp).
  - **end_time** (string) - Optional - Snapshots before this timestamp (inclusive, Unix ms timestamp).
- **formatter_config** (object) - Required - Configuration for formatting the output.
  - **format_type** (string) - Required - The type of format, e.g., "raw".

### Request Example
```json
{
    "agent_id": 572,
    "params": {
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        "start_time": "1769902905868",
        "end_time": "1770034843377"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

### Response
#### Success Response (200)
- **timestamp** (string) - Timestamp of the order book snapshot (ISO 8601).
- **token_id** (string) - Token identifier.
- **asks** (array) - List of ask orders (price, size).
- **bids** (array) - List of bid orders (price, size).

#### Response Example
```json
{
  "timestamp": "2026-02-02T12:01:20.885Z",
  "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
  "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"}
  ]
}
```
```

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

### Request pagination Field Example

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

The pagination field is optional and controls the number of records returned and the result offset. It includes limit for the maximum number of records and offset for the starting index.

```json
"pagination": {
  "limit": 10,
  "offset": 0
}
```

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

### Time Filter Parameters Example

Source: https://falcon-bot.gitbook.io/falcon-api/reference/core-concepts.md

Apply time filters to narrow down results by specifying a start and end time using Unix timestamps represented as strings. This is useful for querying data within a specific historical range.

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

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

### cURL Request Example for Falcon Wallet 360

Source: https://falcon-bot.gitbook.io/falcon-api/market-intelligence/falcon-wallet-360.md

This cURL command demonstrates how to make a request to the Falcon Wallet 360 API. Ensure your Authorization token is correctly set.

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

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

### Example Top Traders Response

Source: https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md

Sample JSON response structure for top trader data. Includes ranking, PnL, ROI, win rate, and other performance metrics for each trader.

```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",

```
Tokens:
Raw