# Candles (data API)

`GET https://api.getchord.xyz/v1/candles`

Source: https://getchord.xyz/docs/api-reference/operations/candles/

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.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | no | `5042` · `4663` · `43114` · `8453` · `56` · `42161` · `1` · `143` (default `143`) | Chain id: `5042` Arc · `4663` Robinhood Chain · `43114` Avalanche C-Chain · `8453` Base · `56` BNB Chain · `42161` Arbitrum One · `1` Ethereum · `143` Monad. Omitted = 143. |
| `token` | query | yes | string | Token address. |
| `tf` | query | no | `1m` · `5m` · `15m` · `1h` · `4h` · `1d` · `1w` (default `1h`) | Timeframe. |
| `from` | query | no | integer | Start, inclusive. Default: `to` minus `limit` buckets. |
| `to` | query | no | integer | End, exclusive, snapped up to a bucket edge. Default: the end of the open bucket. |
| `limit` | query | no | integer (default `300`) | Buckets per page. |
| `fill` | query | no | `1` | Carry the previous close through empty buckets (v = 0, n = 0). |

## Response 200

Example (captured from the live API):

```json
{
  "chain": 5042,
  "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
  "tf": "1h",
  "source": "index",
  "from": 1790704800,
  "to": 1790712000,
  "forming": true,
  "candles": [
    {
      "t": 1790704800,
      "o": 83084.16874661468,
      "h": 83761.32352941176,
      "l": 82504.09836065574,
      "c": 83716.00512163893,
      "v": 236698.5,
      "n": 976
    },
    {
      "t": 1790708400,
      "o": 83676.16747181964,
      "h": 83758.25396825396,
      "l": 82970.76923076923,
      "c": 83590.35733333333,
      "v": 28901.4,
      "n": 212
    }
  ]
}
```

- **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.