GRATIS · RIFERIMENTO API REST

COT Data API

Auth bearer · 60 req/min · 500 req/giorno

API REST per l'intero dataset CFTC Commitments of Traders. Endpoint disponibili, autenticazione, rate limit e codici di errore — tutto ciò che serve per integrare.

L'API COT Data espone lo stesso dataset di cot-reports.com: ogni mercato CFTC, ogni famiglia di report (Legacy, Disaggregato, TFF, Supplementare), colonne normalizzate, storico settimanale. Abbonati per generare un token; auth bearer su ogni richiesta; rate limit qui sotto.

Questo riferimento è solo in inglese — il resto del sito è localizzato in 6 lingue, ma la superficie API (nomi degli endpoint, sintassi dei parametri, codici di errore) è condivisa tra le lingue. Gli esempi sono in curl; gli snippet JavaScript funzionano in Node 18+ e in qualsiasi browser moderno.

Autenticazione

Ogni richiesta tranne /api/v1/demo/ richiede un token bearer. Abbonati su cot-reports.com/api, genera un token da /account/api, e includilo nell'header Authorization.

curl -H "Authorization: Bearer cot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://cot-reports.com/api/v1/markets/

I token sono di 36 caratteri totali (prefisso cot_live_ + 32 caratteri hex). Il token completo viene mostrato esattamente una volta alla creazione; conserviamo solo un hash SHA-256. I token persi non sono recuperabili — revoca il vecchio e generane uno nuovo.

Rate limit

Piano	Al minuto	Al giorno	Note
Entry (9.99 $/mese)	60	500	Piano predefinito con abbonamento.
Demo (senza auth)	5	10	Per IP. Risposta sintetica statica.

Ogni risposta contiene X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset per la più stretta delle due finestre, più chiavi per finestra (-Minute / -Day) per telemetria più ricca. Su 429, Retry-After indica i secondi di attesa.

Endpoint

GET/api/v1/markets/Auth bearer

Elenca tutti i mercati CFTC nel dataset, con metadati e appartenenza alle famiglie di report.

Parametro	In	Tipo	Descrizione
category	query	string	Match esatto sul campo metadata category.
tracked	query	boolean	Filtra al set curato di mercati "popolari".
family	query	string	Uno tra legacy, disagg, tff, supp.
search	query	string	Ricerca per sottostringa su market_name (case-insensitive).
limit	query	integer (1..2000)	Predefinito 500.
offset	query	integer	Offset di paginazione, predefinito 0.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/markets/?family=legacy&tracked=true&limit=10"

GET/api/v1/cot/{cftc_code}/Auth bearer

Storico settimanale per un mercato. Predefinito: ultime 520 settimane (10 anni).

Parametro	In	Tipo	Descrizione
cftc_code *	path	string	Codice CFTC del contract market, es. 099741 per EURO FX.
family	query	string	Predefinito legacy. Uno tra legacy, disagg, tff, supp.
variant	query	futonly \| combined	Variante CFTC: futonly (Futures Only) o combined (Futures & Options Combined). Predefinita: quella del report (legacy: futonly; disagg, tff: combined; supp: solo combined). Se indicata, la risposta la riporta in un campo variant.
from	query	YYYY-MM-DD	Limite inferiore inclusivo su report_date.
to	query	YYYY-MM-DD	Limite superiore inclusivo su report_date.
limit	query	integer (1..5000)	Predefinito 520.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/?from=2024-01-01"

GET/api/v1/cot/{cftc_code}/latest/Auth bearer

Report più recente per un mercato.

Parametro	In	Tipo	Descrizione
cftc_code *	path	string	Codice CFTC del contract market.
family	query	string	Predefinito legacy.
variant	query	futonly \| combined	futonly o combined. Predefinita: quella del report; se indicata, la risposta la riporta.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/latest/?variant=combined"

GET/api/v1/cot/{cftc_code}/index/Auth bearer

COT Index in stile Briese (percentile 0–100) per l'ultimo report rispetto alla finestra di lookback.

Parametro	In	Tipo	Descrizione
cftc_code *	path	string	Codice CFTC del contract market.
lookback	query	integer (4..520)	Finestra in settimane. Predefinito 52.
variant	query	futonly \| combined	La variante del report Legacy: futonly (predefinita) o combined.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/index/?lookback=156"

GET/api/v1/demo/Senza auth

Campione sintetico statico. Senza auth. 10 req/giorno per IP. Usalo per validare la forma delle risposte prima di abbonarti.

curl https://cot-reports.com/api/v1/demo/

Server MCP (assistenti IA)

I dati COT sono serviti anche agli assistenti IA tramite il Model Context Protocol all'indirizzo https://mcp.cot-reports.com. La tua chiave Data API funziona anche lì, come intestazione Bearer — stessi mercati e famiglie di report, conteggiati insieme alle tue chiamate all'API REST (una chiave, un solo piano: gli stessi limiti sull'API REST e sul server MCP). Tutte le chiavi di un account condividono questi limiti, sull'API REST e sul server MCP insieme.

claude mcp add --transport http cot-reports https://mcp.cot-reports.com \
  --header "Authorization: Bearer cot_live_<32 hex>"

Configurazione per ogni app IA

Codici di errore

codice	HTTP	Quando
missing_header	401	L'header Authorization non è stato inviato.
malformed_header	401	L'header Authorization non è Bearer + cot_live_<32 hex>.
unknown_token	401	Il token non corrisponde a nessuna riga attiva. Potrebbe essere stato revocato o mai generato.
revoked	403	Il token esiste ma è stato revocato (abbonamento cancellato, revoca manuale).
account_suspended	403	L'account a cui appartiene questo token è sospeso o chiuso. I suoi token tornano a funzionare quando la sospensione viene revocata; quelli di un account chiuso vengono revocati insieme all'abbonamento e non tornano se l'account viene ripristinato.
rate_limited	429	Limite al minuto o al giorno superato. L'header Retry-After indica i secondi di attesa.
invalid_code	400	cftc_code nel path non ha passato la validazione alfanumerica.
invalid_family	400	Parametro family non in legacy, disagg, tff, supp.
invalid_from	400	Parametro from non è una data YYYY-MM-DD valida.
invalid_to	400	Parametro to non è una data YYYY-MM-DD valida.
invalid_variant	400	Il parametro variant non è futonly né combined.
variant_not_published	400	La CFTC non pubblica questa variante del report (supp: solo Futures & Options Combined).
variant_unavailable	404	Questa variante del report non è ancora disponibile.
no_data	404	Nessuno storico per il mercato richiesto nella famiglia richiesta.
db_error	500	Errore database interno. Riprovare una volta; se persiste, contattare il supporto.
internal	500	Errore server inatteso. Riprovare una volta; se persiste, contattare il supporto.
demo_rate_limited	429	/api/v1/demo/ limite per hash IP (10/giorno) raggiunto.

Esempio JavaScript

const r = await fetch('https://cot-reports.com/api/v1/cot/099741/index/?lookback=52', {
  headers: { Authorization: `Bearer ${process.env.COT_API_TOKEN}` },
})
if (!r.ok) {
  const { error, message } = await r.json()
  throw new Error(`COT API ${r.status} ${error}: ${message}`)
}
const { cot_index, latest_report_date } = await r.json()
console.log(`COT Index for EURO FX as of ${latest_report_date}: ${cot_index}`)

Spec OpenAPI 3.0

Descrizione machine-readable di ogni endpoint sopra. Importabile in Postman, Insomnia, OpenAPI Generator, ecc.

Scarica openapi.json

Uso consentito

Un token per abbonato. La condivisione di token tra utenti o sistemi oltre quanto coperto dall'abbonamento è una violazione dei Termini; revochiamo i token che mostrano pattern di IP distribuiti.
I dati CFTC stessi sono di pubblico dominio (17 USC §105). Puoi costruire prodotti a pagamento sopra, ridistribuire risultati di query, o alimentare qualsiasi modello. Non restringiamo la semantica dei dati.
Lo scraping massivo per ricreare gratuitamente il Data Dump è vietato — compra il Data Dump se è ciò di cui hai bisogno; costa da 49 $ una tantum e ti risparmia il balletto dei rate-limit.
L'aggiramento dei rate limit (IP rotanti, token paralleli verso lo stesso endpoint) viola i Termini. Loggiamo per token + per hash IP esattamente per questo motivo.

Termini completi: /terms.