---
title: "Candles (data API)"
method: GET
path: "/candles"
tags: ["Tokens and charts"]
---

# Candles (data API)

`GET /candles`

## Request

- Base URL: `https://api.getchord.xyz/v1`
- URL: `https://api.getchord.xyz/v1/candles`
- Auth: none declared

OHLCV for any token Chord indexes on Arc, Robinhood Chain, Avalanche, Base, BNB Chain, Arbitrum, Ethereum or Monad, built only from Chord's own index — never a third-party feed, so `source` is always `index`. 1m / 5m / 15m come from a 1-minute rollup that keeps history after raw trades are retired; 1h and above from the hourly rollup; the newest minutes straight from the tape. Each candle carries `n`, the trades in the bucket. Buckets without a trade are absent unless `fill=1`, which carries the previous close through them.

Paging: the default window ends with the still-open bucket (`forming: true`) and holds `limit` buckets. A `from`–`to` range wider than `limit` keeps the newest buckets; ask for the previous page with `to` = this page's `from`. The token must trade on the chain you name — `404 UNKNOWN_TOKEN` says which chain it trades on when it is another one. The zero address stands for the chain's native asset (its wrapped twin, or the USDC predeploy on Arc). For live candles subscribe on `/v1/ws/live` (see Streaming).

**Avalanche, Base, BNB Chain** (`43114`, `8453`, `56`): candles come from chain-keyed tables, so one address on two chains is two tokens, and `404 UNKNOWN_TOKEN` means no indexed trades on the chain you named. These chains answer once their tape runs and, until the chain is public, only to requests with an `X-API-Key` (`400 UNSUPPORTED_CHAIN` otherwise; all three are public today). Where the tape runs with an ingest floor (BNB Chain, $100 today) the response carries `ingestFloor`, and `v` and `n` count only trades at or above it.

## Query parameters

- `chain` 5042 | 4663 | 43114 | 8453 | 56 | 42161 | 1 | 143
- `token` string, required: EVM address, hex, case-insensitive.
- `tf` '1m' | '5m' | '15m' | '1h' | '4h' | '1d' | '1w'
- `from` integer: Unix time, seconds, UTC.
- `to` integer: Unix time, seconds, UTC.
- `limit` integer
- `fill` '1'

## Response `200`

- object
  - `chain` integer
  - `token` string: EVM address, hex, case-insensitive.
  - `tf` string
  - `source` string: Always `index`.
  - `from` integer: Unix time, seconds, UTC.
  - `to` integer: Unix time, seconds, UTC.
  - `forming` boolean: The last candle is the still-open bucket.
  - `ingestFloor` IngestFloor: The tape's ingest floor. BNB Chain runs at $100 today; Avalanche and Base at 0.
    - `minTradeUsd` number: Trades under this USD value (at index time) are not in the index, so every count, volume and candle covers trades at or above it. 0 = every priced trade.
    - `history` object[]: Floors in force over time, oldest first. Empty when the chain was never floored. Raising a floor does not remove older, smaller rows.
      - `usd` number: Floor in force.
      - `fromTs` integer: Unix time, seconds, UTC.
  - `candles` object[]: Oldest first.
    - `t` integer: Unix time, seconds, UTC.
    - `o` number
    - `h` number
    - `l` number
    - `c` number
    - `v` number: USD volume in the bucket.
    - `n` integer, nullable: Trades in the bucket.

## Other responses

- `400`: Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).
- `404`: Nothing at this identity (`NOT_FOUND`, `UNKNOWN_TOKEN`, `NO_ROUTE`).
- `503`: The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.

---

[API](https://skmtc.dev/getchord/apis/chord-api.md) · [All operations](https://skmtc.dev/getchord/apis/chord-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getchord/apis/chord-api/revisions/d3bc4640fea0?raw)