Telemetría
contrato · SentinelTelemetryV1
Un contrato lo bastante estricto como para merecer confianza.
Tu asesor experto envía un objeto JSON. El servidor lo valida contra reglas fijas, lo normaliza y lo indexa por identidad. Lo que no encaja se rechaza con un motivo.
El payload
29 campos entran. 31 se almacenan.
Agrupados tal y como están definidos en el modelo de transporte. Los dos campos extra los añade el servidor: un identityKey compuesto y la marca de recepción lastSeenUtc.
| Grupo | Nº | Contiene |
|---|---|---|
| identidad | 10 | accountKey, accountLogin, brokerServer, terminalName, magic, name, family, symbol, timeframe, contractVersion |
| versión y tiempo | 3 | timestampUtc, telemetryVersion, guardVersion |
| lote y riesgo | 5 | baseLot, requestedLot, finalLot, appliedMultiplier, riskMultiplierSource |
| decisión | 5 | allowTrading, blockReason, lastDecision, sentinelAction, dashboardAction |
| calidad de ejecución | 4 | spread, slippage, positionLots, expectedLots |
| tickets | 2 | orderTicket, positionTicket |
X-Sentinel-Telemetry-Key: ••••••••
{
"contractVersion": "SentinelTelemetryV1",
"accountKey": "broker::184422",
"magic": 184422,
"symbol": "EURUSD",
"family": "breakout",
"telemetryVersion": "1.4.0",
"guardVersion": "10D.4",
"baseLot": 0.10,
"requestedLot": 0.10,
"finalLot": 0.0750,
"appliedMultiplier": 0.75,
"allowTrading": true
}
Clave de identidad. Las filas se indexan por accountKey|magic|SYMBOL|family. Si falta accountKey, se deriva como {brokerServer}::{accountLogin}.
Validación
Seis reglas que deben cumplirse.
Si falla cualquiera, el payload se rechaza con 400 — nunca llega al almacén y nunca se convierte en una fila a medias que tendrías que depurar más adelante.
| Regla | Restricción | Por qué |
|---|---|---|
| contractVersion | = SentinelTelemetryV1 | La desviación de versión entre flota y plataforma se detecta al instante, no meses después. |
| magic | > 0 | Un experto sin número mágico no puede atribuirse a una estrategia. |
| symbol | obligatorio | Se pasa a mayúsculas al llegar, para que el formato del bróker no divida un instrumento en dos. |
| family | una de 5 | Un vocabulario cerrado mantiene comparable el análisis entre cuentas. |
| appliedMultiplier | 0.0 – 5.0 | Un rango acotado impide que una entrada errónea parezca una instrucción de riesgo verosímil. |
| versiones | no vacías | telemetryVersion y guardVersion, para que cada fila sea atribuible a una compilación. |
- breakout
- meanreversion
- trendpullback
- cs28
- unknown
Los alias habituales se normalizan al llegar — brk → breakout, mr → meanreversion, trd → trendpullback, cs → cs28. Los lotes se redondean a cuatro decimales, alejándose de cero.
Frescura
Cinco estados, y honestidad sobre qué miden.
Una fila queda obsoleta cinco minutos después de la última vez que la API supo de ese experto. El reloj es del servidor: lastSeenUtc se sella al recibir, no lo aporta el terminal. Así, la frescura significa «tiempo desde que supimos de él», que es exactamente lo que conviene alertar — un terminal que deja de hablar es el fallo que importa.
Filas heredadas. Las filas de flota derivadas de fuentes antiguas, previas a V1, usan una ventana más amplia de 10 minutos y se etiquetan como tales. No mezclamos ambas.
-
OK / FULL
Contrato completo y visto dentro de la ventana.
-
PARTIAL
Reciente, pero con campos de versión incompletos — la fila es utilizable, no concluyente.
-
STALE
Contrato completo, pero nada recibido dentro de la ventana. El experto se ha callado.
-
LEGACY
Derivada de una fuente previa a V1. Sujeta a la ventana amplia, nunca mezclada con filas V1.
-
MISSING
Esperada por el registro y nunca vista. La ausencia es en sí misma una señal.
Superficie
Una escritura. Tres lecturas.
| Método | Ruta | Devuelve |
|---|---|---|
| POST | /api/ea-telemetry/v1/ingest | Acepta un payload validado. Cada intento —permitido o denegado— escribe una entrada de auditoría con endpoint, actor, motivo y accountKey. |
| GET | /api/ea-telemetry/v1/latest | Última fila por identidad, opcionalmente filtrada por accountKey. |
| GET | /api/ea-telemetry/v1/magic/{magic} | Todo lo que reporta bajo un mismo número mágico. |
| GET | /api/ea-telemetry/v1/summary | Recuentos por estado, incluidas cuántas filas han pasado la ventana de frescura. |
La ingesta queda deliberadamente fuera de la tabla de rutas bloqueadas: la telemetría sigue fluyendo mientras toda ruta de apply, override y configuración devuelve 403.
Obediencia
¿Lo hizo realmente el terminal?
Instrucción y ejecución son cosas distintas, y en esa brecha es donde las flotas se desvían en silencio. La auditoría de lote la cierra con aritmética: baseLot × multiplicador esperado frente al lote que el bróker ejecutó de verdad, con un 5% de tolerancia.
- OK
- MISMATCH
- MISSING_DATA
Sujeta a la evidencia. La auditoría vale lo que vale lo que reporta el experto. Los terminales que no envían campos de lote y multiplicador se resuelven como MISSING_DATA — nunca se puntúan como obedientes por defecto.
Conectarse
Un include, una llamada.
El cliente MQL5 es una sola cabecera con una función de envío. El único requisito en el terminal es permitir el endpoint en Herramientas → Opciones → Asesores Expertos. La petición HTTP expira a los 8000 ms, así que una red lenta degrada en un latido perdido y no en un experto bloqueado.
El almacén guarda solo el último valor. Una fila por accountKey|magic|symbol|family, y gana la última escritura. No hay histórico ni ventana de retención que configurar. Quantisentry es un plano de observación, no un almacén de datos — si necesitas histórico a nivel de tick, consérvalo tú.
La firma de payload no está implementada. El sobre tiene campos para un hash y una firma, y hoy nada los escribe ni los verifica. La seguridad del transporte es TLS más una clave de cabecera. Preferimos decírtelo a dejar que lo supongas.