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

# Get candles

> Query finalized OHLCV candles for one market.

<ParamField path="marketAddress" type="string" required>
  Lowercase 20-byte market contract address.
</ParamField>

<ParamField query="interval" type="string" required>
  One of `1s`, `1m`, `5m`, `1h`, `6h`, or `1d`. Each interval maps directly
  to a materialized continuous aggregate.
</ParamField>

<ParamField query="from" type="integer" required>
  Inclusive lower bound on the candle's start timestamp, in Unix seconds.
</ParamField>

<ParamField query="to" type="integer">
  Inclusive upper bound on the candle's start timestamp, in Unix seconds.
  When omitted, the upper bound is the current time.
</ParamField>

<ParamField query="countback" type="integer" default="5000">
  Return up to the latest N candles within the requested range. Accepts `1` to
  `5000`. Results are returned oldest-first. The query does not search before
  `from` to satisfy the count, so fewer than N candles may be returned.
</ParamField>

<ParamField query="limit" type="integer">
  Backward-compatible alias for `countback`, with the same range and behavior.
  Providing both `limit` and `countback` returns `400 Bad Request`.
</ParamField>

When neither `countback` nor `limit` is supplied, the latest 5000 candles at most
within the requested range are returned, ordered oldest-first. Responses never
exceed 5000 candles. Empty, zero, negative, non-integer, or greater-than-5000 count
values are rejected. `from` must be less than or equal to an explicit `to`.

For example, if a range contains ten one-minute candles from `10:00` through
`10:09`, `countback=3` returns `10:07`, `10:08`, and `10:09`. Omitting both count
parameters returns all ten candles. Range bounds apply to bucket start times:
for hourly candles, a `from` at `10:15` excludes the `10:00` candle, while a `to`
at `11:00` includes the `11:00` candle.

The response is columnar. Values at the same array index belong to one candle:
`t` is Unix time in seconds, `o/h/l/c` are price integer strings in market pp, and `v`
remains x18 quote volume.
Missing intervals carry forward the preceding aggregate close: open, high, low
and close all equal that price, and volume is zero. The preceding price may be
before `from`; returned timestamps never are. If no earlier price is known,
leading empty buckets are omitted. A market with no candles returns empty arrays.
Synthetic candles count toward `countback` and `limit`; future buckets are never
generated, even if `to` is in the future. Boundaries are UTC-aligned.
Actual candles retain their original OHLCV. This is query-time filling and does
not change the continuous aggregates or repair missed refreshes.
`feedEpoch` and `marketSeq` report the materialization epoch and the market's
sequence progress, read alongside the candles and cached with the response.
Either may be `null` when the corresponding progress is unavailable.
Candle aggregates can lag this progress while refreshing; these fields do not
guarantee that all trades through `marketSeq` are included in the candle arrays.
Historical range filters do not change this progress metadata.

<ResponseExample>
  ```json 200 theme={null}
  {
    "feedEpoch": 283,
    "marketSeq": "5798",
    "data": {
      "t": [
        1788274800,
        1788339600,
        1788350400
      ],
      "o": [
        "255179",
        "244994",
        "237485"
      ],
      "h": [
        "257507",
        "257282",
        "247071"
      ],
      "l": [
        "242806",
        "242282",
        "237485"
      ],
      "c": [
        "252201",
        "252272",
        "247071"
      ],
      "v": [
        "1330230000000000000000",
        "1252520000000000000000",
        "38550000000000000000"
      ]
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml api/data-source/openapi.yaml GET /api/v1/markets/{marketAddress}/candles
openapi: 3.1.0
info:
  title: Kuru Data Source API
  version: 1.0.0
servers:
  - url: https://api.mainnet.kuru.io
    description: Monad mainnet (default)
  - url: https://api.testnet.kuru.io
    description: Monad testnet
security: []
paths:
  /api/v1/markets/{marketAddress}/candles:
    get:
      summary: Get candles
      description: >-
        Missing buckets carry the preceding aggregate close into OHLC with zero
        volume. No candles are generated before the first known price or in the
        future. Synthetic buckets count toward countback. Response fields and
        units are unchanged.
      operationId: getCandles
      parameters:
        - name: marketAddress
          in: path
          required: true
          schema:
            type: string
            example: '0x8121ee960066e4344a213f9ac7502395502aee7a'
        - name: interval
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: integer
        - name: to
          in: query
          schema:
            type: integer
        - name: countback
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Candles

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.