> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tulipai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Candles

> Query chronological OHLCV buckets for a Tulip model market.

```http theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
GET /v1/markets/{modelId}/candles?interval=300&from=1784037600&limit=500
```

## Parameters

| Parameter  | Required | Description                                                       |
| ---------- | -------- | ----------------------------------------------------------------- |
| `modelId`  | Yes      | Canonical 32-byte ModelID.                                        |
| `interval` | Yes      | Bucket size: `60`, `300`, `900`, or `3600` seconds.               |
| `from`     | No       | Inclusive Unix timestamp for the first bucket.                    |
| `limit`    | No       | Maximum number of chronological buckets, up to the service limit. |

## Response

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "modelId": "0x...",
  "interval": 300,
  "candles": [
    {
      "time": 1784037600,
      "open": "0.00000121",
      "high": "0.00000129",
      "low": "0.00000119",
      "close": "0.00000124",
      "volumeUsdG": "812.44",
      "swaps": 17
    }
  ]
}
```

Candles are derived only from swaps within their exact time bucket. The first trade sets the open, the final trade sets the close, and high and low are the maximum and minimum indexed execution prices.

## Real-time charting

Poll the current interval while the page is visible. Merge updates by `time` instead of appending every response as a new candle. A candle's timestamp is the start of its interval, not the arrival time of the API response.

When switching intervals, request a fresh series rather than aggregating already rounded client data.