GRATIS · REFERENCIA API REST

COT Data API

Auth bearer · 60 req/min · 500 req/día

API REST para todo el dataset CFTC Commitments of Traders. Endpoints disponibles, autenticación, límites de tasa y códigos de error — todo lo que necesitas para integrar.

La API COT Data expone el mismo dataset que cot-reports.com: cada mercado CFTC, cada familia de informes (Legacy, Desagregado, TFF, Suplementario), columnas normalizadas, historial semanal. Suscríbete para generar un token; auth bearer en cada petición; límites de tasa abajo.

Esta referencia está solo en inglés — el resto del sitio está localizado en 6 idiomas, pero la superficie de la API (nombres de endpoints, sintaxis de parámetros, códigos de error) se comparte entre idiomas. Los ejemplos son en curl; los snippets de JavaScript funcionan en Node 18+ y cualquier navegador moderno.

Autenticación

Cada petición excepto /api/v1/demo/ requiere un token bearer. Suscríbete en cot-reports.com/api, genera un token desde /account/api, e inclúyelo en la cabecera Authorization.

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

Los tokens tienen 36 caracteres en total (prefijo cot_live_ + 32 caracteres hex). El token completo se muestra exactamente una vez en la creación; solo almacenamos un hash SHA-256. Los tokens perdidos no se pueden recuperar — revoca el viejo y genera uno nuevo.

Límites de tasa

Nivel	Por minuto	Por día	Notas
Entry (9.99 US$/mes)	60	500	Nivel por defecto con suscripción.
Demo (sin auth)	5	10	Por IP. Respuesta sintética estática.

Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset para la más estricta de las dos ventanas, más claves por ventana (-Minute / -Day) para telemetría más rica. En 429, Retry-After indica segundos de espera.

Endpoints

GET/api/v1/markets/Auth bearer

Lista cada mercado CFTC del dataset, con metadatos y pertenencia a familias de informes.

Parámetro	In	Tipo	Descripción
category	query	string	Match exacto sobre el campo de metadatos category.
tracked	query	boolean	Filtra al conjunto curado de mercados "populares".
family	query	string	Uno entre legacy, disagg, tff, supp.
search	query	string	Búsqueda por subcadena en market_name (insensible a mayúsculas).
limit	query	integer (1..2000)	Por defecto 500.
offset	query	integer	Offset de paginación, por defecto 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

Historial semanal de un mercado. Por defecto devuelve las últimas 520 semanas (10 años).

Parámetro	In	Tipo	Descripción
cftc_code *	path	string	Código CFTC del contract market, ej. 099741 para EURO FX.
family	query	string	Por defecto legacy. Uno entre legacy, disagg, tff, supp.
variant	query	futonly \| combined	Variante CFTC: futonly (Futures Only) o combined (Futures & Options Combined). Por defecto: la del informe (legacy: futonly; disagg, tff: combined; supp: solo combined). Si se indica, la respuesta la nombra en un campo variant.
from	query	YYYY-MM-DD	Límite inferior inclusivo en report_date.
to	query	YYYY-MM-DD	Límite superior inclusivo en report_date.
limit	query	integer (1..5000)	Por defecto 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

Informe más reciente de un mercado.

Parámetro	In	Tipo	Descripción
cftc_code *	path	string	Código CFTC del contract market.
family	query	string	Por defecto legacy.
variant	query	futonly \| combined	futonly o combined. Por defecto: la del informe; si se indica, la respuesta la nombra.

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 estilo Briese (percentil 0–100) para el último informe contra la ventana de lookback.

Parámetro	In	Tipo	Descripción
cftc_code *	path	string	Código CFTC del contract market.
lookback	query	integer (4..520)	Ventana en semanas. Por defecto 52.
variant	query	futonly \| combined	La variante del informe Legacy: futonly (por defecto) o combined.

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

GET/api/v1/demo/Sin auth

Muestra sintética estática. Sin auth. 10 req/día por IP. Úsala para validar la forma de las respuestas antes de suscribirte.

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

Servidor MCP (asistentes de IA)

Los datos COT también se sirven a los asistentes de IA mediante el Model Context Protocol en https://mcp.cot-reports.com. Tu clave de Data API también funciona allí, como cabecera Bearer — los mismos mercados y familias de informes, contados junto con tus llamadas a la API REST (una clave, un solo plan: los mismos límites en la API REST y en el servidor MCP). Todas las claves de una cuenta comparten estos límites, en la API REST y el servidor MCP juntos.

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

Configuración para cada app de IA

Códigos de error

código	HTTP	Cuándo
missing_header	401	No se envió la cabecera Authorization.
malformed_header	401	La cabecera Authorization no es Bearer + cot_live_<32 hex>.
unknown_token	401	El token no coincide con ninguna fila activa. Puede haber sido revocado o nunca generado.
revoked	403	El token existe pero fue revocado (suscripción cancelada, revocación manual).
account_suspended	403	La cuenta a la que pertenece este token está suspendida o cerrada. Sus tokens vuelven a funcionar cuando se levanta la suspensión; los de una cuenta cerrada se revocan junto con su suscripción y no vuelven si la cuenta se restaura.
rate_limited	429	Límite por minuto o por día excedido. La cabecera Retry-After indica los segundos de espera.
invalid_code	400	cftc_code en el path no pasó la validación alfanumérica.
invalid_family	400	Parámetro family no en legacy, disagg, tff, supp.
invalid_from	400	Parámetro from no es una fecha YYYY-MM-DD válida.
invalid_to	400	Parámetro to no es una fecha YYYY-MM-DD válida.
invalid_variant	400	El parámetro variant no es futonly ni combined.
variant_not_published	400	La CFTC no publica esa variante del informe (supp: solo Futures & Options Combined).
variant_unavailable	404	Esa variante del informe aún no está disponible.
no_data	404	No existe historial para el mercado solicitado en la familia solicitada.
db_error	500	Error interno de base de datos. Reintenta una vez; si persiste, contacta soporte.
internal	500	Error de servidor inesperado. Reintenta una vez; si persiste, contacta soporte.
demo_rate_limited	429	/api/v1/demo/ límite por hash de IP (10/día) alcanzado.

Ejemplo 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

Descripción legible por máquina de cada endpoint arriba. Importable en Postman, Insomnia, OpenAPI Generator, etc.

Descargar openapi.json

Uso aceptable

Un token por suscriptor. Compartir tokens entre usuarios o sistemas más allá de lo que cubre tu suscripción viola los Términos; revocamos tokens que muestran patrones de IP distribuidos.
Los datos CFTC en sí son de dominio público (17 USC §105). Puedes construir productos de pago encima, redistribuir resultados de consultas, o alimentar cualquier modelo. No restringimos la semántica de los datos.
El scraping masivo para recrear gratuitamente el Data Dump está prohibido — compra el Data Dump si es lo que necesitas; cuesta desde 49 US$ una sola vez y te ahorra el baile de rate-limits.
Eludir los límites de tasa (IPs rotatorias, tokens paralelos al mismo endpoint) viola los Términos. Logueamos por token + por hash de IP exactamente por esta razón.

Términos completos: /terms.