La maggior parte dei lettori di COT-Reports.com non avrà mai bisogno di un’API. Il sito copre l’uso quotidiano; il foglio di calcolo quello settimanale. Ma ogni tanto qualcuno ci scrive per chiedere la stessa cosa: «Avete un’API? Voglio portare i dati COT in [Python / una dashboard interna / un bot Discord / un database Notion].» Sì. Si chiama COT Data API, ed ecco che cosa fa.
In una frase: un endpoint REST che restituisce lo stesso dataset Commitments of Traders su cui si basano il sito e la cartella di lavoro Excel: autenticazione bearer, JSON, colonne normalizzate, storico settimanale. 9,99 $ al mese, disdicibile in qualsiasi momento, con accesso fino alla fine del periodo pagato. I dati di base sono di pubblico dominio federale statunitense (17 USC §105); ciò che paghi è il lavoro intorno: le colonne ripulite, una consegna con limiti pubblicati e la specifica OpenAPI 3.0.
Chi usa davvero un’API per i dati COT?
Tre profili, secondo la nostra esperienza:
Il trader sistematico. Fa girare un modello di posizionamento in Python o in R. Legge la nuova pubblicazione della CFTC il venerdì pomeriggio, ricalcola il modello nel fine settimana ed è pronto prima dell’apertura del lunedì. Non vuole scrivere uno scraper per la CFTC né gestire download di CSV; vuole requests.get(...) e una busta JSON.
L’analista che costruisce una dashboard. Dashboard interna del team, pannello Grafana, database Notion, report Tableau su misura. Porta l’ultimo posizionamento COT in una vista che i colleghi controllano già ogni giorno. Ha bisogno di una struttura JSON stabile, che non cambi sotto i suoi piedi.
Lo sviluppatore indipendente di strumenti. Un bot Discord che ogni venerdì pubblica su un server la nuova uscita COT. Una piccola pagina web che disegna il posizionamento Managed Money accanto al prezzo. Un’app per telefono che invia una notifica quando il posizionamento arriva al bordo del suo intervallo. Superfici diverse, lo stesso bisogno di dati.
Se il tuo modo di lavorare somiglia a uno di questi, l’API è fatta per te. Se vuoi solo leggere il report, il sito lo fa gratis.
I quattro endpoint
L’API è volutamente essenziale. Quattro endpoint, ognuno fa una cosa sola, tutti restituiscono JSON:
GET /api/v1/markets/ — elenca ogni mercato CFTC del nostro catalogo, con nome, codice CFTC, categoria, borsa, unità del contratto, le famiglie di report che lo pubblicano e le date del primo e dell’ultimo report. Filtra con category, family, tracked o search; sfoglia le pagine con limit e offset. Chiamalo una volta per trovare i codici che ti servono, poi tieni la tua lista.
GET /api/v1/cot/{cftc_code}/ — lo storico settimanale di un mercato. Per impostazione predefinita restituisce gli ultimi 520 report settimanali (circa 10 anni) del report Legacy. family=disagg|tff|supp passa alle altre famiglie di report della CFTC; from / to (AAAA-MM-GG) restringono le date; limit stabilisce quanti report tornano.
GET /api/v1/cot/{cftc_code}/latest/ — il report più recente di un mercato, quando ti serve solo la settimana corrente, non tutto lo storico. Accetta gli stessi parametri family e variant.
GET /api/v1/cot/{cftc_code}/index/ — il COT Index alla maniera di Briese: dove si colloca l’ultima posizione netta non commerciale (lunghe meno corte) tra la posizione netta più bassa e quella più alta di una finestra mobile, su una scala da 0 a 100 (100 al massimo della finestra, 0 al minimo, 50 quando la finestra è piatta). È calcolato sul report Legacy; la finestra predefinita è di 52 settimane, regolabile da 4 a 520 con lookback. Integrato, così non devi ricalcolarlo lato client.
Il parametro variant. La CFTC pubblica ogni report in due versioni: Solo Futures, e Futures e Opzioni Combinati. variant=futonly o variant=combined ne sceglie una sugli endpoint di storico, ultimo report e indice. Senza il parametro, ogni report dà la sua versione predefinita: Solo Futures per Legacy, Combinati per Disaggregated, TFF e Supplemental (Supplemental esiste solo nella versione Combinati). Quando chiedi una versione, la risposta la indica in un campo variant.
In più un quinto, GET /api/v1/demo/, che restituisce un campione sintetico fisso senza autenticazione (10 richieste al giorno per indirizzo di rete). Usalo per verificare il tuo parser prima di abbonarti.
Autenticazione, rate limit e dettagli pratici
L’autenticazione è un token bearer: Authorization: Bearer cot_live_<32 hex>. Dopo l’abbonamento crei le tue chiavi nella pagina delle chiavi API del tuo account. Di ogni chiave conserviamo solo un hash SHA-256, mai la chiave stessa, e puoi revocare una chiave dalla stessa pagina se finisce nelle mani sbagliate.
I limiti sono 60 richieste al minuto e 500 richieste al giorno, per chiave. È molto più di quanto serve al tipico «prendere l’ultima settimana di 30 mercati ogni venerdì». Ogni richiesta servita porta gli header X-RateLimit-Remaining, così puoi rallentare prima di arrivare al tetto; oltre, ricevi un HTTP 429 con un header Retry-After.
Gli errori tornano in una busta stabile: { "error": "<codice_macchina>", "message": "<testo_umano>" } con uno stato HTTP significativo. Il codice macchina è ciò su cui il tuo codice deve basarsi (unknown_token, rate_limited, no_data, invalid_variant e così via); il messaggio leggibile è per i log.
Un esempio minimo, in tre linguaggi
Prendere l’ultima settimana dell’Euro FX (codice CFTC 099741) richiede più o meno il codice che ti aspetti:
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 specifica OpenAPI 3.0 si trova in /api/v1/openapi.json, se vuoi generare automaticamente un client nel tuo linguaggio; la pagina della documentazione API descrive ogni campo.
In cosa differisce dal leggere da soli l’archivio della CFTC
Potresti senz’altro leggere direttamente l’archivio pubblico della CFTC (Socrata, l’API SODA): è pubblico, gratuito e documentato. È esattamente ciò che facciamo noi nel back end. Allora perché pagare 9,99 $/mese per uno strato normalizzato sopra la stessa fonte?
Alcuni motivi per cui c’è chi decide che ne vale la pena:
I nomi delle colonne. La CFTC distribuisce i suoi dati con nomi di campo stabili ma disordinati: noncomm_postions_spread_all (con il refuso), change_in_noncomm_spead_all (con un altro), suffissi che vanno e vengono da una famiglia all’altra. La nostra API restituisce nomi puliti e prevedibili: noncomm_long, noncomm_short, comm_long, comm_short. Una cosa in meno da mantenere.
Un solo schema di nomi per le quattro famiglie. La CFTC pubblica Legacy, Disaggregated, TFF e Supplemental come dataset separati, ciascuno con la sua grafia (Supplemental restituisce perfino chiavi con maiuscole e minuscole miste). L’API li chiama tutti allo stesso modo: ogni riga ha cftc_code, report_date, market_name e open_interest, e ogni gruppo di trader segue uno stesso schema (<group>_long, <group>_short, change_<group>_long, pct_oi_<group>_long). I gruppi stessi cambiano, perché cambiano i report: noncomm_long in Legacy, managed_long e swap_long in Disaggregated, dealer_long e asset_mgr_long in TFF. Cambiare family vuol dire quindi leggere altri nomi di gruppo, non imparare altre grafie.
COT Index integrato. L’indice da 0 a 100 è una sola chiamata invece di una query a finestra da mantenere tu.
Limiti leggibili. I nostri limiti sono pubblicati e indicati in ogni risposta, e i dati arrivano dal nostro database, non dai server della CFTC. Socrata, la piattaforma dietro l’archivio della CFTC, serve le richieste senza app token da una riserva condivisa per indirizzo di rete e può rallentare un indirizzo che ne invia troppe (HTTP 429); con un app token gratuito, Socrata dichiara di non limitare un uso normale.
La manutenzione. Se la CFTC rinomina un campo, la correzione avviene dalla nostra parte e il tuo codice continua a leggere gli stessi nomi.
Come si integra accanto al foglio di calcolo e al Data Dump
Vendiamo tre prodotti di dati, e coprono tre modi di lavorare diversi:
Il COT Report Spreadsheet (39 $, una tantum) — per il trader che vive in Excel. Apri il file, vedi l’ultima settimana, prosegui con la giornata. Include una modalità API facoltativa (incolli la tua chiave API in una cella di configurazione, con le macro attivate, e la sua scheda dello storico si carica dalla nostra API normalizzata).
La COT Data API (9,99 $/mese) — per il trader che programma. Qualsiasi linguaggio, framework o piattaforma. Autenticazione bearer, limiti pubblicati, JSON.
Il COT Data Dump (da 49 $, una tantum) — quando ti serve tutto l’archivio storico in una volta. Ogni mercato, ogni famiglia (Legacy dal 1986, le altre dal 2006), in due ZIP (uno per variante CFTC: Solo Futures, e Futures e Opzioni Combinati), ciascuno con un manifest SHA-256. Backtest, dati di addestramento per il machine learning, analisi offline.
Sono volutamente prodotti diversi, a prezzi diversi, perché servono usi diversi. La maggior parte dei lettori ne usa uno solo. Alcuni ne prendono due: l’API più il foglio di calcolo (un flusso programmato più la comodità di Excel), oppure l’API più il Data Dump (gli aggiornamenti settimanali più tutto lo storico per i backtest). Come preferisci.
Abbonati dalla pagina della COT Data API, crea la tua prima chiave nel tuo account, e l’endpoint demo verificherà la tua configurazione prima che tu scriva una sola riga di codice di produzione. Disdici quando vuoi; l’accesso dura fino alla fine del mese pagato, senza vincoli.
