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/marketsAuth 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.
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}/latestAuth 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.

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

GET/api/v1/cot/{cftc_code}/indexAuth 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.

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

GET/api/v1/demoFă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

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ă).
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ă.
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ă 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.