> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md).

# Orderbook

### Request Body (JSON)

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

***

### Available Filters

| Parameter    | Type                       | Description                                 | Example           |
| ------------ | -------------------------- | ------------------------------------------- | ----------------- |
| `token_id`   | String                     | Token ID of the market outcome              | `"123456..."`     |
| `start_time` | String (Unix ms timestamp) | Snapshots after this timestamp (inclusive)  | `"1700000000000"` |
| `end_time`   | String (Unix ms timestamp) | Snapshots before this timestamp (inclusive) | `"1705000000000"` |

<details>

<summary>Example Request (curl)</summary>

```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"
    }
}'
```

</details>

### Response Fields

| Field       | Type              | Description                          |
| ----------- | ----------------- | ------------------------------------ |
| `timestamp` | String (ISO 8601) | Timestamp of the order book snapshot |
| `token_id`  | String            | Token identifier                     |
| `asks`      | Array             | List of ask orders (price, size)     |
| `bids`      | Array             | List of bid orders (price, size)     |

<details>

<summary>Example Response</summary>

```bash
{
  "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"20.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:46:37.004Z",
        "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"20.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:37:53.29Z",
        "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"20.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:20:49.337Z",
        "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"20.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:12:06.611Z",
        "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"20.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:03:42.168Z",
        "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:02:00.593Z",
        "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\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"15\", \"price\": \"0.03\"}, {\"size\": \"5.63\", \"price\": \"0.04\"}, {\"size\": \"12\", \"price\": \"0.09\"}, {\"size\": \"12\", \"price\": \"0.19\"}, {\"size\": \"200\", \"price\": \"0.28\"}, {\"size\": \"29.48\", \"price\": \"0.29\"}]",
        "timestamp": "2026-02-02T05:12:34.61Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      }
    ]
  }
}
```

</details>

***

### Notes

* Use a **narrow time range** between `start_time` and `end_time` to avoid extremely large responses when retrieving historical orderbook data.
* Query a **specific `token_id`** to ensure the orderbook snapshots correspond to the exact market outcome you want.
* Use **pagination (`limit` and `offset`)** when retrieving large datasets to efficiently iterate through historical snapshots.
* Keep `start_time` and `end_time` values as **Unix timestamps in milliseconds (strings)** to ensure proper filtering.
* When analyzing liquidity changes, request **multiple sequential time ranges** instead of a single large query to improve reliability and performance.
* If the response includes `has_more`, continue fetching with an updated `offset` to retrieve the remaining snapshots.
* For orderbook analysis, compare **bids and asks across consecutive snapshots** to observe liquidity shifts, spread changes, and market pressure.