# Candles (/scripting/data-types/candles)



Read candles through `history.source` in live runs and backtests:

```js
const candles = history.source('btc@candles@binancef@mmt')
const latest = history.source('btc@candles@binancef@mmt', 0)
```

## Shape [#shape]

```ts
type Candle = {
  t: number
  o: number
  h: number
  l: number
  c: number
  volume: number
  trades: number
  close_time?: number
  vb?: number
  vs?: number
  tb?: number
  ts?: number
}
```

Fields:

* `t`: bucket start in Unix milliseconds.
* `o`, `h`, `l`, `c`: open, high, low, and close prices.
* `volume`: total volume available for the candle.
* `trades`: total trade count.
* `close_time`: exclusive bucket end in Unix milliseconds when supplied.
* `vb`, `vs`: buy and sell volume when directional volume is available.
* `tb`, `ts`: buy and sell trade counts when directional counts are available.

Live MMT, BULK, and Hyperliquid candles are derived locally from trades, so all directional fields and `close_time` are present. Live `volume`, `vb`, and `vs` use the base quantity reported by the raw trade stream.

Backtests read provider-stored candles. MMT historical candles include directional fields. Standalone historical candle fields retain what each exchange returns rather than inventing unavailable directional data.

## Example [#example]

```js
export function onData(ctx, input, history) {
  const candles = history.source('btc@candles@binancef@mmt')
  const latest = history.source('btc@candles@binancef@mmt', 0)
  if (!latest) return

  const sma = ctx.study.sma(candles, { window: 20 })
  const delta =
    latest.vb !== undefined && latest.vs !== undefined
      ? latest.vb - latest.vs
      : null

  return {
    metrics: {
      candles: candles.length,
      close: latest.c,
      sma: sma.latest,
      delta,
    },
  }
}
```

See [Candles Source](/scripting/sources/candles) for live aggregation, startup alignment, and historical timeframe limits.