> 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/candlesticks.md).

# Candlesticks

### Request Body (JSON)

```json
{
    "agent_id": 568,
    "params": {
        "token_id": "58639447033085668146701215689433308999613524738987821507545529427932862502961",
        "interval": "1m",
        "start_time": "1769219100",
        "end_time": "1769508420"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Available Filters

| Parameter    | Type                    | Description                    | Example                                                                           |
| ------------ | ----------------------- | ------------------------------ | --------------------------------------------------------------------------------- |
| `token_id`   | String                  | Token ID of the market outcome | `"58639447033085668146701215689433308999613524738987821507545529427932862502961"` |
| `interval`   | String                  | Candlestick interval           | `"5m"`                                                                            |
| `start_time` | String (Unix timestamp) | Filter after this timestamp    | `"1701388800"`                                                                    |
| `end_time`   | String (Unix timestamp) | Filter before this timestamp   | `"1704067199"`                                                                    |

### Supported Intervals

| Interval | Max Range |
| -------- | --------- |
| `1m`     | 7 days    |
| `5m`     | 15 days   |
| `15m`    | 30 days   |
| `1h`     | 90 days   |
| `4h`     | 180 days  |
| `1d`     | 360 days  |
| `1w`     | 360 days  |

<details>

<summary>Example Request <strong>(cURL)</strong></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": 568,
    "params": {
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "interval": "4h",
        "start_time": "1769910300",
        "end_time": "1770083100"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

| Field          | Type              | Description                        |
| -------------- | ----------------- | ---------------------------------- |
| `candle_time`  | String (ISO 8601) | Start time of the candlestick      |
| `open`         | String (Decimal)  | Opening price                      |
| `high`         | String (Decimal)  | Highest price                      |
| `low`          | String (Decimal)  | Lowest price                       |
| `close`        | String (Decimal)  | Closing price                      |
| `mean`         | String (Decimal)  | Average traded price               |
| `volume`       | String (Decimal)  | Total traded volume                |
| `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 (Decimal)  | Opening ask price                  |
| `ask_high`     | String (Decimal)  | Highest ask price                  |
| `ask_low`      | String (Decimal)  | Lowest ask price                   |
| `ask_close`    | String (Decimal)  | Closing ask price                  |
| `bid_open`     | String (Decimal)  | Open bid price                     |
| `bid_high`     | String (Decimal)  | Highest bid price                  |
| `bid_low`      | String (Decimal)  | Lowest bid price                   |
| `bid_close`    | String (Decimal)  | Closing bid price                  |

<details>

<summary>Example Response</summary>

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

</details>

***

### Notes

* Use shorter intervals (e.g., `1m`, `5m`) for detailed price movement
* Use longer intervals (e.g., `1h`, `1d`) for trend analysis
* Always match interval with an appropriate time range to avoid empty results
* Limit query duration using `start_time` and `end_time`
* Use pagination (`offset`) when retrieving large datasets