Prise en main

Conventions

Les règles qui valent sur toutes les familles. Elles expliquent pourquoi deux appels au même endpoint peuvent différer, pourquoi un chiffre ne se compare pas à un autre, et ce que veut dire l’absence d’une place de marché dans un agrégat.

#Symboles

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

Symbole	Actif	Marchés collectés
`BTCUSDT`	Bitcoin	spot + perpétuel
`ETHUSDT`	Ethereum	spot + perpétuel
`SOLUSDT`	Solana	spot + perpétuel
`XRPUSDT`	XRP	spot + perpétuel
`DOGEUSDT`	Dogecoin	spot + perpétuel
`BNBUSDT`	BNB	spot + perpétuel
`TRXUSDT`	TRON	spot + perpétuel
`SUIUSDT`	Sui	spot + perpétuel
`HYPEUSDT`	HYPE	spot + perpétuel
`XLMUSDT`	Stellar	spot + perpétuel
`USDCUSDT`	USDC — spot uniquement	spot
`USDTUSDC`	USDT — spot uniquement	spot

symbol est obligatoire

Sur toutes les routes propres à un actif. Absent, la requête rend 422 ; inconnu ou désactivé, 400 avec la liste des valeurs acceptées. Il n’y a ni symbole par défaut ni repli : servir Bitcoin à qui n’a rien demandé produirait un chiffre juste attribué au mauvais actif.

Les données marché entier n’acceptent au contraire aucun symbole : Fear & Greed, marché global, macro, ETF, réseau Bitcoin, on-chain BTC et ETH. Les options se ciblent par ?asset=BTC ou ?asset=ETH.

#Pas de temps

Sur les routes bucketées, sept valeurs :

1m5m15m30m1h4h1d

Les indicateurs techniques en acceptent une huitième, la semaine, parce qu’ils sont calculés directement sur les bougies :

1m5m15m30m1h4h1d1w

Deux exceptions à retenir :

Le ratio long/short refuse 1m — aucune place ne publie de ratio compte-global à ce pas.
Les instruments macro intraday refusent 30m et cinq d’entre eux ne sont servis qu’en 1d. Le catalogue de la famille dit lesquels.

Une valeur hors liste rend 422 avec les valeurs acceptées, jamais un repli silencieux sur un autre pas.

#Agrégation multi-place

Aucune réponse ne nomme sa place de marché. Les métriques multi-place arrivent déjà fusionnées : c’est le contrat de la plateforme, et la raison pour laquelle des intégrations multiples deviennent une seule. Trois règles de fusion, selon la nature de la grandeur :

Nature	Type	Description
`somme`	additive	Volumes, open interest, comptes de trades, liquidations, profondeur de carnet. Une place manquante rend mécaniquement le chiffre trop bas.
`moyenne pondérée par l’open interest`	taux et prix	Funding, basis, ratio long/short. La place qui porte le plus de positions pèse le plus — c’est ce qui rend le composite représentatif.
`moyenne pondérée par le volume`	prix moyens	VWAP et prix de référence. Le poids naturel d’un prix moyen est le volume qui l’a produit.

Une seule exception dans toute l’API : /v1/spread/interexchange nomme les places, un écart n’ayant pas de sens sans elles. Partout ailleurs, le paramètre exchange n’existe pas — le passer rend 422.

#Bougies fermées et période en cours

Six familles servent des données découpées en fenêtres : les bougies de trades, le VWAP par fenêtre, le CVD, le carnet agrégé, les écarts entre places et le ratio long/short. Sur celles-là, chaque ligne porte un booléen is_closed, que vous l’ayez demandé ou non.

Valeur	Type	Description
`true`	boolean	La valeur est finale et immuable. Elle ne bougera plus jamais : elle peut être stockée, sommée, comparée à un graphique.
`false`	boolean	La valeur est provisoire. Deux appels successifs peuvent rendre des chiffres différents pour la même ligne.

Par défaut, seules les fenêtres fermées sont servies. Pour voir la période en cours, ajoutez ?live=1 :

curl

# La derniere bougie horaire FERMEE : sa valeur ne bougera plus.
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h"

# La bougie EN COURS : provisoire, marquee is_closed: false.
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/cvd?symbol=BTCUSDT&timeframe=1h&live=1"

Ce qu’il faut savoir sur ?live=1

C’est une option. Sans elle, la réponse est strictement celle d’avant.
Uniquement sur les routes de dernière valeur. Les /history ne servent que du fermé, par définition ; le paramètre y est ignoré.
Jamais de null. Si la période en cours n’a encore rien reçu — marché calme — la dernière fenêtre fermée est rendue à la place.
La valeur ne saute pas à la fermeture. Provisoire et définitive sortent de la même définition : quand la période se ferme, la ligne se fige sur le chiffre qu’elle affichait.

Fraîcheur atteignable : environ deux secondes sur les trades, le VWAP, le CVD et les écarts ; six à dix secondes sur le carnet ; une minute sur le ratio long/short, que les places ne publient pas plus vite.

#Couverture des sources

Puisque la place n’est jamais nommée, un funding calculé sur deux places a la même forme qu’un funding calculé sur six. Deux mécanismes rétablissent l’information :

venue_count, ligne par ligne — le compte réel de la fenêtre concernée. Il varie d’une fenêtre à l’autre, il ne peut donc pas être un attribut global. Le funding le nomme exchange_count, pour raison historique.
la clé coverage sur le snapshot — ce qui est constant sur toutes les lignes : combien de places étaient attendues, et l’effet d’une absence.

coverage

{
  "coverage": {
    "oi_history": {
      "status": "available",
      "effect": "additive",
      "count_field": "venue_count",
      "venues_expected": 6
    },
    "cvd@1h": { "status": "unavailable", "reason": "pre_aggregated" }
  }
}

Clé	Type	Description
`effect: additive`	string	Une place absente rend le chiffre mécaniquement trop bas. Ne rapportez jamais la baisse comme un événement de marché : dites « au moins X ».
`effect: weighted`	string	Le niveau reste valide mais peut être biaisé. Ne le comparez pas à un historique calculé sur davantage de places.
`venues_expected`	integer	Le dénominateur observé sur une fenêtre glissante, jamais déclaré. Il varie par actif et par métrique : certains actifs ne sont pas listés partout, et toutes les places ne publient pas de liquidations.
`status: unavailable`	string	La couverture n’est pas connue pour ce champ — soit la place a été fusionnée dès l’écriture, soit les lignes sont antérieures à la mesure. Ne concluez pas qu’elle est complète.

#Horodatages et ordre

Les horodatages de la donnée sont en ISO 8601, en UTC : 2026-08-29T11:38:00+00:00. La clé bucket désigne le début de la fenêtre, jamais sa fin.
Les bornes de requête — since_ms et until_ms — sont en millisecondes depuis l’époque Unix. Une borne négative ou un since_ms supérieur à until_ms rend 422.
Les tableaux de valeurs — la série d’un indicateur, la série interne d’un CVD — vont de l’ancien vers le récent.
Les listes d’historique sont rendues du plus récent au plus ancien. La ligne la plus fraîche est en tête.
Le jour commence à minuit UTC — c’est la remise à zéro du VWAP intraday, et l’alignement des séries quotidiennes.