Conventions de l'API
Les règles communes à tous les endpoints : structure des URL, enveloppe de réponse, symboles, unités, horodatages, pagination et mise en cache.
URL de base et versionnement
Tous les endpoints se trouvent sous une même URL de base et s'appellent en GET HTTPS. Les chemins actuels correspondent à la version v1. Au sein de la v1, les changements sont additifs : des champs et des endpoints peuvent être ajoutés, les champs existants conservent leur nom, leur type et leur sens. Un changement non rétrocompatible serait publié sous un nouveau chemin et annoncé au préalable dans le journal des modifications.
https://www.coinboss.com/apiEnveloppe de réponse
Chaque réponse JSON comporte un indicateur success au premier niveau. Les endpoints de la couche de données collectées en interne (chemins sous /api/sd) partagent les mêmes blocs supplémentaires :
| Champ | Description |
|---|---|
| success | true lorsque l'appel a abouti. Vérifiez-le systématiquement. |
| schema | Identifiant et version majeure de la structure de la réponse. |
| now | Heure du serveur au moment où la réponse a été assemblée, en millisecondes. |
| coverage | Les plateformes incluses, celles qui sont indisponibles et pourquoi, et celles qui ont été exclues car périmées. |
| method | La formule ou la règle derrière chaque agrégat de la réponse. |
| meta | Sources, horodatages, fenêtre, note de qualité, indicateur de péremption, durée de vie du cache et comportement de repli. |
Les endpoints plus anciens renvoient success et un champ data, et peuvent ne pas inclure coverage, method ni meta. Leurs pages de référence documentent les champs exacts.
Cryptos, contrats et plateformes
- Les paramètres coin attendent le symbole de base en majuscules, par exemple BTC ou PEPE.
- Les contrats à multiplicateur tels que 1000PEPE ou kPEPE sont fusionnés dans leur crypto de base, avec conversion des quantités.
- Les identifiants de plateforme sont en minuscules, par exemple binance, okx, bybit, hyperliquid.
- Les symboles de contrat sont renvoyés tels que la plateforme les nomme. Les contrats à marge USDT, USDC ou crypto et les futures à échéance sont distingués par un champ de type de contrat lorsqu'un endpoint les mélange.
- Les contrats perpétuels sur actions tokenisées et matières premières qui partagent un ticker avec un crypto-actif sont exclus des agrégats crypto.
Unités
- Les champs se terminant par _usd sont des notionnels en dollars américains.
- Les taux de financement sont des fractions, non des pourcentages : 0.0001 signifie 0,01 %. Les champs se terminant par _8h sont normalisés sur un intervalle de 8 heures ; l'intervalle d'origine est renvoyé à côté du taux brut.
- Les champs se terminant par _pct sont des pourcentages : 1.5 signifie 1,5 %.
- Les positions ouvertes sont un notionnel simple face en USD, sauf mention contraire dans la description d'un champ. Les plateformes qui publient des chiffres double face sont signalées dans le bloc method.
- Certains endpoints hérités renvoient les décimaux sous forme de chaînes pour préserver la précision. Le tableau des champs indique alors le type string(decimal).
Horodatages
- Les horodatages sont en millisecondes depuis l'époque Unix, en UTC, sauf mention contraire dans la description d'un champ.
- observed_at est l'horodatage propre à la plateforme pour l'enregistrement le plus récent inclus, ou null lorsque la plateforme n'en fournit pas.
- received_at est le moment où le collecteur CoinBoss a stocké cet enregistrement.
- fetched_at est le moment où la réponse a été assemblée. Pour une réponse en cache, il peut précéder l'heure de votre appel d'une durée allant jusqu'au TTL du cache.
- Les séries quotidiennes utilisent les limites de jour UTC.
Fenêtres et intervalles
- Les paramètres de fenêtre utilisent des valeurs courtes : 1h, 4h, 12h, 24h et, sur certains endpoints, 3d, 7d, 30d, 90d. La page de référence liste les valeurs acceptées pour chaque endpoint.
- Une valeur de fenêtre inconnue est soit rejetée avec INVALID_PARAM, soit remplacée par la valeur par défaut documentée, comme indiqué pour chaque paramètre.
- La taille des tranches des séries temporelles dépend de la fenêtre et est indiquée sur la page de référence.
Pagination et tri
- Les endpoints de liste utilisent limit et offset, ou page et size, selon la documentation de chaque endpoint. Les limites sont plafonnées ; une valeur supérieure est ramenée au plafond.
- Lorsqu'une réponse inclut total, il s'agit du nombre de lignes avant pagination.
- L'ordre de tri est fixe, sauf si l'endpoint documente un paramètre de tri.
Null, zéro et valeur absente
- null signifie que la valeur est inconnue ou indisponible. 0 signifie un zéro mesuré.
- Les graphiques doivent afficher un trou pour null. N'interpolez pas.
- Un champ marqué « peut être absent » dans un tableau des champs peut manquer entièrement dans l'objet ; traitez-le comme null.
Mise en cache
- Chaque endpoint possède un TTL de cache serveur, indiqué sur sa page de référence et dans meta.cache_ttl_s. L'en-tête X-Cache indique HIT, STALE ou MISS.
- Un cache court en périphérie, d'une dizaine de secondes, est placé devant la plupart des endpoints GET.
- Interroger plus souvent que le TTL renvoie des données identiques et ne fait que consommer votre limite de requêtes.
WebSocket
wss://www.coinboss.com/ws- Le flux est en JSON, en push uniquement. Chaque message comporte un champ type.
- Après une déconnexion, reconnectez-vous après un délai et rattrapez les données manquantes via l'endpoint HTTP correspondant.
Documentation lisible par machine
Le catalogue, les paramètres et le tableau des champs de chaque endpoint, le statut et la matrice de qualité sont disponibles en JSON sous /api/meta, et l'ensemble du catalogue sous forme de document OpenAPI 3.