Conventions de l’API pour le code et les LLM

#Symboles

104 actifs sont suivis : 102 perpétuels USDT-M et deux stablecoins, ces derniers en spot uniquement. La liste vivante est servie par /v1/symbols, et c’est elle qui fait foi.

#Unités de temps

Sur la plupart des routes par intervalles, sept valeurs :

1m5m15m30m1h4h1d

Les bougies (/v1/klines) et les indicateurs techniques en acceptent une huitième, la semaine (qui commence le lundi à 00:00 UTC), parce qu’ils sont construits directement sur les bougies :

1m5m15m30m1h4h1d1w

Les exceptions : les routes d’options refusent 1m (leurs instantanés arrivent environ une fois par minute), les instruments macro intrajournaliers refusent 30m, et le pas facultatif de /v1/btc/fees/history et /v1/global/history vaut 1h, 4h ou 1d. Le contrat donne à chaque route sa liste exacte (un enum), et le catalogue de la famille (/v1/macro/intraday/series) les unités de temps de chaque instrument.

Une valeur hors liste renvoie 422 invalid_timeframe avec les valeurs acceptées, jamais un repli silencieux sur une autre unité de temps. Toute erreur de validation est un 422, corps de POST /v1/indicators et historiques d’options compris. Testez error.code : il dit quel paramètre est en cause. Comme symbol, timeframe et order ignorent la casse (1H vaut 1h), sauf 1M : ailleurs un mois, il est refusé ici, 1m étant une minute.

#Agrégation multi-places

Les métriques multi-places arrivent déjà fusionnées : c’est le contrat de la plateforme, et la raison pour laquelle plusieurs intégrations deviennent une seule. Trois règles de fusion, selon la nature de la grandeur :

Le paramètre exchange n’existe sur aucune route : le passer renvoie 422.

#Bougies closes et période en cours

Toute route qui sert une donnée découpée en fenêtres porte un booléen is_closed sur chaque ligne, que vous l’ayez demandé ou non : bougies, bougies de trades, CVD, ratio achat/vente, taille des trades, grosses/petites liquidations, carnet, spreads entre places — et chaque ligne de chaque route /history (basis, open interest, funding, liquidations, macro, on-chain…). Leur dernière valeur est le dernier bucket CLOS de timeframe (obligatoire). Une dernière valeur calculée sur une fenêtre GLISSANTE (liquidations cumulées, variation d’open interest, funding cumulé, variation d’open interest des options) est toujours définitive et ne porte pas is_closed : time est la fin de sa fenêtre, window_start_at et window_s en donnent le début et la durée.

Par défaut, seules les fenêtres closes sont servies. Pour voir la période en cours, ajoutez ?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"

#Unités et échelles

Une proportion ne s’écrit jamais de deux façons. Le suffixe d’un champ donne son échelle, et la règle vaut dans toutes les familles, du cœur de marché aux satellites :

#Horodatages et ordre

• Les horodatages des données sont en ISO 8601, en UTC, avec le suffixe Z et trois chiffres fixes de millisecondes : 2026-08-29T11:38:00.000Z. time est TOUJOURS dans ce format, séries quotidiennes comprises (un jour est daté à minuit UTC) et il n’y a pas de clé date à côté ; une date seule (2026-08-29) n’apparaît que dans les clés qui désignent un jour métier, comme filed_date ou oldest_input_date. time suit l’une de deux règles, et la référence de chaque route dit laquelle : sur une série découpée en buckets (bougies, CVD, carnet par bucket, funding par période de 8 h), c’est le début du bucket, jamais sa fin ; sur une valeur ponctuelle (dernière valeur, fenêtre glissante, prévision, composite), c’est l’instant auquel la valeur se rapporte — la fin d’une fenêtre glissante, le règlement que vise une prévision, l’entrée la plus récente d’un composite (qui donne aussi oldest_input_date). La valeur courante d’une route en buckets est son dernier bucket CLOS, daté à son début comme la première ligne de son /history : /v1/klines, /v1/cvd, /v1/buy-sell-ratio, /v1/trades/avg-size, /v1/liquidations/big-small-ratio, /v1/orderbook (toutes exigent timeframe). L’enveloppe de /v1/options/max-pain/history rappelle expiry sous la forme du jour d’échéance (YYYY-MM-DD), quelle que soit la forme envoyée.
• Les bornes de requête (since_ms, until_ms et before_ms) sont en millisecondes depuis l’époque Unix. since_ms et until_ms sont inclusives (à la milliseconde), before_ms est exclusive. since_ms=0 veut dire le début des données. Une borne négative, un since_ms supérieur à until_ms (égal lit cette milliseconde) ou supérieur ou égal à before_ms, until_ms et before_ms ensemble, une borne en secondes, en microsecondes ou en nanosecondes, ou toute autre borne antérieure au 2009-01-03 (le premier bloc Bitcoin) rend 422 avant toute exécution.
• Les tableaux de valeurs (la série d’un indicateur, la série interne d’un CVD) vont du plus ancien au plus récent.
• Les listes d’historique sont renvoyées du plus récent au plus ancien par défaut — la ligne la plus fraîche vient en premier —, ou du plus ancien au plus récent avec order=asc.
• La journée commence à minuit UTC : c’est l’alignement des séries quotidiennes.