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

# candleSnapshot: Fetch Historical OHLCV Candle Data

> Query historical OHLCV candle data for a contract over any time range, with support for minute, hour, day, week, and month intervals.

The `candleSnapshot` query returns historical OHLCV (open/high/low/close/volume) candles for a contract over a specified time range. Candles are returned in ascending time order. The last candle in the response may represent the current open (in-progress) bar, indicated by `"closed": false` — at most one such bar will appear, always at the end of the array.

<Note>
  For real-time updates, subscribe to the WebSocket `candle` channel after loading historical data with this endpoint. The WebSocket push will keep your local candle state current without repeated polling.
</Note>

## Request

```json theme={"system"}
{
  "type": "candleSnapshot",
  "asset": "1",
  "interval": "1m",
  "startTime": 1782205172447,
  "endTime": 1782291572447
}
```

<ParamField body="type" type="string" required>
  Must be `"candleSnapshot"`.
</ParamField>

<ParamField body="asset" type="string" required>
  The contract ID to fetch candles for, expressed as a decimal string (e.g. `"1"`). Use the `contractId` from `configs`.
</ParamField>

<ParamField body="interval" type="string" required>
  Candle interval. See the supported intervals table below for all valid values.
</ParamField>

<ParamField body="startTime" type="integer">
  Start of the time range as Unix milliseconds (inclusive). Defaults to `0` (earliest available data) if omitted.
</ParamField>

<ParamField body="endTime" type="integer">
  End of the time range as Unix milliseconds (inclusive). Defaults to max int64 (latest available data) if omitted.
</ParamField>

## Supported Intervals

| Category | Intervals                      |
| -------- | ------------------------------ |
| Minutes  | `1m`, `3m`, `5m`, `15m`, `30m` |
| Hours    | `1h`, `2h`, `4h`, `8h`, `12h`  |
| Day+     | `1d`, `3d`, `1w`, `1M`         |

<Warning>
  Passing an interval string not listed above returns HTTP 400 `BAD_REQUEST`. Validate the interval value in your client before sending the request.
</Warning>

<Note>
  If the `asset` does not exist or no trades have occurred in the requested time range, the response returns `"candles": []` with HTTP 200. This is not an error — simply an empty result.
</Note>

## Response

```json theme={"system"}
{
  "type": "candleSnapshot",
  "asset": "1",
  "interval": "1m",
  "candles": [
    {
      "s": "1",
      "i": "1m",
      "t": 1782270780000,
      "T": 1782270840000,
      "o": "100",
      "c": "100",
      "h": "100",
      "l": "100",
      "v": "4",
      "n": 1,
      "closed": true
    },
    {
      "s": "1",
      "i": "1m",
      "t": 1782279660000,
      "T": 1782279720000,
      "o": "110",
      "c": "70",
      "h": "110",
      "l": "70",
      "v": "15",
      "n": 6,
      "closed": false
    }
  ]
}
```

### Candle Fields

<ResponseField name="s" type="string">
  Contract ID (same as `asset`).
</ResponseField>

<ResponseField name="i" type="string">
  Interval identifier.
</ResponseField>

<ResponseField name="t" type="integer">
  Bucket open time in Unix milliseconds (inclusive). This is the start of the candle period.
</ResponseField>

<ResponseField name="T" type="integer">
  Bucket close time in Unix milliseconds (exclusive). The next candle's `t` equals this value.
</ResponseField>

<ResponseField name="o" type="string">
  Opening price of the candle (raw integer string). Divide by `10^priceScale` from `configs` to get the display value.
</ResponseField>

<ResponseField name="h" type="string">
  Highest price traded during the candle period (raw integer string).
</ResponseField>

<ResponseField name="l" type="string">
  Lowest price traded during the candle period (raw integer string).
</ResponseField>

<ResponseField name="c" type="string">
  Closing price of the candle (raw integer string). For an open bar (`closed: false`), this is the last traded price so far.
</ResponseField>

<ResponseField name="v" type="string">
  Total traded volume during the candle period (raw integer string). Divide by `10^qtyScale` from `configs` to get the display value.
</ResponseField>

<ResponseField name="n" type="integer">
  Number of individual trades that occurred during the candle period.
</ResponseField>

<ResponseField name="closed" type="boolean">
  `true` if this candle is finalized (the period has ended); `false` if this is the current open bar that is still accumulating trades. At most one `false` candle will appear, always as the last element in the array.
</ResponseField>