La COT Data API — accès programmatique aux rapports CFTC

Qui utilise vraiment une API pour les données COT ?

Trois profils, d’après notre expérience :

Le trader systématique. Fait tourner un modèle de positionnement en Python ou en R. Lit la nouvelle publication de la CFTC le vendredi après-midi, recalcule son modèle pendant le week-end et il est prêt avant l’ouverture du lundi. Il ne veut ni écrire un scraper CFTC ni gérer des téléchargements CSV ; il veut requests.get(...) et une enveloppe JSON.

L’analyste qui construit un tableau de bord. Tableau de bord interne d’équipe, panneau Grafana, base Notion, rapport Tableau sur mesure. Il fait entrer le dernier positionnement COT dans une vue que ses collègues consultent déjà chaque jour. Il lui faut une structure JSON stable, qui ne change pas sous ses pieds.

Le développeur d’outils indépendant. Un bot Discord qui publie chaque vendredi la nouvelle sortie COT sur un serveur. Une petite page web qui trace le positionnement Managed Money à côté du prix. Une application mobile qui envoie une notification quand le positionnement atteint le bord de sa fourchette. Des supports différents, le même besoin de données.

Si votre façon de travailler ressemble à l’une de celles-ci, l’API est faite pour vous. Si vous voulez simplement lire le rapport, le site le fait gratuitement.

Les quatre endpoints

L’API est volontairement resserrée. Quatre endpoints, chacun fait une seule chose, tous renvoient du JSON :

GET /api/v1/markets/ — liste chaque marché CFTC de notre catalogue, avec son nom, son code CFTC, sa catégorie, sa bourse, l’unité du contrat, les familles de rapports qui le publient et les dates de son premier et de son dernier rapport. Filtrez avec category, family, tracked ou search ; paginez avec limit et offset. Appelez-le une fois pour trouver les codes dont vous avez besoin, puis gardez votre propre liste.

GET /api/v1/cot/{cftc_code}/ — l’historique hebdomadaire d’un marché. Par défaut, il renvoie les 520 derniers rapports hebdomadaires (environ 10 ans) du rapport Legacy. family=disagg|tff|supp passe aux autres familles de rapports de la CFTC ; from / to (AAAA-MM-JJ) restreignent les dates ; limit fixe le nombre de rapports renvoyés.

GET /api/v1/cot/{cftc_code}/latest/ — le rapport le plus récent d’un marché, quand seule la semaine en cours vous intéresse, pas tout l’historique. Il accepte les mêmes paramètres family et variant.

GET /api/v1/cot/{cftc_code}/index/ — le COT Index à la manière de Briese : la place de la dernière position nette non commerciale (longues moins courtes) entre la position nette la plus basse et la plus haute d’une fenêtre glissante, sur une échelle de 0 à 100 (100 au plus haut de la fenêtre, 0 au plus bas, 50 quand la fenêtre est plate). Il est calculé sur le rapport Legacy ; la fenêtre par défaut est de 52 semaines, réglable de 4 à 520 avec lookback. Intégré, pour que vous n’ayez pas à le recalculer côté client.

Le paramètre variant. La CFTC publie chaque rapport en deux versions : Futures Uniquement, et Futures et Options Combinés. variant=futonly ou variant=combined choisit l’une des deux sur les endpoints d’historique, de dernier rapport et d’index. Sans ce paramètre, chaque rapport donne sa version par défaut : Futures Uniquement pour Legacy, Combinés pour Disaggregated, TFF et Supplemental (Supplemental n’existe qu’en version Combinés). Quand vous demandez une version, la réponse l’indique dans un champ variant.

Et un cinquième, GET /api/v1/demo/, qui renvoie un échantillon synthétique fixe sans authentification (10 requêtes par jour et par adresse réseau). Utilisez-le pour vérifier votre parser avant de vous abonner.

Authentification, limites de débit et détails pratiques

L’authentification se fait par jeton bearer : Authorization: Bearer cot_live_<32 hex>. Après l’abonnement, vous créez vos clés sur la page des clés API de votre compte. Nous ne conservons qu’une empreinte SHA-256 de chaque clé, jamais la clé elle-même, et vous pouvez révoquer une clé depuis la même page si elle fuit.

Les limites sont de 60 requêtes par minute et 500 requêtes par jour, par clé. C’est largement plus que ce dont a besoin l’usage typique « récupérer la dernière semaine de 30 marchés chaque vendredi ». Chaque requête servie porte les en-têtes X-RateLimit-Remaining, pour que vous puissiez ralentir avant d’atteindre le plafond ; au-delà, vous recevez un HTTP 429 avec un en-tête Retry-After.

Les erreurs reviennent dans une enveloppe stable : { "error": "<code_machine>", "message": "<texte_humain>" } avec un statut HTTP parlant. Le code machine est ce sur quoi votre code doit se brancher (unknown_token, rate_limited, no_data, invalid_variant, etc.) ; le message humain sert aux logs.

Un exemple minimal, en trois langages

Récupérer la dernière semaine de l’Euro FX (code CFTC 099741) demande à peu près autant de code qu’on l’imagine :

Python :

import requests
r = requests.get(
    "https://cot-reports.com/api/v1/cot/099741/latest/",
    headers={"Authorization": "Bearer cot_live_..."},
)
data = r.json()
print(data["row"]["noncomm_long"])

JavaScript / Node :

const res = await fetch(
  "https://cot-reports.com/api/v1/cot/099741/latest/",
  { headers: { Authorization: "Bearer cot_live_..." } }
)
const data = await res.json()
console.log(data.row.noncomm_long)

Bash / curl :

curl https://cot-reports.com/api/v1/cot/099741/latest/ \
  -H "Authorization: Bearer cot_live_..."

La spécification OpenAPI 3.0 se trouve à /api/v1/openapi.json si vous voulez générer automatiquement un client dans votre langage ; la page de documentation de l’API décrit chaque champ.

En quoi c’est différent de lire vous-même l’archive de la CFTC

Vous pourriez tout à fait lire directement l’archive publique de la CFTC (Socrata, l’API SODA) : elle est publique, gratuite et documentée. C’est exactement ce que nous faisons nous-mêmes en back end. Alors pourquoi payer 9,99 $/mois pour une couche normalisée au-dessus de la même source ?

Quelques raisons pour lesquelles certains jugent que cela en vaut la peine :

Les noms de colonnes. La CFTC livre ses données avec des noms de champs stables mais désordonnés : noncomm_postions_spread_all (avec la faute de frappe), change_in_noncomm_spead_all (avec une autre), des suffixes qui vont et viennent d’une famille à l’autre. Notre API renvoie des noms propres et prévisibles : noncomm_long, noncomm_short, comm_long, comm_short. Une chose de moins à maintenir.

Un seul schéma de noms pour les quatre familles. La CFTC publie Legacy, Disaggregated, TFF et Supplemental comme des jeux de données séparés, chacun avec sa propre orthographe (Supplemental renvoie même des clés en casse mixte). L’API les nomme tous de la même façon : chaque ligne a cftc_code, report_date, market_name et open_interest, et chaque groupe de traders suit un même modèle (<group>_long, <group>_short, change_<group>_long, pct_oi_<group>_long). Les groupes eux-mêmes diffèrent, parce que les rapports diffèrent : noncomm_long dans Legacy, managed_long et swap_long dans Disaggregated, dealer_long et asset_mgr_long dans TFF. Changer de family, c’est donc lire d’autres noms de groupes, pas apprendre d’autres orthographes.

COT Index intégré. L’indice de 0 à 100 tient en un appel au lieu d’une requête de fenêtre que vous maintenez vous-même.

Des limites lisibles. Nos limites sont publiées et indiquées à chaque réponse, et les données viennent de notre propre base, pas des serveurs de la CFTC. Socrata, la plateforme derrière l’archive de la CFTC, sert les requêtes sans jeton d’application depuis un réservoir partagé par adresse réseau et peut ralentir une adresse qui en envoie trop (HTTP 429) ; avec un jeton d’application gratuit, Socrata indique ne pas limiter un usage normal.

La maintenance. Si la CFTC renomme un champ, la correction se fait de notre côté, et votre code continue de lire les mêmes noms.

Comment ça s’intègre à côté du tableur et du Data Dump

Nous vendons trois produits de données, et ils couvrent trois façons de travailler différentes :

Le COT Report Spreadsheet (39 $, paiement unique) — pour le trader qui vit dans Excel. Ouvrez le fichier, voyez la dernière semaine, passez à la suite de votre journée. Il comprend un mode API facultatif (collez votre clé API dans une cellule de configuration, macros activées, et son onglet d’historique se charge depuis notre API normalisée).

La COT Data API (9,99 $/mois) — pour le trader qui code. N’importe quel langage, framework ou plateforme. Authentification bearer, limites publiées, JSON.

Le COT Data Dump (à partir de 49 $, paiement unique) — quand il vous faut toute l’archive historique d’un coup. Chaque marché, chaque famille (Legacy depuis 1986, les autres depuis 2006), en deux ZIP (un par variante CFTC : Futures Uniquement, et Futures et Options Combinés), chacun avec un manifeste SHA-256. Backtests, données d’entraînement pour le machine learning, analyse hors ligne.

Ce sont volontairement des produits différents, à des prix différents, parce qu’ils servent des usages différents. La plupart des lecteurs n’en ont besoin que d’un. Quelques-uns en prennent deux : l’API et le tableur (un flux codé et le confort d’Excel), ou l’API et le Data Dump (les mises à jour hebdomadaires et tout l’historique pour les backtests). À chacun ce qui lui convient.

Abonnez-vous sur la page de la COT Data API, créez votre première clé dans votre compte, et l’endpoint de démo vérifiera votre installation avant que vous n’écriviez une seule ligne de code de production. Résiliable à tout moment ; l’accès court jusqu’à la fin du mois payé, sans engagement.