Majoritatea cititorilor COT-Reports.com nu vor avea niciodată nevoie de un API. Site-ul acoperă folosirea zilnică, iar spreadsheet-ul pe cea săptămânală. Dar din când în când cineva ne scrie cu aceeași întrebare: „Aveți un API? Vreau să aduc datele COT în [Python / un dashboard intern / un bot de Discord / o bază Notion].” Avem. Se numește COT Data API, iar mai jos găsești ce face.
Pe scurt: un endpoint REST care întoarce același set de date Commitments of Traders pe care rulează site-ul și registrul Excel: autentificare bearer, JSON, coloane normalizate, istoric săptămânal. 9,99 $ pe lună, cu anulare oricând și acces până la sfârșitul perioadei plătite. Datele de bază sunt în domeniul public federal al SUA (17 USC §105); plătești munca din jurul lor: coloanele curățate, livrarea cu limite publicate și specificația OpenAPI 3.0.
Cine folosește de fapt un API pentru datele COT?
Trei profiluri, din experiența noastră:
Traderul sistematic. Rulează un model de poziționare în Python sau R. Citește noua publicare CFTC vineri după-amiază, își recalculează modelul în weekend și e gata înainte de deschiderea de luni. Nu vrea să scrie un scraper pentru CFTC și nici să gestioneze descărcări CSV; vrea requests.get(...) și un răspuns JSON.
Analistul care construiește un dashboard. Dashboard intern al echipei, panou Grafana, bază Notion, raport Tableau personalizat. Aduce ultima poziționare COT într-o vedere pe care colegii o verifică deja zilnic. Are nevoie de o structură JSON stabilă, care să nu se schimbe pe neașteptate.
Dezvoltatorul independent de unelte. Un bot de Discord care publică în fiecare vineri noul raport COT pe un server. O pagină web mică ce desenează poziționarea Managed Money lângă preț. O aplicație de telefon care trimite o notificare când poziționarea ajunge la marginea intervalului ei. Suprafețe diferite, aceeași nevoie de date.
Dacă felul tău de lucru seamănă cu unul dintre acestea, API-ul e făcut pentru tine. Dacă vrei doar să citești raportul, site-ul face asta gratuit.
Cele patru endpoint-uri
API-ul e restrâns intenționat. Patru endpoint-uri, fiecare face un singur lucru, toate întorc JSON:
GET /api/v1/markets/ — listează fiecare piață CFTC din catalogul nostru, cu numele, codul CFTC, categoria, bursa, unitatea contractului, familiile de rapoarte care o publică și datele primului și ultimului raport. Filtrezi cu category, family, tracked sau search și paginezi cu limit și offset. Îl apelezi o dată ca să afli codurile de care ai nevoie, apoi îți păstrezi propria listă.
GET /api/v1/cot/{cftc_code}/ — istoricul săptămânal al unei piețe. Implicit întoarce ultimele 520 de rapoarte săptămânale (circa 10 ani) din raportul Legacy. family=disagg|tff|supp trece la celelalte familii de rapoarte CFTC; from / to (AAAA-LL-ZZ) restrâng datele; limit stabilește câte rapoarte se întorc.
GET /api/v1/cot/{cftc_code}/latest/ — cel mai recent raport al unei piețe, când te interesează doar săptămâna curentă, nu tot istoricul. Primește aceiași parametri family și variant.
GET /api/v1/cot/{cftc_code}/index/ — COT Index în stilul lui Briese: unde se află ultima poziție netă non-commercial (long minus short) între cea mai mică și cea mai mare poziție netă dintr-o fereastră mobilă, pe o scară de la 0 la 100 (100 la maximul ferestrei, 0 la minim, 50 când fereastra e plată). Se calculează pe raportul Legacy; fereastra implicită e de 52 de săptămâni, reglabilă de la 4 la 520 cu lookback. E inclus, ca să nu fie nevoie să-l recalculezi la tine.
Parametrul variant. CFTC publică fiecare raport în două variante: Doar Contracte Futures, și Futures și Opțiuni Combinate. variant=futonly sau variant=combined alege una dintre ele pe endpoint-urile de istoric, de ultim raport și de index. Fără parametru, fiecare raport dă varianta lui implicită: Doar Contracte Futures pentru Legacy, Combinate pentru Disaggregated, TFF și Supplemental (Supplemental există doar ca Combinate). Când ceri o variantă, răspunsul o numește într-un câmp variant.
Plus un al cincilea, GET /api/v1/demo/, care întoarce un eșantion sintetic fix, fără autentificare (10 cereri pe zi pentru fiecare adresă de rețea). Îl folosești ca să-ți verifici parserul înainte de abonare.
Autentificare, limite de cereri și detaliile practice
Autentificarea se face cu un token bearer: Authorization: Bearer cot_live_<32 hex>. După abonare îți creezi cheile pe pagina de chei API din contul tău. Din fiecare cheie păstrăm doar amprenta SHA-256, niciodată cheia în sine, iar dacă o cheie ajunge pe mâini străine o poți revoca din aceeași pagină.
Limitele sunt de 60 de cereri pe minut și 500 de cereri pe zi, pentru fiecare cheie. E mult peste ce cere un flux obișnuit de tipul „iau ultima săptămână pentru 30 de piețe în fiecare vineri”. Fiecare cerere servită vine cu antetele X-RateLimit-Remaining, ca să poți încetini înainte de plafon; peste el primești HTTP 429, cu un antet Retry-After.
Erorile vin într-un format stabil: { "error": "<cod_mașină>", "message": "<text_uman>" }, cu un status HTTP care spune ceva. Codul-mașină e cel după care îți ramifici codul (unknown_token, rate_limited, no_data, invalid_variant și așa mai departe); mesajul în clar e pentru loguri.
Un exemplu minimal, în trei limbaje
Ca să iei ultima săptămână pentru Euro FX (cod CFTC 099741) îți trebuie cam atât cod cât te-ai aștepta:
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_..."Specificația OpenAPI 3.0 se află la /api/v1/openapi.json, dacă vrei să generezi automat un client în limbajul tău; pagina de documentație a API-ului descrie fiecare câmp.
Prin ce diferă de citirea directă a arhivei CFTC
Ai putea, desigur, să citești direct arhiva publică a CFTC (Socrata, API-ul SODA): e publică, gratuită și documentată. Exact asta facem și noi în back end. Atunci de ce să plătești 9,99 $/lună pentru un strat normalizat peste aceeași sursă?
Câteva motive pentru care unii decid că merită:
Numele coloanelor. CFTC își livrează datele cu nume de câmpuri stabile, dar dezordonate: noncomm_postions_spread_all (cu greșeala de tipar), change_in_noncomm_spead_all (cu încă una), sufixe care apar și dispar de la o familie la alta. API-ul nostru întoarce nume curate, previzibile: noncomm_long, noncomm_short, comm_long, comm_short. Un lucru mai puțin de întreținut.
O singură schemă de nume pentru toate cele patru familii. CFTC publică Legacy, Disaggregated, TFF și Supplemental ca seturi de date separate, fiecare cu ortografia lui (Supplemental întoarce chiar chei cu litere mari și mici amestecate). API-ul le numește pe toate la fel: fiecare rând are cftc_code, report_date, market_name și open_interest, iar fiecare grup de traderi urmează același tipar (<group>_long, <group>_short, change_<group>_long, pct_oi_<group>_long). Grupurile în sine diferă, pentru că diferă rapoartele: noncomm_long în Legacy, managed_long și swap_long în Disaggregated, dealer_long și asset_mgr_long în TFF. Când schimbi family, citești deci alte nume de grupuri, nu înveți alte ortografii.
COT Index inclus. Indicele de la 0 la 100 e un singur apel, în loc de o interogare pe fereastră pe care s-o întreții singur.
Limite pe care le poți citi. Limitele noastre sunt publicate și apar în fiecare răspuns, iar datele vin din baza noastră de date, nu de pe serverele CFTC. Socrata, platforma din spatele arhivei CFTC, servește cererile fără app token dintr-un fond comun pe adresă de rețea și poate încetini o adresă care trimite prea multe (HTTP 429); cu un app token gratuit, Socrata spune că nu limitează o folosire obișnuită.
Întreținerea. Dacă CFTC redenumește un câmp, corectura se face la noi, iar codul tău citește în continuare aceleași nume.
Cum se potrivește lângă spreadsheet și Data Dump
Vindem trei produse de date, iar ele acoperă trei feluri diferite de lucru:
COT Report Spreadsheet (39 $, o singură plată) — pentru traderul care lucrează în Excel. Deschizi fișierul, vezi ultima săptămână și îți vezi de zi. Include un mod API opțional (lipești cheia API într-o celulă de configurare, cu macrocomenzile activate, iar fila de istoric se încarcă din API-ul nostru normalizat).
COT Data API (9,99 $/lună) — pentru traderul care programează. Orice limbaj, orice framework, orice platformă. Autentificare bearer, limite publicate, JSON.
COT Data Dump (de la 49 $, o singură plată) — când ai nevoie de toată arhiva istorică dintr-odată. Fiecare piață, fiecare familie (Legacy din 1986, celelalte din 2006), în două arhive ZIP (câte una pentru fiecare variantă CFTC: Doar Contracte Futures, și Futures și Opțiuni Combinate), fiecare cu un manifest SHA-256. Backtesturi, date de antrenare pentru machine learning, analiză offline.
Sunt intenționat produse diferite, la prețuri diferite, pentru că servesc nevoi diferite. Majoritatea cititorilor au nevoie de unul singur. Câțiva iau două: API-ul plus spreadsheet-ul (un flux programat plus confortul Excel) sau API-ul plus Data Dump-ul (actualizările săptămânale plus tot istoricul pentru backtesturi). Cum ți se potrivește.
Abonează-te de pe pagina COT Data API, creează-ți prima cheie în cont, iar endpoint-ul demo îți verifică configurarea înainte să scrii o singură linie de cod de producție. Anulezi oricând; accesul ține până la sfârșitul lunii plătite, fără angajament.
