La mayoría de los lectores de COT-Reports.com nunca necesitará una API. El sitio cubre el uso diario; la hoja de cálculo, el semanal. Pero de vez en cuando alguien nos escribe para pedir lo mismo: «¿Tienen una API? Quiero llevar los datos COT a [Python / un panel interno / un bot de Discord / una base de Notion].» Sí. Se llama COT Data API, y esto es lo que hace.
En una frase: un endpoint REST que devuelve el mismo conjunto de datos Commitments of Traders en el que se basan el sitio y el libro de Excel: autenticación bearer, JSON, columnas normalizadas, historial semanal. 9,99 $ al mes, cancelable en cualquier momento, con acceso hasta el final del periodo pagado. Los datos de base son de dominio público federal de EE. UU. (17 USC §105); lo que pagas es el trabajo que los rodea: las columnas limpias, una entrega con límites publicados y la especificación OpenAPI 3.0.
¿Quién usa realmente una API para datos COT?
Tres perfiles, según nuestra experiencia:
El trader sistemático. Ejecuta un modelo de posicionamiento en Python o en R. Lee la nueva publicación de la CFTC el viernes por la tarde, recalcula el modelo durante el fin de semana y está listo antes de la apertura del lunes. No quiere escribir un scraper de la CFTC ni gestionar descargas de CSV; quiere requests.get(...) y un sobre JSON.
El analista que construye un panel. Panel interno del equipo, panel de Grafana, base de Notion, informe de Tableau a medida. Lleva el último posicionamiento COT a una vista que sus compañeros ya consultan cada día. Necesita una estructura JSON estable, que no cambie bajo sus pies.
El desarrollador independiente de herramientas. Un bot de Discord que cada viernes publica en un servidor la nueva salida COT. Una pequeña página web que dibuja el posicionamiento de Managed Money junto al precio. Una app de móvil que avisa cuando el posicionamiento llega al borde de su rango. Superficies distintas, la misma necesidad de datos.
Si tu forma de trabajar se parece a alguna de estas, la API está hecha para ti. Si solo quieres leer el informe, el sitio lo hace gratis.
Los cuatro endpoints
La API es deliberadamente compacta. Cuatro endpoints, cada uno hace una sola cosa, todos devuelven JSON:
GET /api/v1/markets/ — lista cada mercado CFTC de nuestro catálogo, con su nombre, código CFTC, categoría, bolsa, unidad del contrato, las familias de informes que lo publican y las fechas de su primer y último informe. Filtra con category, family, tracked o search; pagina con limit y offset. Llámalo una vez para encontrar los códigos que necesitas y luego guarda tu propia lista.
GET /api/v1/cot/{cftc_code}/ — el historial semanal de un mercado. Por defecto devuelve los últimos 520 informes semanales (unos 10 años) del informe Legacy. family=disagg|tff|supp cambia a las otras familias de informes de la CFTC; from / to (AAAA-MM-DD) acotan las fechas; limit fija cuántos informes se devuelven.
GET /api/v1/cot/{cftc_code}/latest/ — el informe más reciente de un mercado, cuando solo te interesa la semana actual, no todo el historial. Admite los mismos parámetros family y variant.
GET /api/v1/cot/{cftc_code}/index/ — el COT Index al estilo de Briese: dónde se sitúa la última posición neta no comercial (largas menos cortas) entre la posición neta más baja y la más alta de una ventana móvil, en una escala de 0 a 100 (100 en el máximo de la ventana, 0 en el mínimo, 50 cuando la ventana es plana). Se calcula sobre el informe Legacy; la ventana por defecto es de 52 semanas, ajustable de 4 a 520 con lookback. Integrado, para que no tengas que recalcularlo en el cliente.
El parámetro variant. La CFTC publica cada informe en dos versiones: Solo Futuros, y Futuros y Opciones Combinados. variant=futonly o variant=combined elige una en los endpoints de historial, último informe e índice. Sin el parámetro, cada informe da su versión por defecto: Solo Futuros para Legacy, Combinados para Disaggregated, TFF y Supplemental (Supplemental solo existe en versión Combinados). Cuando pides una versión, la respuesta la indica en un campo variant.
Y un quinto, GET /api/v1/demo/, que devuelve una muestra sintética fija sin autenticación (10 peticiones al día por dirección de red). Úsalo para comprobar tu parser antes de suscribirte.
Autenticación, límites de uso y los detalles prácticos
La autenticación es un token bearer: Authorization: Bearer cot_live_<32 hex>. Tras suscribirte, creas tus claves en la página de claves API de tu cuenta. De cada clave guardamos solo un hash SHA-256, nunca la clave en sí, y puedes revocar una clave desde la misma página si se filtra.
Los límites son 60 peticiones por minuto y 500 peticiones al día, por clave. Es mucho más de lo que necesita el uso típico de «traer la última semana de 30 mercados cada viernes». Cada petición atendida lleva las cabeceras X-RateLimit-Remaining, para que puedas frenar antes de llegar al tope; por encima, recibes un HTTP 429 con una cabecera Retry-After.
Los errores vuelven en un sobre estable: { "error": "<código_máquina>", "message": "<texto_humano>" } con un estado HTTP significativo. El código de máquina es en lo que debe basarse tu código (unknown_token, rate_limited, no_data, invalid_variant, etc.); el mensaje legible es para los logs.
Un ejemplo mínimo, en tres lenguajes
Traer la última semana del Euro FX (código CFTC 099741) requiere más o menos el código que esperas:
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 especificación OpenAPI 3.0 está en /api/v1/openapi.json por si quieres generar automáticamente un cliente en tu lenguaje; la página de documentación de la API describe cada campo.
En qué se diferencia de leer tú mismo el archivo de la CFTC
Podrías leer directamente el archivo público de la CFTC (Socrata, la API SODA): es público, gratuito y está documentado. Es exactamente lo que hacemos nosotros en el back end. Entonces, ¿por qué pagar 9,99 $/mes por una capa normalizada sobre la misma fuente?
Algunas razones por las que hay quien decide que vale la pena:
Los nombres de columnas. La CFTC publica sus datos con nombres de campo estables pero desordenados: noncomm_postions_spread_all (con la errata), change_in_noncomm_spead_all (con otra), sufijos que van y vienen de una familia a otra. Nuestra API devuelve nombres limpios y predecibles: noncomm_long, noncomm_short, comm_long, comm_short. Una cosa menos que mantener.
Un solo esquema de nombres para las cuatro familias. La CFTC publica Legacy, Disaggregated, TFF y Supplemental como conjuntos de datos separados, cada uno con su propia grafía (Supplemental incluso devuelve claves con mayúsculas y minúsculas mezcladas). La API los nombra a todos igual: cada fila tiene cftc_code, report_date, market_name y open_interest, y cada grupo de traders sigue un mismo patrón (<group>_long, <group>_short, change_<group>_long, pct_oi_<group>_long). Los grupos en sí cambian, porque los informes cambian: noncomm_long en Legacy, managed_long y swap_long en Disaggregated, dealer_long y asset_mgr_long en TFF. Cambiar de family significa, por tanto, leer otros nombres de grupo, no aprender otras grafías.
COT Index integrado. El índice de 0 a 100 es una sola llamada en lugar de una consulta de ventana que mantienes tú.
Límites que puedes leer. Nuestros límites están publicados y se indican en cada respuesta, y los datos salen de nuestra propia base, no de los servidores de la CFTC. Socrata, la plataforma detrás del archivo de la CFTC, atiende las peticiones sin app token desde un fondo compartido por dirección de red y puede frenar una dirección que envíe demasiadas (HTTP 429); con un app token gratuito, Socrata afirma no limitar un uso normal.
El mantenimiento. Si la CFTC cambia el nombre de un campo, la corrección se hace de nuestro lado y tu código sigue leyendo los mismos nombres.
Cómo encaja junto a la hoja de cálculo y al Data Dump
Vendemos tres productos de datos, y cubren tres formas de trabajar distintas:
El COT Report Spreadsheet (39 $, pago único) — para el trader que vive en Excel. Abres el archivo, ves la última semana y sigues con tu día. Incluye un modo API opcional (pegas tu clave API en una celda de configuración, con las macros activadas, y su pestaña de historial se carga desde nuestra API normalizada).
La COT Data API (9,99 $/mes) — para el trader que programa. Cualquier lenguaje, framework o plataforma. Autenticación bearer, límites publicados, JSON.
El COT Data Dump (desde 49 $, pago único) — cuando necesitas todo el archivo histórico de una vez. Cada mercado, cada familia (Legacy desde 1986, las demás desde 2006), en dos ZIP (uno por variante CFTC: Solo Futuros, y Futuros y Opciones Combinados), cada uno con un manifiesto SHA-256. Backtests, datos de entrenamiento para machine learning, análisis sin conexión.
Son productos distintos a propósito, con precios distintos, porque sirven usos distintos. La mayoría de los lectores solo necesita uno. Algunos compran dos: la API más la hoja de cálculo (un flujo programado más la comodidad de Excel), o la API más el Data Dump (las actualizaciones semanales más todo el historial para los backtests). Lo que mejor encaje.
Suscríbete en la página de la COT Data API, crea tu primera clave en tu cuenta, y el endpoint de demo comprobará tu configuración antes de que escribas una sola línea de código de producción. Cancela cuando quieras; el acceso dura hasta el final del mes pagado, sin permanencia.
