Skip to content
ChordChordChord Docs

Candles (data API)

GET
/candles
curl --request GET \
  --url 'https://api.getchord.xyz/v1/candles?chain=5042&token=example&tf=1m&limit=300&fill=1'

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

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
chain
integer
default: 143
Allowed values: 5042 4663 43114 8453 56 42161 1 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
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/

Token address.

tf
string
default: 1h
Allowed values: 1m 5m 15m 1h 4h 1d 1w

Timeframe.

from

Unix time, seconds, UTC.

integer

Start, inclusive. Default: to minus limit buckets.

to

Unix time, seconds, UTC.

integer

End, exclusive, snapped up to a bucket edge. Default: the end of the open bucket.

limit
integer
default: 300 >= 1 <= 1000

Buckets per page.

fill
string
Allowed values: 1

Carry the previous close through empty buckets (v = 0, n = 0).

Responses

Section titled “ Responses ”

200

Section titled “200”
Media typeapplication/json
object
chain
integer
token

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
tf
string
source

Always index.

string
from

Unix time, seconds, UTC.

integer
to

Unix time, seconds, UTC.

integer
forming

The last candle is the still-open bucket.

boolean
ingestFloor

Only on 43114 / 8453 / 56 when the tape runs with a floor (BNB Chain).

object
minTradeUsd

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.

number
history

Floors in force over time, oldest first. Empty when the chain was never floored. Raising a floor does not remove older, smaller rows.

Array<object>
object
usd

Floor in force.

number
fromTs

Unix time, seconds, UTC.

integer
candles

Oldest first.

Array<object>
object
t

Unix time, seconds, UTC.

integer
o
number
h
number
l
number
c
number
v

USD volume in the bucket.

number
n

Trades in the bucket.

integer | null
Example
{
  "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

Section titled “400”

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

404

Section titled “404”

Nothing at this identity (NOT_FOUND, UNKNOWN_TOKEN, NO_ROUTE).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

503

Section titled “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.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}