GRATUIT · REFERINȚĂ API REST

COT Data API

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

API REST pentru întregul dataset CFTC Commitments of Traders. Endpoint-uri disponibile, autentificare, rate limits și coduri de eroare — tot ce-ți trebuie pentru integrare.

API-ul COT Data expune același dataset ca și cot-reports.com: fiecare piață CFTC, fiecare familie de rapoarte (Legacy, Dezagregat, TFF, Suplimentar), coloane normalizate, istoric săptămânal. Abonează-te pentru a genera un token; auth bearer la fiecare cerere; rate limits mai jos.

Această referință este doar în engleză — restul site-ului este localizat în 6 limbi, dar suprafața API-ului (numele endpoint-urilor, sintaxa parametrilor, codurile de eroare) este comună tuturor limbilor. Exemplele sunt în curl; snippet-urile JavaScript funcționează în Node 18+ și orice browser modern.

Autentificare

Fiecare cerere cu excepția /api/v1/demo/ necesită un token bearer. Abonează-te pe cot-reports.com/api, generează un token din /account/api și include-l în header-ul Authorization.

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

Token-urile au 36 de caractere în total (prefix cot_live_ + 32 de caractere hex). Token-ul complet este afișat exact o dată la creare; păstrăm doar un hash SHA-256. Token-urile pierdute nu pot fi recuperate — revocă-l pe cel vechi și generează unul nou.

Limite de rată

Nivel	Pe minut	Pe zi	Note
Entry (9.99 $/lună)	60	500	Nivel implicit la abonament.
Demo (fără auth)	5	10	Per IP. Răspuns sintetic static.

Fiecare răspuns include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset pentru cea mai strictă dintre cele două ferestre, plus chei per fereastră (-Minute / -Day) pentru telemetrie mai bogată. La 429, Retry-After indică secundele de așteptare.

Endpoint-uri

GET/api/v1/markets/Auth bearer

Listează fiecare piață CFTC din dataset, cu metadate și apartenența la familii de rapoarte.

Parametru	În	Tip	Descriere
category	query	string	Match exact pe câmpul metadata category.
tracked	query	boolean	Filtrează la setul curat de piețe „populare".
family	query	string	Una dintre legacy, disagg, tff, supp.
search	query	string	Căutare pe substring în market_name (case-insensitive).
limit	query	integer (1..2000)	Implicit 500.
offset	query	integer	Offset de paginare, implicit 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

Istoric săptămânal pentru o piață. Implicit returnează ultimele 520 de săptămâni (10 ani).

Parametru	În	Tip	Descriere
cftc_code *	path	string	Codul CFTC al contract market-ului, ex. 099741 pentru EURO FX.
family	query	string	Implicit legacy. Una dintre legacy, disagg, tff, supp.
variant	query	futonly \| combined	Varianta CFTC: futonly (Futures Only) sau combined (Futures & Options Combined). Implicit: a raportului (legacy: futonly; disagg, tff: combined; supp: doar combined). Dacă o dai, răspunsul o numește într-un câmp variant.
from	query	YYYY-MM-DD	Limită inferioară inclusivă pe report_date.
to	query	YYYY-MM-DD	Limită superioară inclusivă pe report_date.
limit	query	integer (1..5000)	Implicit 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

Cel mai recent raport pentru o piață.

Parametru	În	Tip	Descriere
cftc_code *	path	string	Codul CFTC al contract market-ului.
family	query	string	Implicit legacy.
variant	query	futonly \| combined	futonly sau combined. Implicit: a raportului; dacă o dai, răspunsul o numește.

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 în stil Briese (percentilă 0–100) pentru cel mai recent raport raportat la fereastra de lookback.

Parametru	În	Tip	Descriere
cftc_code *	path	string	Codul CFTC al contract market-ului.
lookback	query	integer (4..520)	Fereastră în săptămâni. Implicit 52.
variant	query	futonly \| combined	Varianta raportului Legacy: futonly (implicit) sau combined.

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

GET/api/v1/demo/Fără auth

Eșantion sintetic static. Fără auth. 10 req/zi per IP. Folosește-l ca să validezi forma răspunsurilor înainte de abonament.

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

Server MCP (asistenți AI)

Datele COT sunt servite și asistenților AI prin Model Context Protocol la adresa https://mcp.cot-reports.com. Cheia ta Data API funcționează și acolo, ca header Bearer — aceleași piețe și familii de rapoarte, numărate împreună cu apelurile tale către API-ul REST (o cheie, un singur plan: aceleași limite pe API-ul REST și pe serverul MCP). Toate cheile unui cont împart aceste limite, pe API-ul REST și pe serverul MCP împreună.

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

Configurare pentru fiecare aplicație AI

Coduri de eroare

cod	HTTP	Când
missing_header	401	Header-ul Authorization nu a fost trimis.
malformed_header	401	Header-ul Authorization nu este Bearer + cot_live_<32 hex>.
unknown_token	401	Token-ul nu corespunde niciunui rând activ. Poate a fost revocat sau nu a fost generat niciodată.
revoked	403	Token-ul există dar a fost revocat (abonament anulat, revocare manuală).
account_suspended	403	Contul căruia îi aparține token-ul este suspendat sau închis. Token-urile lui funcționează din nou când suspendarea este ridicată; token-urile unui cont închis sunt revocate odată cu abonamentul și nu revin dacă, ulterior, contul este restaurat.
rate_limited	429	Limita per minut sau per zi depășită. Header-ul Retry-After indică secundele de așteptare.
invalid_code	400	cftc_code din path nu a trecut validarea alfanumerică.
invalid_family	400	Parametrul family nu este în legacy, disagg, tff, supp.
invalid_from	400	Parametrul from nu este o dată YYYY-MM-DD validă.
invalid_to	400	Parametrul to nu este o dată YYYY-MM-DD validă.
invalid_variant	400	Parametrul variant nu este futonly sau combined.
variant_not_published	400	CFTC nu publică această variantă a raportului (supp: doar Futures & Options Combined).
variant_unavailable	404	Această variantă a raportului nu este încă disponibilă.
no_data	404	Nu există istoric pentru piața cerută în familia cerută.
db_error	500	Eroare internă de bază de date. Reîncearcă o dată; dacă persistă, contactează support-ul.
internal	500	Eroare neașteptată de server. Reîncearcă o dată; dacă persistă, contactează support-ul.
demo_rate_limited	429	/api/v1/demo/ limita per hash IP (10/zi) atinsă.

Exemplu 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

Descriere machine-readable a fiecărui endpoint de mai sus. Importabilă în Postman, Insomnia, OpenAPI Generator etc.

Descarcă openapi.json

Utilizare acceptabilă

Un token per abonat. Partajarea token-urilor între utilizatori sau sisteme dincolo de ce acoperă abonamentul tău încalcă Termenii; revocăm token-urile care arată pattern-uri de IP distribuite.
Datele CFTC în sine sunt de domeniu public (17 USC §105). Poți construi produse plătite peste ele, redistribui rezultatele interogărilor sau le poți alimenta în orice model. Nu restricționăm semantica datelor.
Scraping-ul masiv cu scopul de a recrea gratuit Data Dump-ul este interzis — cumpără Data Dump dacă asta îți trebuie; costă de la 49 $ o singură dată și te scutește de dansul rate-limit-urilor.
Eludarea rate-limit-urilor (IP-uri rotative, token-uri paralele către același endpoint) încalcă Termenii. Logăm per token + per hash IP exact pentru acest motiv.

Termeni compleți: /terms.