Ir al contenido
API v1 · 2026-11-17

Documentación de la API

Una API de operaciones de directivos que cubre 46 mercados (AMF · SEC · BaFin · SIX SER · RNS · SEDI · Consob · CNMV · AFM · FSMA · Oslo · Helsinki · Copenhagen · ASX · FMA · CVM · HKEX · BSE-Sofia · Tadawul · DART · EDINET · SSE · SZSE · SEBI · KNF · PSE · NZX · JSE) en un esquema único. Importes normalizados en EUR/USD. Backtests minoristas T+30/T+90/T+365 incluidos. Scoring transparente (7 factores desglosables). Nativa para IA: servidor MCP para Claude, Cursor, Windsurf. API en los planes Pro y Quant.

Swagger UI interactivo ↗Servidor MCP para IA ↗Generar una clave API ↗Especificación OpenAPI JSON ↗Comparativa con Quiver, OpenInsider ↗
Acceso a la API · beta privada
Insiders Trades está en beta privada. La API y el servidor MCP se desbloquean con los planes Pro y Quant. Únete a la lista de espera para obtener acceso anticipado (334 solicitudes/día, 5 años de historial en la API, MCP, alertas por email).
Respuesta de ejemplo · GET /v1/declarations
$ 
Primeros pasos

Inicio rápido

Tres pasos para hacer tu primera solicitud:

  1. Crea una cuenta y ve a Mi cuenta → Claves API.
  2. Genera una clave con nombre (p. ej. "Production bot"). Cópiala de inmediato, no se volverá a mostrar.
  3. Añade la cabecera Authorization: Bearer <key> a cada solicitud.
curl https://insiders-trades.com/api/v1/me \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Seguridad

Autenticación

Cada solicitud debe incluir exactamente una clave API válida y no revocada. Se aceptan dos formatos:

  • Authorization: Bearer <key> · estándar, recomendado.
  • X-Api-Key: <key> · alternativa si tu cliente HTTP no gestiona bien la cabecera Authorization.
La clave se muestra una sola vez al crearla. Si la pierdes, revócala y genera una nueva. Límite: 10 claves activas por cuenta. Las claves revocadas siguen visibles en el historial.

Formato de las claves

text
sit_live_<32 caracteres base62>

Ejemplo de prefijo visible (seguro para logs): sit_live_Ab1C
La clave completa tiene unos 40 caracteres. Se almacena con hash (SHA-256) en el servidor
y nunca se puede recuperar en texto plano.

Clave no válida, caducada o revocada

Cualquier error de autenticación devuelve un HTTP 401 con un formato uniforme:

json
{
 "error": {
 "code": "invalid_api_key",
 "message": "Clave API no válida, desconocida o revocada. Genera una nueva clave desde tu cuenta.",
 "status": 401
 }
}
Fundamentos

Conceptos clave

URL base

text
https://insiders-trades.com

Metadatos universales

Cada respuesta 200 incluye un objeto meta. Contiene la latencia del servidor y un pequeño diccionario dataFreshness con la fecha de última actualización de cada bloque de datos, para que tu cliente decida si debe invalidar su caché.

json
{
 "items": [ /* ... */ ],
 "meta": {
 "requestedAt": "2026-04-20T18:32:11.123Z",
 "latencyMs": 47,
 "dataFreshness": {
 "priceAt": "2026-04-20T16:01:45.120Z",
 "financialsAt": "2026-04-20T15:04:10.940Z"
 }
 }
}

Paginación

Los endpoints de listado admiten ?limit (por defecto 50, máx. 200) y ?offset (por defecto 0). El campo total devuelto permite paginar hasta el final.

Formato de las marcas de tiempo

Todas las marcas de tiempo están en ISO 8601 UTC (2026-04-20T18:32:11.123Z).

Campos que admiten null

Un campo ausente en la base de datos se serializa como null (nunca se omite). Así puedes distinguir entre "dato ausente" y un error de campo.

BigInt (importes)

Campos como marketCap, revenue, totalAmount pueden superar la capacidad de los números de coma flotante de JS (253). Se devuelven como números, pero para totales grandes (L'Oréal con 195 000 M€…) tu código cliente debe usar BigInt si la precisión importa por debajo de 1 €.

Referencia de la API

Endpoints

Todos los endpoints son de solo lectura, agrupados por dominio. Filtro multimercado con ?market=<code> en todos los endpoints de listado (códigos listados por GET /v1/markets).

── Autenticación
GET/api/v1/me

Verificar una clave y obtener la identidad

Devuelve la información del propietario de la clave y los metadatos de la propia clave. Úsalo como ping para comprobar que una clave sigue activa.

curl https://insiders-trades.com/api/v1/me -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
── Estado y estadísticas
GET/api/v1/health

Estado del sistema

Hace ping a la base de datos (con latencia medida) y fecha cada etapa del pipeline. Útil para detectar que el cron horario o el scoring se han detenido.

bash
curl https://insiders-trades.com/api/v1/health -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Respuesta (extracto)
json
{
 "status": "ok",
 "database": { "reachable": true, "latencyMs": 187 },
 "lastAmfPublicationAt": "2026-04-20T16:20:03.577Z",
 "lastIngestAt": "2026-04-20T16:59:53.841Z",
 "lastScoringAt": "2026-04-20T17:59:59.061Z",
 "lastBacktestAt": "2026-04-19T20:13:54.245Z",
 "lastFinancialsAt": "2026-04-20T15:04:10.940Z",
 "lastPriceAt": "2026-04-20T16:01:45.120Z"
}
GET/api/v1/stats

Contadores globales

Número total de declaraciones, empresas, directivos y backtests, desgloses por ventana temporal (24 h / 7 d / 30 d) y score medio global.

bash
curl https://insiders-trades.com/api/v1/stats -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/markets

Listar los mercados / reguladores admitidos

Catálogo de los reguladores ingeridos con contadores en vivo (declaraciones, empresas) y ventana de cobertura por mercado. Llámalo una vez al iniciar tu integración para comprobar qué está disponible.

bash
curl https://insiders-trades.com/api/v1/markets -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
json
{
 "total": { "markets": 8, "declarations": 31420, "companies": 2480 },
 "markets": [
 { "code": "fr", "iso": "FR", "label": "FR", "regulator": "AMF",
 "currency": "EUR", "declarations": 18900, "companies": 1240,
 "coverage": { "oldestPubDate": "2015-01-05T...", "latestPubDate": "2026-05-17T..." } },
 { "code": "us", "iso": "US", "label": "US", "regulator": "SEC (Form 4)",
 "currency": "USD", "declarations": 9100, "companies": 720, "coverage": { ... } },
 { "code": "de", "regulator": "BaFin", ... },
 { "code": "ch", "regulator": "SIX SER", ... },
 { "code": "uk", "regulator": "RNS (LSE)", ... },
 { "code": "ca", "regulator": "SEDI", ... },
 { "code": "it", "regulator": "Consob", ... },
 { "code": "es", "regulator": "CNMV", ... }
 ],
 "meta": { "requestedAt": "...", "latencyMs": 90 }
}
── Empresas
GET/api/v1/companies

Listar empresas

Devuelve las empresas filtradas.

Parámetros de consulta
NombreTipoPor defectoDescripción
qstring·Búsqueda por nombre sin distinguir mayúsculas
isinstring·Filtro exacto por ISIN
marketstring·Filtro por mercado de cotización (p. ej. Euronext Paris)
marketCodeenum·Código de mercado, tal como lo lista GET /api/v1/markets (por ejemplo fr, us, jp)
hasLogoboolean·Devuelve solo empresas con (true) o sin (false) logo
sortenumnamename | marketCap | recent
orderenumascasc | desc
limitinteger501 → 200
offsetinteger0Desplazamiento de paginación
bash
curl "https://insiders-trades.com/api/v1/companies?q=lvmh&limit=3" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Respuesta (truncada)
json
{
 "total": 585, "offset": 0, "limit": 3,
 "items": [
 {
 "name": "LVMH MOET HENNESSY-LOUIS VUITTON",
 "slug": "lvmh-moet-hennessy-louis-vuitton-0042",
 "isin": "FR0000121014",
 "market": "Euronext Paris",
 "yahooSymbol": "MC.PA",
 "marketCap": 320200000000,
 "currentPrice": 643.40,
 "trailingPE": 22.43,
 "analystReco": "buy",
 "targetMean": 595.72,
 "logoUrl": "https://.../lvmh.webp",
 "declarationsCount": 147,
 "priceAt": "2026-04-20T16:01:45.120Z",
 "financialsAt": "2026-04-20T15:04:10.940Z"
 }
 ],
 "meta": { "requestedAt": "...", "latencyMs": 650, "dataFreshness": { ... } }
}
GET/api/v1/companies/{slug}

Detalle de una empresa (fundamentales completos)

Devuelve el perfil completo: cuenta de resultados, balance, valoración (P/E, P/B, beta), consenso de analistas (reco, objetivo medio/alto/bajo) e indicadores técnicos (52 semanas, medias de 50/200 días, rentabilidad por dividendo).

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Identificador URL único de la empresa (presente en la lista)
bash
curl https://insiders-trades.com/api/v1/companies/bouygues-1454 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Los campos de datos de mercado (trailingPE, analystReco, targetMean…) pueden ser null en micro-caps sin cobertura de analistas.
GET/api/v1/companies/{slug}/declarations

Declaraciones de directivos de una empresa

Historial completo de transacciones de directivos en una empresa, ordenado por pubDate desc.

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Slug de la empresa
Parámetros de consulta
NombreTipoPor defectoDescripción
directionenum·BUY | SELL (por defecto: todas)
minScorenumber·Umbral de signalScore
limitinteger501 → 200
offsetinteger0Desplazamiento de paginación
bash
curl "https://insiders-trades.com/api/v1/companies/bouygues-1454/declarations?direction=BUY&minScore=40&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/companies/{slug}/insider-flow

Flujo neto comprador / vendedor agregado

Compras netas menos ventas netas en una empresa, agrupadas por mes (o semana ISO), con agregados por directivo y una señal móvil de 90 días. Pensado para detectar fases de acumulación o distribución.

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Slug de la empresa
Parámetros de consulta
NombreTipoPor defectoDescripción
windowDaysinteger73030 → 3650 días
bucketenummonthmonth | week
bash
curl "https://insiders-trades.com/api/v1/companies/bouygues-1454/insider-flow?windowDays=365&bucket=month" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
json
{
 "company": { "name": "BOUYGUES", "slug": "bouygues-1454", "marketCap": 12400000000 },
 "windowDays": 365, "bucket": "month",
 "totals": { "tradeCount": 47, "buyAmount": 18450000, "sellAmount": 2100000, "netAmount": 16350000, "sellToBuyRatio": 0.114 },
 "rolling90d": { "buyAmount": 7800000, "sellAmount": 0, "netAmount": 7800000 },
 "buckets": [
 { "period": "2025-06", "buyAmount": 1200000, "sellAmount": 0, "netAmount": 1200000, "tradeCount": 4 },
 { "period": "2025-07", "buyAmount": 840000, "sellAmount": 320000, "netAmount": 520000, "tradeCount": 3 }
 ],
 "topInsiders": [
 { "name": "M. BOUYGUES", "slug": "martin-bouygues", "function": "PDG",
 "buyAmount": 6400000, "sellAmount": 0, "netAmount": 6400000, "tradeCount": 12 }
 ]
}
── Directivos
GET/api/v1/insiders

Listar directivos

Directivos seguidos con búsqueda aproximada por nombre.

Parámetros de consulta
NombreTipoPor defectoDescripción
qstring·Búsqueda por nombre sin distinguir mayúsculas
limitinteger501 → 200
offsetinteger0Desplazamiento de paginación
bash
curl "https://insiders-trades.com/api/v1/insiders?q=arnault&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/insiders/{slug}

Detalle de un directivo

Perfil, empresas a las que está vinculado con su cargo, y score medio y máximo de sus declaraciones.

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Slug del directivo
bash
curl https://insiders-trades.com/api/v1/insiders/bernard-arnault \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/insiders/{slug}/declarations

Historial de transacciones de un directivo

Cadena completa de operaciones, todas las empresas combinadas, ordenada por pubDate desc.

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Slug del directivo
Parámetros de consulta
NombreTipoPor defectoDescripción
limitinteger50Max 200
offsetinteger0Desplazamiento de paginación
bash
curl https://insiders-trades.com/api/v1/insiders/bernard-arnault/declarations \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/insiders/{slug}/timeline

Cronología con posición acumulada

Transacciones ordenadas en el tiempo para un directivo, con un volumen acumulado por empresa recalculado en cada línea, para ver cómo se construye la posición operación a operación.

Parámetros de ruta
NombreTipoPor defectoDescripción
slugobligatoriostring·Slug del directivo
Parámetros de consulta
NombreTipoPor defectoDescripción
fromISO date·Límite inferior de pubDate (opcional)
toISO date·Límite superior de pubDate (opcional)
limitinteger5001 → 2000
bash
curl "https://insiders-trades.com/api/v1/insiders/bernard-arnault/timeline?from=2024-01-01&limit=200" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
── Declaraciones
GET/api/v1/declarations

Búsqueda avanzada de declaraciones

Endpoint de uso general con 12 filtros combinables. Es el punto de entrada principal para exportar un corpus histórico o analizar por criterio.

Parámetros de consulta
NombreTipoPor defectoDescripción
marketenum·Código de mercado, tal como lo lista GET /api/v1/markets (por defecto: all)
currencyenum·EUR | USD | GBP | CHF | SEK | NOK | DKK | AUD | CAD · añade transaction.converted
sinceISO date·Alias de from. Combínalo con sort=pubDate&order=asc para polling incremental.
includestring·Lista CSV de objetos relacionados que se incluyen en línea. Admitido: backtest
fromISO date·Filtro pubDate >= from
toISO date·Filtro pubDate <= to
minScorenumber·Umbral mínimo de signalScore
maxScorenumber·Umbral máximo de signalScore
directionenum·BUY | SELL
clusterboolean·true = solo operaciones en clúster
minAmountnumber·Importe mínimo en €
companystring·Búsqueda por nombre de empresa
insiderstring·Búsqueda por nombre de directivo
isinstring·Filtro exacto por ISIN
sortenumpubDatepubDate | signalScore | amount
orderenumdescasc | desc
limitinteger501 → 200
offsetinteger0Desplazamiento de paginación
bash
# Top 20 señales de compra con score v3 ≥ 50 en los últimos 30 días
curl "https://insiders-trades.com/api/v1/declarations?direction=BUY&minScore=50&from=2026-03-20&sort=signalScore&order=desc&limit=20" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Variantes multimercado
bash
# Solo compras en EE. UU., importes en EUR, con backtest incluido
curl "https://insiders-trades.com/api/v1/declarations?market=us&direction=BUY&currency=EUR&include=backtest&limit=20" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Polling incremental, todas las declaraciones nuevas desde ayer, orden asc
curl "https://insiders-trades.com/api/v1/declarations?since=2026-05-16&sort=pubDate&order=asc&limit=200" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Compras en clúster DE+CH (Vorstand alemán + consejo suizo) por encima de 500 000 EUR
curl "https://insiders-trades.com/api/v1/declarations?market=de&cluster=true&minAmount=500000" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/declarations/{amfId}

Detalle de una declaración (con backtest)

Objeto completo que incluye el backtest minorista T+30/90/365 si está calculado. Entrada: cierre de pubDate+1.

Parámetros de ruta
NombreTipoPor defectoDescripción
amfIdobligatoriostring·Identificador AMF (p. ej. 2026DD1108988)
bash
curl https://insiders-trades.com/api/v1/declarations/2026DD1108988 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Extracto del bloque backtest
json
"backtest": {
"returnBasis": "retail_pubDate_plus_1_close",
 "direction": "BUY",
"priceAtPub": 33.10,
"returnsPct": {
  "T30": 4.16,
  "T90": 8.23,
  "T365": 19.88
},
"pubLeakPct": 2.0,
 "computedAt": "2026-04-19T20:13:54.245Z"
}
── Señales
GET/api/v1/signals

Señales principales (compras / ventas)

Atajo para obtener los mejores scores en una ventana móvil. Ideal para un dashboard o un bot de notificaciones.

Parámetros de consulta
NombreTipoPor defectoDescripción
directionenumBUYBUY | SELL
lookbackDaysinteger7Ventana (1 → 90)
minScoreinteger40Score mínimo (0 → 100)
limitinteger20Max 100
bash
curl "https://insiders-trades.com/api/v1/signals?direction=BUY&minScore=50&lookbackDays=7&limit=5" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
── Scoring (transparencia)
GET/api/v1/scoring/explain/{amfId}

Descomponer un signalScore en 7 factores ponderados

Devuelve el valor, los puntos brutos asignados, el tope y una breve justificación para cada uno de los 7 factores del score compuesto v3. Sin caja negra: audita cualquier señal tú mismo. Metodología: ver /methodology.

Parámetros de ruta
NombreTipoPor defectoDescripción
amfIdobligatoriostring·Identificador único (p. ej. 2026DD1108988 o SEC:0001127602-25-009876)
bash
curl https://insiders-trades.com/api/v1/scoring/explain/SEC:0001127602-25-009876 \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
json
{
 "declaration": { "amfId": "SEC:...", "storedScore": 78, "direction": "BUY", ... },
 "breakdown": {
 "sumFactorPoints": 78,
 "factors": [
 { "key": "pctOfMarketCap", "label": "Trade size vs market cap",
 "value": 0.42, "points": 14, "maxPoints": 16, "description": "Log-scaled..." },
 { "key": "directionalCluster", "label": "Directional cluster (±30d)",
 "value": 3, "points": 15, "maxPoints": 18, "description": "..." },
 { "key": "trackRecord", "label": "Insider track record (Bayesian-shrunk)",
 "value": 8.4, "sampleSize": 12, "points": 11, "maxPoints": 14, "description": "..." }
 ],
 "notes": [ "Sum of factor points is clamped to [0, 100]." ]
 }
}
── Backtest
GET/api/v1/backtest

Estadísticas globales de backtest

Rendimientos medios minoristas por horizonte (T+30, T+90, T+365) y tasa de acierto a T+90. Filtrable por dirección / score / periodo.

Parámetros de consulta
NombreTipoPor defectoDescripción
directionenum·BUY | SELL (por defecto: ambas)
minScorenumber·Filtro sobre el signalScore de la declaración subyacente
fromISO·Filtro pubDate >= from
toISO·Filtro pubDate <= to
bash
curl "https://insiders-trades.com/api/v1/backtest?direction=BUY&minScore=50" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Respuesta de ejemplo
json
{
 "filters": { "direction": "BUY", "minScore": "50", "from": null, "to": null },
 "total": 2 340,
 "byDirection": { "BUY": 2340 },
"returnBasis": "retail_pubDate_plus_1_close",
 "averageReturnsPct": {
"T30": 1.24, "T90": 4.62, "T365": 9.85
 },
 "sampleCounts": {
"T30": 2340, "T90": 2290, "T365": 1940
 },
 "winRates90d": { "BUY": 0.582, "SELL": null }
}
── Búsqueda
── Estrategia y rendimiento
GET/api/v1/strategy/winning

Cohorte de vigilancia filtrada (heredada)

Señales que cumplen los 6 filtros de la cohorte de vigilancia heredada (clúster, mid-cap, cargos clave, frescura ≤ 7 d, adquisición, score v3 ≥ 40). Solo vigilancia: sin rentabilidad esperada ni asignación validada, la respuesta lo indica en su bloque proof.

Parámetros de consulta
NombreTipoPor defectoDescripción
lookbackDaysinteger36530 → 1825
minScoreinteger700 → 100
bash
curl "https://insiders-trades.com/api/v1/strategy/winning?minScore=70" \
 -H "Authorization: Bearer sit_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
GET/api/v1/oos-performance

Seguimiento real por grupo de puestos (Top 3, 5, 10)

Las mismas cifras que /performance: una posición por empresa desde su primer día en el top k, rentabilidad frente al índice de su región en las mismas fechas, a 30 días, 90 días y 1 año, con cobertura e intervalos al 95 %. Versión 2 desde el 13/10/2026. Público, sin clave API.

bash
curl "https://insiders-trades.com/api/v1/oos-performance"
── Sandbox anónimo
GET/api/v1/sandbox/{path}

Proxy anónimo (10 llamadas / 24 h, sin clave)

Hace de proxy de las rutas READ de /api/v1/* sin autenticación. Límite móvil de 24 h: 10 llamadas por huella (3 para user-agents de bots). IP de centros de datos rechazadas, captcha a partir de la 6.ª llamada, marca de agua en cada respuesta. Bulk export, MCP y webhooks NO pasan por el proxy.

bash
# No hace falta ninguna cabecera. Pruébalo:
curl "https://insiders-trades.com/api/v1/sandbox/declarations?limit=3"
curl "https://insiders-trades.com/api/v1/sandbox/signals?direction=BUY&limit=5"
curl "https://insiders-trades.com/api/v1/sandbox/status"
POST/api/v1/sandbox/challenge

POW para user-agents de bots

Emite un challenge HMAC (dificultad de 16 bits, TTL de 10 min). El cliente debe encontrar un nonce tal que sha256(challenge + ':' + nonce) empiece por 4 ceros hex y reenviar X-Sandbox-POW-Challenge + X-Sandbox-POW-Solution en la siguiente llamada.

bash
curl -X POST "https://insiders-trades.com/api/v1/sandbox/challenge"
Esquema

Modelo de datos

Cinco entidades principales. Estos son los campos expuestos en la API (algunos campos internos, como índices o marcas de tiempo técnicas, no se incluyen).

Company

slugstringIdentificador URL, p. ej. bouygues-1454
namestringRazón social (fuente AMF)
isinstring | nullInternational Securities ID Number
marketstring | nullP. ej. Euronext Paris
yahooSymbolstring | nullTicker de mercado para precios / fundamentales
marketCapnumber | nullCapitalización bursátil en €
currentPricenumber | nullÚltimo precio conocido
trailingPE, forwardPE, priceToBook, betanumber | nullMétricas de valoración
analystReco, analystScore, targetMean, targetHigh, targetLowmixedConsenso de analistas
dividendYield, fiftyTwoWeekHigh/Low, fiftyDayAverage, twoHundredDayAveragenumber | nullIndicadores técnicos
logoUrlstring | nullURL del logo
priceAt, financialsAt, analystAtISO date-timeFrescura por bloque de datos

Insider

slugstringIdentificador URL
namestringNombre del directivo (fuente AMF)
declarationsCountintegerNúmero total de transacciones
companiesCompany[]Empresas vinculadas con el cargo ocupado

Declaration

amfIdstringIdentificador AMF único (p. ej. 2026DD1108988)
pubDateISO date-timeFecha de publicación AMF
transactionDateISO date-time | nullFecha efectiva de la transacción
pdfUrlstringEnlace al PDF oficial de la AMF
transactionobjectnature, instrument, isin, unitPrice, volume, totalAmount, currency, venue
insiderobjectname, slug, function
companyobjectname, slug, yahooSymbol, marketCap
signalobjectscore (0-100), pctOfMarketCap, pctOfInsiderFlow, insiderCumNet, isCluster, scoredAt

BacktestResult (anidado en Declaration.backtest)

directionstringBUY | SELL | OTHER
returnBasisstringretail_pubDate_plus_1_close
priceAtPubnumber | nullPrecio de entrada minorista (cierre pubDate+1)
returnsPct.T30 / T90 / T365number | nullRendimientos minoristas por horizonte
pubLeakPctnumber | nullMovimiento entre la transacción y la publicación
computedAtISO date-timeCuándo se ejecutó el cálculo

Signal (componente de scoring v3, calculado al vuelo)

scorenumber (0-100)Score compuesto v3 (10 componentes · ver /methodologie)
pctOfMarketCapnumber | nullRatio importe / capitalización (%)
pctOfInsiderFlownumber | nullParte del flujo total del directivo
insiderCumNetnumber | nullNeto acumulado (compra - venta) hasta esta operación
isClusterboolean≥ 2 directivos en el MISMO sentido ±30 d (direccional v3)
Errores

Gestión de errores

Todos los errores siguen un formato uniforme (similar a RFC-7807):

json
{
 "error": {
 "code": "<machine_readable_slug>",
 "message": "<descripción legible>",
 "status": <http_status>
 }
}

Códigos de error

StatusCodeCuándo
401missing_api_keySin cabecera Authorization ni X-Api-Key
401invalid_api_keyClave mal formada, desconocida o revocada. Usuario bloqueado = igual.
404company_not_foundSlug de empresa inexistente
404insider_not_foundSlug de directivo inexistente
404declaration_not_foundamfId inexistente
500internal_errorError del servidor, envíanos la URL y la hora
Reintenta cualquier respuesta ≥ 500 con back-off exponencial (p. ej. 1 s, 2 s, 4 s, máx. 5 intentos). Nunca reintentes 401 / 404.
Cuotas

Límites de uso y buenas prácticas

Límites por defecto durante la fase beta:

  • Beta privada: sin límite de páginas web, 20 solicitudes sandbox/día con una cuenta Free (el contador se reinicia a las 00:00 UTC). Las claves API empiezan con Pro y Quant.
  • 10 solicitudes/segundo (ráfaga) · suficiente para la mayoría de usos. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (ISO 8601).
  • 10 claves activas como máximo por cuenta. Por encima, revoca una desde tu página de claves.
  • Los contadores de uso son visibles en tiempo real para el usuario (total + hoy) y para el administrador (con los principales consumidores).

Buenas prácticas

  • Respeta la frescura. Los datos no cambian cada segundo. Los precios se actualizan una vez al día y las declaraciones de directivos de nuestros 46 mercados (AMF, SEC, BaFin, SIX SER, RNS, SEDI, Consob, CNMV, AFM, FSMA, Oslo, Helsinki, Copenhagen, ASX, FMA, CVM, HKEX, BSE-Sofia, Tadawul, DART, EDINET, SSE, SZSE, SEBI, KNF, PSE, NZX, JSE y más) varias veces al día según la fuente. Consulta meta.dataFreshness para adaptar tu frecuencia de polling.
  • Cachea de forma agresiva. El detalle de una empresa cambia poco, cachéalo en el cliente hasta priceAt + 1h.
  • Pagina correctamente. Usa un limit razonable (20-50) y offset para grandes volúmenes de datos.
  • Reintenta los 5xx. Con back-off exponencial, máx. 5 intentos.
  • Guarda tu clave de forma segura. Nunca en texto plano en un repo Git, en el frontend ni en los logs.
Ejemplos

Ejemplos de código

Obtener las señales principales del día

const API = "https://insiders-trades.com";
const KEY = process.env.INSIDERS_API_KEY;

async function topSignals(direction = "BUY", days = 1) {
 const url = new URL(API + "/api/v1/signals");
 url.searchParams.set("direction", direction);
 url.searchParams.set("lookbackDays", String(days));
 url.searchParams.set("minScore", "50");
 url.searchParams.set("limit", "10");

 const res = await fetch(url, {
 headers: { Authorization: "Bearer " + KEY },
 });
 if (!res.ok) throw new Error(`HTTP ${res.status}`);
 const { items, meta } = await res.json();

 console.log(`${items.length} signals · latency ${meta.latencyMs}ms`);
 for (const s of items) {
 console.log(
 `[${s.signal.score}] ${s.company.name.padEnd(32)} ${s.insider.name} · ${s.transaction.amount}€`
);
 }
}

topSignals();

Exportar a CSV todas las declaraciones de una empresa

import csv, os, requests

API = "https://insiders-trades.com"
KEY = os.environ["INSIDERS_API_KEY"]

def fetch_all(slug):
 items, offset = [], 0
 while True:
 r = requests.get(
 f"{API}/api/v1/companies/{slug}/declarations",
 params={"limit": 100, "offset": offset},
 headers={"Authorization": f"Bearer {KEY}"},
)
 r.raise_for_status()
 page = r.json()
 items.extend(page["items"])
 if offset + 100 >= page["total"]:
 break
 offset += 100
 return items

with open("bouygues_declarations.csv", "w", newline="") as f:
 rows = fetch_all("bouygues-1454")
 w = csv.writer(f)
 w.writerow(["pubDate", "insider", "role", "nature",
 "isin", "unitPrice", "volume", "amount", "score"])
 for d in rows:
 w.writerow([
 d["pubDate"],
 d["insider"]["name"],
 d["insider"]["function"],
 d["transaction"]["nature"],
 d["transaction"]["isin"],
 d["transaction"]["unitPrice"],
 d["transaction"]["volume"],
 d["transaction"]["totalAmount"],
 d["signal"]["score"],
 ])
print(f"Wrote {len(rows)} rows")
Versionado

Registro de cambios

v1.0.0 · 2026-04-20
  • Lanzamiento de la API pública.
  • 18 endpoints, autenticación por clave API, metadatos de frescura y de límite de uso en cada respuesta.
  • Swagger UI interactivo disponible en /api/docs.
  • 11 oct. 2026: el campo gender se elimina de los objetos insider (REST, OpenAPI, MCP). Era inferido, no declarado, y ya no se publica.
Soporte

Ayuda, comentarios, SLA

La API está en beta privada. El acceso es por invitación. Durante la beta no se ofrece SLA contractual, pero el equipo vigila a diario la frescura de los datos (varias recogidas al día en los mercados, precios actualizados a diario).

  • Solicitud de acceso a la beta o aumento de cuota: escribe a contact@insiders-trades.com.
  • Error / anomalía: indica la URL exacta, la hora (UTC) y el prefix de la clave utilizada.
  • Hoja de ruta: endpoints POST para notificaciones push, webhooks sobre nuevas señales, permisos granulares.
Uso ético. Las declaraciones de directivos (AMF, SEC, BaFin, SIX, RNS, SEDI, Consob, CNMV, AFM, FSMA, Oslo, Helsinki, Stockholm, Copenhagen, ASX, FMA, Dublin y más) son públicas, pero el límite de uso también protege a los reguladores y proveedores de datos que leemos. Los patrones abusivos conllevan la revocación inmediata de la clave.

¿Listo para integrar la señal de los directivos?

Genera una clave en 10 segundos, copia el ejemplo cURL del inicio rápido y explora los endpoints en vivo con Swagger.