OHLCV candles aggregated from 1-minute bars — accepts any venue/instrument.

Aggregates 1-minute OHLCV rows from the `candle_1m` table up to the requested interval. The bucket fold is (first open, MAX high, MIN low, last close, SUM base volume) so multi-minute bars are consistent with the underlying 1m stream. Pass `symbol` as a canonical `BTC-USDT-PERP` or a bare base (`BTC`) — a bare base resolves to the preferred perp for that asset. Unknown symbols return `[]`, not an error.

Query parameters

All query parameters are optional unless marked required.

Response shape

Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.

// Wrapped in the standard envelope:
// {
//   data: /* shape below */,
//   meta?: { total?: number; limit?: number; offset?: number; ... }
// }

Array<{
  time: number;   // seconds since epoch (Lightweight Charts convention)
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number; // base units (not USD)
}>

Example

Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.

curl -sS "http://localhost:3000/api/v1/candles?symbol=BTC&interval=1h&limit=5"

{
  "data": [
    { "time": 1744834800, "open": 62900.1, "high": 63250.0, "low": 62850.0, "close": 63180.5, "volume": 1820.4 }
  ],
  "meta": { "count": 1, "symbol": "BTC", "canonical": "BTC-USDT-PERP", "exchange": null, "interval": "1h", "intervalMs": 3600000, "from": null, "to": null }
}

Notes

• `time` is seconds-since-epoch (Lightweight Charts convention), not ms. Every other timestamp in the API is ms — this one field is the exception.
• `volume` is in base units (e.g. BTC), not USD. Multiply by `close` for a notional estimate.