---
title: Candles
description: OHLCV candlestick data via the Kiyotaka Data API.
---

# Candles

<EndpointBar method="GET" path="/v1/points"></EndpointBar>

## Side-Agnostic Candles

<TypeHeader type="TRADE_SIDE_AGNOSTIC_AGG" meta="Weight: 1x | Max points: 100,000"></TypeHeader>

Standard OHLCV candlestick data with combined buy + sell volume. This is the most common candle type.

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `open` | double | Opening price |
| `high` | double | Highest price in the interval |
| `low` | double | Lowest price in the interval |
| `close` | double | Closing price |
| `volume` | double | Total traded volume (coin by default, USD with [transform](/docs/exchanges#transforms)) |
| `timestamp` | Timestamp | Start of the candle interval |
| `firstTimestamp` | Timestamp | Timestamp of the first trade in the interval |
| `lastTimestamp` | Timestamp | Timestamp of the last trade in the interval |

### Capabilities

| Feature | Supported | Details |
| --- | --- | --- |
| USD denomination | Yes | `transform.normalize.quote=USD` converts volume to USD |
| Multi-exchange aggregation | Yes | `transform.groupBy.type=GROUP_BY_TYPE_SUM` with `coin` param |
| Gapfill | Yes | `gapfill=true` fills missing intervals using last close price. Gapfill is only supported on candle types. |

### Examples

### Single exchange

Fetches 6.25 days (`period=540000` seconds) of hourly candles for BTCUSDT on Binance Futures, starting from the given timestamp.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">TRADE_SIDE_AGNOSTIC_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">540000</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_SIDE_AGNOSTIC_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=540000 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_SIDE_AGNOSTIC_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=540000 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Aggregated across exchanges (USD volume)

Aggregates 1 hour of hourly BTC candle data across Binance Futures, Bybit, and OKX into a single series. Volume is converted to USD so values are comparable across exchanges.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">TRADE_SIDE_AGNOSTIC_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BYBIT</span>
    <span class="s-p">&exchange</span>=<span class="s-s">OKEX_SWAP</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</span>
    <span class="s-p">&transform.groupBy.type</span>=<span class="s-s">GROUP_BY_TYPE_SUM</span>
    <span class="s-p">&transform.normalize.quote</span>=<span class="s-s">USD</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_SIDE_AGNOSTIC_AGG&exchange=BINANCE_FUTURES&exchange=BYBIT&exchange=OKEX_SWAP&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.groupBy.type=GROUP_BY_TYPE_SUM&transform.normalize.quote=USD "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_SIDE_AGNOSTIC_AGG&exchange=BINANCE_FUTURES&exchange=BYBIT&exchange=OKEX_SWAP&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.groupBy.type=GROUP_BY_TYPE_SUM&transform.normalize.quote=USD "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Response

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"series"</span>: [
    {
      <span class="s-p">"id"</span>: {
        <span class="s-p">"type"</span>: <span class="s-s">"TRADE_SIDE_AGNOSTIC_AGG"</span>,
        <span class="s-p">"exchange"</span>: <span class="s-s">"BINANCE_FUTURES"</span>,
        <span class="s-p">"rawSymbol"</span>: <span class="s-s">"BTCUSDT"</span>,
        <span class="s-p">"normalizedSymbol"</span>: <span class="s-s">"BTC-USDT"</span>,
        <span class="s-p">"category"</span>: <span class="s-s">"PERPETUAL"</span>,
        <span class="s-p">"interval"</span>: <span class="s-s">"HOUR"</span>,
        <span class="s-p">"coin"</span>: <span class="s-s">"BTC"</span>
      },
      <span class="s-p">"points"</span>: [
        {
          <span class="s-p">"Point"</span>: {
            <span class="s-p">"open"</span>: <span class="s-n">66499.9</span>,
            <span class="s-p">"high"</span>: <span class="s-n">66639.0</span>,
            <span class="s-p">"low"</span>: <span class="s-n">66400.0</span>,
            <span class="s-p">"close"</span>: <span class="s-n">66467.8</span>,
            <span class="s-p">"volume"</span>: <span class="s-n">2852.8330000000055</span>,
            <span class="s-p">"timestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774800000</span> },
            <span class="s-p">"firstTimestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774800003</span>, <span class="s-p">"ns"</span>: <span class="s-n">234000000</span> },
            <span class="s-p">"lastTimestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774803599</span>, <span class="s-p">"ns"</span>: <span class="s-n">649000000</span> }
          }
        }
      ]
    }
  ]
}</pre>
</CodeBlock>

---

## Per-Side Candles

<TypeHeader type="TRADE_AGG" meta="Weight: 1x | Max points: 100,000"></TypeHeader>

Candle data split by trade side. Returns separate series for buy and sell trades, giving you buy volume and sell volume independently.

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `open` | double | Opening price |
| `high` | double | Highest price in the interval |
| `low` | double | Lowest price in the interval |
| `close` | double | Closing price |
| `volume` | double | Volume for this side (coin by default, USD with transform) |
| `timestamp` | Timestamp | Start of the candle interval |
| `firstTimestamp` | Timestamp | Timestamp of the first trade in the interval |
| `lastTimestamp` | Timestamp | Timestamp of the last trade in the interval |

The series identifier includes a `side` field (`BUY` or `SELL`).

### Capabilities

| Feature | Supported | Details |
| --- | --- | --- |
| USD denomination | Yes | `transform.normalize.quote=USD` |
| Multi-exchange aggregation | Yes | `transform.groupBy.type=GROUP_BY_TYPE_SUM` with `coin` param |
| Gapfill | Yes | `gapfill=true` fills missing intervals. Gapfill is only supported on candle types. |

### Example

Fetches 1 hour of hourly per-side candles for BTCUSDT on Binance Futures. The response contains two series -- one with `"side": "BUY"` and one with `"side": "SELL"` -- each with their own OHLCV data.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">TRADE_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=3600 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=TRADE_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=3600 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>