Conventions

#Symbols

Twenty-two assets are tracked: twenty USDT-M perpetuals and two stablecoins, the latter in spot only. The live list is served by /v1/symbols, and that one is authoritative.

#Timeframes

On most bucketed routes, seven values:

1m5m15m30m1h4h1d

Candles (/v1/klines) and technical indicators accept an eighth one, the week (starting Monday 00:00 UTC), because they are built directly from the candles:

1m5m15m30m1h4h1d1w

The exceptions: options routes refuse 1m (their snapshots come about once a minute), intraday macro instruments refuse 30m, and the optional step of /v1/btc/fees/history and /v1/global/history is 1h, 4h or 1d. The contract gives each route its exact list (an enum), and the family catalogue (/v1/macro/intraday/series) the timeframes of each instrument.

A value outside the list returns 422 invalid_timeframe with the accepted values, never a silent fallback to another timeframe. Every validation error is a 422, the body of POST /v1/indicators and the options histories included. Branch on error.code, it says which parameter is at fault. Like symbol, timeframe and order ignore case (1H is 1h), except 1M: elsewhere a month, it is refused here, 1m being one minute.

#Multi-venue aggregation

No response names its trading venue. Multi-venue metrics arrive already merged: that is the platform’s contract, and the reason why multiple integrations become a single one. Three merge rules, according to the nature of the quantity:

One single exception in the whole API: /v1/spread/interexchange names the venues, a spread making no sense without them. Everywhere else the exchange parameter does not exist: passing it returns 422.

#Closed candles and the current period

Every route that serves data cut into windows carries an is_closed boolean on every row, whether you asked for it or not: candles, trade candles, CVD, buy/sell ratio, trade size, big/small liquidations, the order book, inter-venue spreads — and every row of every /history route (basis, open interest, funding, liquidations, macro, on-chain…). Their latest value is the latest CLOSED bucket of timeframe (required). A latest value computed over a ROLLING window (cumulative liquidations, open-interest change, cumulative funding, options open-interest change) is always final and carries no is_closed: time is the end of its window, window_start_at and window_s give its start and length.

By default, only closed windows are served. To see the current period, add ?live=1:

# The latest CLOSED hourly candle: its value will not move again.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h"

# The candle IN PROGRESS: provisional, flagged is_closed: false.
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h&live=1"

#Units and scales

A proportion is never written in two ways. The suffix of a field gives its scale, and the rule holds in every family, from the market core to the satellites:

#Timestamps and ordering

• The timestamps of the data are in ISO 8601, in UTC, with the Z suffix and three fixed digits of milliseconds: 2026-08-29T11:38:00.000Z. time is ALWAYS in this format, daily series included (a day is dated at midnight UTC) and there is no separate date key; a date alone (2026-08-29) appears only in keys that name a business day, such as filed_date or oldest_input_date. time follows one of two rules, and the reference of each route says which: on a bucketed series (candles, CVD, order book per bucket, funding per 8 h period) it is the start of the bucket, never its end; on a point-in-time value (a latest value, a rolling window, a forecast, a composite) it is the instant the value refers to — the end of a rolling window, the settlement a forecast is for, the most recent input of a composite (which also gives oldest_input_date). The latest value of a bucketed route is its latest CLOSED bucket, dated at its start like the first row of its /history: /v1/klines, /v1/cvd, /v1/buy-sell-ratio, /v1/trades/avg-size, /v1/liquidations/big-small-ratio, /v1/orderbook (all of them require timeframe). The envelope of /v1/options/max-pain/history repeats expiry as the expiry day (YYYY-MM-DD), whatever form you sent.
• The request bounds (since_ms, until_ms and before_ms) are in milliseconds since the Unix epoch. since_ms and until_ms are inclusive (to the millisecond), before_ms is exclusive. since_ms=0 means the start of the data. A negative bound, a since_ms greater than until_ms (equal reads that one millisecond) or greater than or equal to before_ms, until_ms and before_ms together, a bound given in seconds, in microseconds or in nanoseconds, or any other bound earlier than 2009-01-03 (the first Bitcoin block) returns 422 before anything runs.
• Value arrays (an indicator’s series, the internal series of a CVD) run from oldest to most recent.
• History lists are returned from most recent to oldest by default — the freshest row comes first — or from oldest to most recent with order=asc.
• The day starts at midnight UTC: that is the alignment of the daily series.