Ejecución en vivo
Ejecuta una estrategia de forma continua contra un flujo de mercado en vivo — recibe sus señales y actualiza parámetros por WebSocket.
Ejecuta una estrategia de forma continua contra un flujo de mercado en vivo, observa sus señales a medida que ocurren, y cambia sus parámetros sin reiniciarla.
| Método | Ruta | Propósito |
|---|---|---|
POST | /strategy/{strategyId}/live | Arrancar una estrategia en vivo |
GET | /strategy/{strategyId}/live | Leer la ejecución actual (o la última) de esta estrategia |
DELETE | /strategy/{strategyId}/live | Detenerla |
GET | /live | Listar tus propias ejecuciones |
GET | /live/{runId} | Leer una de tus ejecuciones por su id |
GET | /live/public | Explorar ejecuciones que otros usuarios han hecho públicas |
PATCH | /live/{runId} | Cambiar visibilidad, nombre o descripción |
PUT | /live/{runId}/params | Cambiar parámetros mientras sigue en vivo |
POST | /live/{runId}/commands | Indicarle un comando mientras sigue en vivo |
POST | /live/{runId}/attachments | Adjuntarle una fuente de datos de mercado |
DELETE | /live/{runId}/attachments/{attachmentId} | Quitarle una fuente |
GET | /live/{runId}/signals | Leer las señales que ya ha producido |
GET | /live/{runId}/paper | Leer su paper trading — consulta Paper trading |
GET | /live/{runId}/paper/equity | Leer la curva de equity de una cuenta de paper trading, con la forma de cualquier curva de equity — consulta Paper trading |
POST | /live/token | Generar un token de conexión WebSocket |
Ciclo de vida: sandbox, luego live
Arrancar una ejecución (POST /strategy/{strategyId}/live) nunca la pone delante de nadie más que
de ti. Empieza en la etapa sandbox, una prueba cuya duración depende de tu plan: cada plan tiene una más corta, y la más larga que tiene
una ejecución es de 24 horas (Cuánto dura el sandbox). Durante ella la plataforma ejecuta
una segunda ejecución independiente de tu estrategia junto a la primera y comprueba cuatro cosas: que
la ejecución procesa datos de mercado, que su consumo de memoria y su tiempo por tick se mantienen
dentro de lo que la plataforma permite, que no se cuelga ni falla repetidamente, y que las dos
ejecuciones producen las mismas señales. Solo tú puedes leer una ejecución en sandbox: por el canal
WebSocket desde su primera señal si pediste relay, y por las rutas de lectura en cualquier caso
(consulta Visibilidad) — y por una URL de flujo si
creas una para ella, que permite a quien se la des leer las señales de la ejecución desde el sandbox.
Una ejecución que la supera se promueve a live automáticamente cuando termina su prueba. No hay
una llamada aparte de “promover” ni nada que hacer mientras esperas. Una ejecución que no la supera
no se promueve, y sigue corriendo en el sandbox.
Arrancar una ejecución necesita un plan que incluya ejecuciones en vivo. Un plan que no, el Free, se rechaza con 402: Live runs are not included in tier free. Upgrade your plan to run strategies live. Una estrategia que usa los
indicadores pro en un plan que no los incluye también se rechaza con 402, consulta los indicadores pro y tu plan.
Volver a arrancar no repite la prueba
Una estrategia que ya ha pasado por la prueba no vuelve a pasar por ella. Si detienes una ejecución que
fue promovida y arrancas la estrategia de nuevo, la ejecución nueva empieza en live de inmediato, sin
espera. Vale cuando una ejecución tuya anterior de la misma estrategia compilada fue
promovida y ninguna ejecución de esa compilación se detuvo por usar más recursos de los permitidos.
Los parámetros, las fuentes y los instrumentos de la ejecución nueva pueden ser distintos de los de la
anterior. Si vuelves a enviar la estrategia (POST /strategy), se compila de nuevo y la compilación
nueva pasa por el sandbox como una primera ejecución.
Qué cambia en una ejecución así:
stageesLIVEen la respuesta al arranque, ygateestá presente desde el principio: el veredicto de la ejecución anterior en la que se apoya, coninheritedFromindicando cuál es.- Nada compara una segunda ejecución con ella, porque no hay prueba. La plataforma detiene una
ejecución
liveque usa más recursos de los permitidos, igual que a cualquier otra (consulta Estado de una ejecución). - Si es
public, está en el catálogo y abierta a cualquiera desde su primera señal. - No tiene historial en la conexión: este se guarda solo para la etapa
sandbox(consulta Leer señales anteriores por la conexión). Sus señales siguen siendo legibles conGET /live/{runId}/signals.
Para obtener el sandbox de todos modos — para depurar una estrategia, o para volver a leer sus señales
por la conexión — arráncala con "sandbox": true. En una estrategia que no ha pasado por la prueba el
campo no cambia nada: siempre arranca en el sandbox.
Lo que puedes observar mientras espera, en GET/PATCH .../live:
stageesSANDBOXhasta la promoción yLIVEdespués (LIVEdesde el principio en una estrategia que ya ha pasado por la prueba, consulta más arriba).statees la salud de la ejecución ahora mismo (consulta Estado de una ejecución).gateestá ausente durante toda la prueba y aparece cuando termina, con el veredicto. Ungateausente significa por tanto “la prueba no ha terminado”, nunca “nadie está evaluando la ejecución”. Su campopassedes el veredicto; el resto es detalle de diagnóstico cuya forma puede cambiar. Una ejecución que arrancó enlivelo tiene desde el principio (consulta más arriba).
Estado de una ejecución
state dice qué está haciendo la ejecución. Es una cadena que puede ganar valores, así que lee uno
desconocido como “en marcha, con algo que mirar”.
state | Qué significa |
|---|---|
STARTING | Aceptada; ningún runner ha informado todavía sobre ella. |
WAITING | En marcha sin ninguna fuente de datos de mercado adjuntada: no ocupa plaza en la plataforma y no lee datos hasta que le adjuntes una. |
RUNNING | En marcha con normalidad. |
LAGGING | En marcha, pero por detrás de los datos de mercado: habitual mientras se pone al día tras arrancar o tras un reinicio de la plataforma. Se despeja sola. |
HUNG | Tu estrategia está atascada dentro de una llamada durante más tiempo del que la plataforma permite. Se despeja cuando esa llamada devuelve. |
DEGRADED | Las ejecuciones independientes de la ejecución produjeron señales distintas a partir de los mismos datos de mercado. La ejecución sigue publicando. En el sandbox esto cuenta en contra de la prueba: la ejecución no se promueve. |
FAILED | La plataforma rechazó la ejecución, no pudo arrancarla, o la ejecución falló mientras corría. reason dice por qué (consulta Por qué una ejecución falló o se detuvo). |
STOPPED | Detenida, por ti o por la plataforma (reason lo dice cuando fue por superar su margen de recursos). |
LAGGING, HUNG y DEGRADED son indicadores de una ejecución que por lo demás está corriendo:
aparecen y desaparecen, y las señales de la ejecución siguen fluyendo todo el tiempo. desired es
lo que pediste por última vez (RUNNING o STOPPED), y state puede ir por detrás durante un
momento.
Solo una ejecución por estrategia a la vez. Volver a arrancar mientras una está en RUNNING es 409 — detenla primero con DELETE.
Arrancar también es 409 cuando la estrategia, tal como se compiló, ya no funciona con la versión actual de la
plataforma: una versión quitó algo a lo que llama. La respuesta es una frase fija (The strategy was compiled for an earlier version of the platform and no longer works with the current one. Register it again to start a new run.), no se crea ninguna ejecución y no se ocupa ninguna plaza. Registra la estrategia de nuevo (POST /strategy con el mismo código) y arráncala; si el propio código usa lo que se quitó, al registrarla te lo dice.
Un DELETE es una petición, no una parada instantánea: desired pasa a STOPPED de inmediato,
pero state puede seguir en RUNNING durante una ventana corta mientras la ejecución concluye.
Volver a llamar a DELETE sobre una ejecución ya detenida no es un error.
Una ejecución fallida es definitiva, y sigue ocupando su plaza
FAILED es definitivo para esa ejecución: no está procesando datos y nada la reinicia. Para volver a
intentarlo, corrige lo que nombra reason y arranca una ejecución nueva. Lo habitual es que desired siga en RUNNING hasta que detengas tú la ejecución, y una ejecución cuenta como activa por su desired, no por su state: una ejecución FAILED sigue respondiendo 409 a un nuevo arranque de la
misma estrategia y sigue contando para el límite de ejecuciones en vivo de tu plan. Llama a DELETE sobre ella y arranca de nuevo.
La excepción es una ejecución que no puede correr, y no podrá por mucho que esperes: cuando su estrategia
no puede consumir su tipo de fuente, cuando su estrategia ya no funciona con la versión actual de la plataforma, o
cuando la pool de una ejecución dex no es una pool o no tiene sitio para seguirla, la plataforma la detiene ella misma (desired pasa a STOPPED, state se queda en FAILED, reason dice por qué), así que no ocupa plaza.
Por qué una ejecución falló o se detuvo
GET /strategy/{strategyId}/live, y cada entrada de GET /live, llevan un reason cuando hay algo
que decir. Está ausente en caso contrario, y nunca es una traza de pila ni un mensaje interno: es una
frase de un conjunto fijo, así que un cliente puede compararla.
reason | Cuándo |
|---|---|
resource: ... | La plataforma detuvo la ejecución por superar su margen de recursos; el texto dice qué límite. |
The run could not start: its strategy cannot consume the source type it was started with. | Una estrategia ticker arrancada con una fuente kline, o al revés. El arranque lo rechaza con un 400 (consulta Fuentes); solo puede aparecer en una ejecución creada antes de que existiera esa comprobación. |
The run could not start: its definition was refused. | La definición de la ejecución no es una que la plataforma pueda ejecutar. |
The run could not start after several attempts. | Un arranque que siguió fallando por un motivo que no era tuyo. Arranca de nuevo. |
The run stopped because its strategy failed while processing data. | El propio código de tu estrategia tumbó la ejecución. |
The run stopped for good: its strategy does not work with the current version of the platform. Register it again to start a new run. | La estrategia se compiló para una versión anterior de la plataforma y una versión quitó algo a lo que llama. Un arranque lo rechaza de entrada con un 409; una ejecución que ya estaba en marcha cuando cambió la versión termina con este motivo y no se vuelve a arrancar. |
The run stopped because it lost its data feed. | El flujo de datos de mercado de la ejecución se cortó y la ejecución se quedó parada. |
The run could not start: its pool address is not a pool of that protocol on that chain. | Una ejecución dex (consulta Pools DEX) nombra una dirección que no es una pool de su protocolo en su cadena, o cuyos tokens la plataforma no puede leer. |
The run could not start: the platform is following as many pools as it can right now. Try again later. | Una ejecución dex nombra una pool para la que la plataforma no tiene sitio. |
The run failed. | Cualquier otra cosa. |
El conjunto puede crecer. Lee una frase que no reconozcas como «la ejecución falló», y no la analices en busca de detalle: el texto es para personas.
Qué está haciendo una ejecución: stats
Mientras una ejecución se está ejecutando, la plataforma guarda sus últimos contadores y los refresca más o
menos una vez por minuto. GET /strategy/{strategyId}/live y GET /live/{runId} los devuelven como stats:
"stats": {
"processed": 18233,
"opsPerSecond": 4.2,
"instrumentsSeen": 12,
"asOfMs": 1758330060000,
"progressedAtMs": 1758330060000,
"stale": false
} | Campo | Qué significa |
|---|---|
processed | Actualizaciones de instrumentos que la ejecución ha aceptado desde que empezó a ejecutarse. Puede volver a empezar desde cero si la ejecución se reinicia. |
opsPerSecond | Actualizaciones aceptadas por segundo durante el último refresco. Es un promedio de alrededor de un minuto, así que no salta de una actualización a la siguiente. 0 cuando no llegó ninguna. |
instrumentsSeen | Instrumentos distintos de los que la ejecución ha recibido una actualización. |
asOfMs | Cuándo se escribieron por última vez estos contadores. |
progressedAtMs | El último refresco en el que processed había crecido. Ausente hasta que la ejecución ha procesado algo. |
stale | true cuando se supone que la ejecución está corriendo y sus contadores no se han refrescado durante varios intervalos de refresco. |
Tres cosas que conviene saber:
statsestá ausente, no a cero, cuando todavía no hay nada: una ejecución recién arrancada no tiene ninguna instantánea. Arrancar (POST) y detener (DELETE) una ejecución no lo devuelven; léelo con uno de los dosGETde arriba.stalesolo dice que la plataforma dejó de actualizar los contadores. Compáralo constate. Una ejecución cuyoprocessedse queda plano no está obsoleta ni rota: una alimentada por una fuente que se actualiza pocas veces (una tasa de financiación, por ejemplo) puede quedarse plana durante horas.progressedAtMses la forma de distinguir una ejecución así de una que se ha parado.- Un refresco de
statsno es un cambio de la ejecución. No mueveupdatedAtMs.
Fuentes
sources acepta una entrada, o ninguna: un arranque sin sources (omitido, o []) crea una ejecución que espera, y adjuntas una fuente cuando quieras. Más fuentes, del mismo mercado, se adjuntan después. Una entrada:
{
"sources": [
{"venueType": "cex", "exchange": "binance", "segment": "spot", "type": "ticker", "instruments": ["BTC/USDT"]}
]
} exchange y segment son los ids que lista GET /exchanges, en minúsculas, y venueType es el que ese
endpoint da al exchange: cex para un exchange centralizado y dex para uno descentralizado (cx, la
grafía que se usaba antes, se sigue leyendo como cex). El segmento tiene que ser uno de los liveSegments del exchange: los segmentos para los que se publican datos en vivo, hoy spot en un exchange centralizado.
Los tres tienen que ir juntos en esa lista, y un arranque cuya fuente no lo cumple se rechaza con 400 indicando lo que la lista tiene, antes de que ocupe plaza: sources[0].exchange 'coinbase' is not a cex exchange (binance, bybit); GET /exchanges lists them, sources[0].segment 'perp' is not one of [spot, futures] for the exchange 'binance', sources[0].exchange 'robinhood' is a dex exchange, not a cex one. Las mayúsculas y
los espacios alrededor de un valor no importan, y la ejecución devuelve venueType, exchange, segment y type en minúsculas.
Un segmento que el exchange ofrece pero sin datos en vivo se rechaza igual, diciendo cuáles lee una
ejecución en vivo: futures de un exchange centralizado es el segmento de su catálogo de instrumentos, así que sources[0].segment 'futures' has no live data on the exchange 'binance': a live run reads one of [spot].
Una ejecución sobre un segmento que nadie publica arrancaría, parecería viva y nunca recibiría una barra.
type tiene que coincidir con el tipo de estrategia: una estrategia ticker corre sobre una fuente ticker y una estrategia kline sobre una kline, y un arranque con la otra se rechaza con 400,
nombrando ambas. Una estrategia QTScript es una estrategia ticker salvo que su cabecera diga otra cosa
(strategy "Name" kline); una Java es la de la clase base que extienda (AbstractTickerStrategy o AbstractKlineStrategy).
type es ticker o kline. Ambos se conectan a la cadencia más ligera (más rápida) disponible
para el exchange — hoy eso es 1 tick/segundo en todos los exchanges soportados; elegir entre
varias cadencias todavía no está disponible.
instruments se puede omitir. Una estrategia QTScript puede declarar qué instrumentos acepta con una línea instruments en su código. Cuando la compilación de la estrategia registra esa selección como una lista
de pares, un arranque que omite instruments, o que envía ["*"], toma esa lista; en caso contrario la
ejecución lee todos los instrumentos que ofrezca el exchange/segmento, sujeto al límite de número de
instrumentos de tu plan:
{
"sources": [
{"venueType": "cex", "exchange": "binance", "segment": "spot", "type": "ticker"}
]
} Una lista de instrumentos se toma tal como se envía, y [] y null se rechazan con 400.
Escribe los instrumentos como BASE/QUOTE. No distinguen mayúsculas de minúsculas y se ignoran los
espacios a su alrededor, así que btc/usdt, BTC/USDT y " btc / usdt " son el mismo instrumento.
Cualquiera de los dos lados puede ser * para significar «cualquiera»: */USDT es todo par cotizado en
USDT y BTC/* es BTC contra cualquier moneda de cotización. Una entrada que no tenga esa forma (sin /, con un lado
vacío, con un . o un espacio dentro de un lado, o con un * mezclado con otros caracteres de un lado)
hace que la ejecución falle al arrancar. Frente al límite de tu plan, una lista con una entrada que lleve
un * en un lado cuenta como ["*"], y solo la admiten los planes que incluyen el comodín; las demás
entradas se cuentan una a una.
Los instrumentos que la ejecución lee de verdad vuelven en sus sources: una ejecución arrancada sin instruments muestra la lista que obtuvo, que puede tener entradas como */USDT.
Pools DEX
Una ejecución puede leer una pool de un exchange descentralizado en lugar del mercado de un exchange
centralizado. Fija venueType a dex:
{
"sources": [
{"venueType": "dex", "exchange": "robinhood", "segment": "uniswap-v3", "type": "kline", "instruments": ["0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca"]}
]
} | Campo | En una fuente dex |
|---|---|
exchange | La cadena en la que está la pool: un exchange que GET /exchanges lista con venueType: dex. Hoy robinhood (Robinhood Chain) es el único. |
segment | El protocolo de la pool, uno de los segments de ese exchange. Hoy uniswap-v3 es el único. |
type | Solo kline. Una fuente ticker no está disponible para una pool, y una estrategia ticker no puede correr sobre una. |
instruments | Exactamente una entrada: la dirección de la pool, 0x y 40 cifras hexadecimales, sin distinguir mayúsculas. No se puede omitir y no se acepta *. |
Para encontrar pools que ejecutar, lista los instrumentos del exchange: GET /exchange/robinhood/uniswap-v3/instruments devuelve las 50 pools con más volumen en las últimas 24 horas entre las que tienen al menos 10 000 dólares
de liquidez, actualizadas cada hora. Cada una trae su id (la dirección que va en instruments), su par
nombrado como lo nombran las señales, su nivel de comisión, su liquidez y su volumen (consulta Pools de un exchange descentralizado). La lista es un
punto de partida, no todo el mercado: una ejecución puede leer cualquier pool de Uniswap V3 de la cadena,
esté listada o no.
Lo que recibe la estrategia:
- Una vela por segundo de las operaciones de la pool, con los habituales
open,high,low,closeyvolume. Un segundo en el que no se operó también recibe vela: repite el cierre anterior, con volumen cero y cero operaciones, de modo que una estrategia que cuenta barras está contando tiempo incluso en una pool que opera poco. - Una vela se publica cuando su segundo ha terminado y las operaciones tardías han tenido un momento para llegar: hasta unos tres segundos después de que acabe el segundo. Las señales llevan por tanto un retraso sobre el mercado de hasta esa espera más el trabajo propio de la estrategia.
- Una pool que no ha operado desde que la plataforma empezó a seguirla no produce velas hasta su primera operación: aún no hay precio que repetir.
- Las señales de la ejecución nombran el par como los tokens de la pool escritos
BASE/QUOTE, comoWETH/USDG, en suinstrument(exchangees la cadena ysegmentel protocolo). La plataforma fija la orientación de una pool, así que la misma pool se cotiza siempre igual.
El arranque y el calentamiento funcionan como en cualquier ejecución (consulta Calentar la ejecución). La plataforma sigue una pool cuando una
ejecución lo pide y reproduce la historia que pide el warmFrom de la ejecución antes de la primera vela en
vivo, así que una ejecución sobre una pool que nadie más lee se pone al día a unas seis veces la velocidad
del mercado: el calentamiento por defecto (hasta 15 minutos) tarda hasta unos minutos, y warmFrom: 3600 unos
diez. Mientras se pone al día la ejecución puede mostrar LAGGING. Una ejecución que arranca sobre una pool
que la plataforma ya sigue recibe la historia que existe para ella, que es más corta que su warmFrom cuando
la pool se empezó a seguir hace un momento.
Una ejecución dex cuya pool no se puede servir falla en cuestión de segundos en lugar de esperar velas que
no van a llegar, y la plataforma la detiene, así que no ocupa plaza (consulta Por qué una ejecución falló o se detuvo):
- La dirección no es una pool de ese protocolo en esa cadena, o la plataforma no puede leer sus tokens: el
reasonesThe run could not start: its pool address is not a pool of that protocol on that chain.Tarda unos quince segundos. Si arrancas la misma dirección de nuevo enseguida, puede tardar hasta medio minuto. - La plataforma sigue ya tantas pools como puede: el
reasonesThe run could not start: the platform is following as many pools as it can right now. Try again later.Tarda unos segundos. Arrancar de nuevo funciona cuando hay sitio: una pool se libera unos minutos después de que se detenga la última ejecución que la lee.
Una cadena o un protocolo que GET /exchanges no lista para un exchange dex se rechaza con 400 al
arrancar la ejecución. Una fuente que supera eso y aun así no se puede ejecutar se acepta y falla también en
cuestión de segundos, con The run could not start: its definition was refused. como reason: un
instrumento que no es una dirección, más de uno, o un tipo ticker. Se exige una estrategia kline, como en
cualquier fuente kline: arrancar una estrategia ticker sobre una fuente dex se rechaza con 400. Un
arranque que omite instruments, o envía ["*"], se rechaza con 402 en un plan sin el comodín; en
cualquier otro la ejecución falla como se ha descrito.
Varias pools en una ejecución
Una ejecución puede leer varias pools a la vez: adjunta cada una como su propia fuente (consulta Adjuntar y quitar una
fuente). Tienen que estar en la misma cadena y el mismo protocolo, y tu plan limita
cuántas pools puedes seguir a la vez entre tus ejecuciones (429, con el número). Dos cosas son distintas de un arranque:
- Una pool adjuntada a una ejecución que ya lee otra se lee desde el momento en que surte efecto. No tiene historia:
envía
warmFrom: 0o déjalo sin enviar, porque cualquier otro valor es un400. Su primera señal llega unos 25 segundos después de la petición en nuestras mediciones: el adjuntado surte efecto con 15 segundos de adelanto, y luego vienen la espera de las operaciones tardías (hasta unos tres segundos) y el segundo de la propia vela. Solo la primera fuente de una ejecución en espera, que es la que la arranca, tomawarmFromcomo lo hace un arranque. - Una pool por par. La estrategia ve el par (
WETH/USDG), nunca la pool, así que no podría distinguir dos pools del mismo par, y un par suele tener varias (una por nivel de comisión). La primera pool que da una vela del par se la queda. Una pool del mismo par adjuntada después se retira: pasa aDETACHEDcon elreasonSAME_PAIR, normalmente en menos de media hora desde que surte efecto, y ninguna de sus velas llega a la estrategia. Adjúntala a otra ejecución, o quita la primera pool.
Adjuntar y quitar una fuente
Una ejecución no tiene por qué arrancar sobre un mercado. Arráncala sin sources y espera (state: WAITING): existe,
conserva su URL de flujo, su canal y sus cuentas de paper trading, no lee
datos de mercado y no ocupa ninguna plaza en la plataforma. Cuando una alerta te dice qué instrumento importa, adjúntalo;
cuando termines, quítalo y adjunta otro. Una ejecución arrancada con una entrada en sources es lo mismo con su primera
fuente ya adjuntada por ti.
POST /live/{runId}/attachments toma una fuente y responde 202:
{
"source": {"venueType": "dex", "exchange": "robinhood", "segment": "uniswap-v3", "type": "kline",
"instruments": ["0x3f4e0b2c8e1a4b6d9c0f1a2b3c4d5e6f708192a3"]},
"warmFrom": 120,
"ref": "alert-8841"
} {"attachmentId": "3p5YyWkq0vH2nJb7LrT9Zc", "state": "ATTACHING", "effectiveAtMs": 1758330015000} | Campo | Qué significa |
|---|---|
source | Obligatorio. La misma entrada que toma sources al arrancar, comprobada igual: exchange, segmento y tipo, y sus instrumentos (una fuente dex es exactamente una pool). Consulta Fuentes. |
warmFrom | Opcional. Cuántos segundos del flujo anteriores al adjuntado ve primero la estrategia, de 0 a 3600, como al arrancar pero solo para esta fuente. Si se omite, el mismo valor por defecto que al arrancar. Una pool dex adjuntada a una ejecución que ya lee otra se lee desde ahora: 0, u omitirlo, son los únicos valores que admite (consulta Varias pools en una ejecución). |
ref | Opcional. Una cadena tuya, de hasta 64 caracteres. Enviar el mismo ref a la misma ejecución devuelve el adjuntado que ya hizo en lugar de hacer otro, así que una petición reintentada, o una alerta que llega dos veces, es segura. Enviar una fuente que la ejecución ya tiene adjuntada, o está adjuntando, devuelve también ese adjuntado, sea cual sea su ref. |
Toda fuente adjuntada a la vez a una ejecución está en el mismo mercado: el mismo exchange para un cex, la misma
cadena y el mismo protocolo para un dex. Una fuente de otro mercado se rechaza con 409 hasta que se quiten las demás.
Una ejecución en espera acepta cualquiera.
Cuándo ocurre. La primera fuente de una ejecución en espera la arranca, como lo hace un arranque. Cualquier otro
adjuntado, y todo quitado, surte efecto en effectiveAtMs, un momento unos segundos por delante que todas las ejecuciones
detrás de la ejecución aplican en la misma posición del mercado, de modo que siguen idénticas entre sí, como con un comando. El 202 es la aceptación; state dice cuándo ha ocurrido.
Leer los adjuntados
attachments es una lista en la ejecución, en GET /strategy/{strategyId}/live y GET /live/{runId}: de cada uno, su attachmentId, la source tal como la tiene la plataforma, warmFrom, tu ref, state, reason y message cuando hay
algo que decir, createdAtMs y effectiveAtMs. Las sources de la ejecución son las fuentes de sus adjuntados que están ATTACHING o ATTACHED, y están vacías mientras espera.
state | Qué significa |
|---|---|
ATTACHING | Aceptado; surte efecto en effectiveAtMs. |
ATTACHED | La ejecución lo está leyendo. |
DETACHING | Un quitado está aceptado; surte efecto en su effectiveAtMs. |
DETACHED | La ejecución ya no lo lee. reason dice por qué cuando no fuiste tú. |
REFUSED | La plataforma no pudo seguirlo. reason y message dicen por qué. La ejecución queda como estaba. |
reason es una cadena que puede ganar valores: OWNER (lo quitaste tú), REFUSED (la plataforma lo rechazó), POOL_GONE (una pool dex dejó de seguirse), CAPACITY (la plataforma no tiene sitio para seguirla), SAME_PAIR (una pool dex de un
par que la ejecución ya lee a través de otra pool) y NO_DATA (el instrumento, de un exchange centralizado, no envió nada
en cinco minutos: puede ser uno que la plataforma no captura). Una ejecución arrancada con una fuente dex que la
plataforma no seguirá falla como siempre (consulta Por qué una ejecución falló o se
detuvo), y lo mismo una cuya primera fuente, adjuntada mientras esperaba, es una
pool así. Una pool adjuntada a una ejecución que ya está leyendo se retira en su lugar, sin hacer fallar la ejecución:
acaba DETACHED con el reason REFUSED (no es una pool de ese protocolo en esa cadena) o CAPACITY (la plataforma no
tiene sitio para seguirla), normalmente en menos de medio minuto desde que el adjuntado surte efecto, y el onDetach de la
estrategia recibe CAPACITY cuando la plataforma no tiene sitio y REFUSED en cualquier otro caso, SAME_PAIR incluido.
Quitar
DELETE /live/{runId}/attachments/{attachmentId} responde 202 con el adjuntado en DETACHING; repetirlo no es un error.
En una ejecución que se ha detenido no hay nada que avisar, y el adjuntado pasa directamente a DETACHED. Las posiciones
que una cuenta de paper trading tenía abiertas en los instrumentos de esa fuente se informan como
huecos. Cuando se quita la última fuente la ejecución vuelve a esperar: la memoria de la estrategia se libera, así que el
siguiente adjuntado la arranca limpia, y las cuentas de paper trading se conservan.
Qué puede rechazar un adjuntado
| Estado | Cuándo |
|---|---|
400 | El cuerpo: sin source, un warmFrom fuera de 0 a 3600, un ref de más de 64 caracteres; o una fuente que un arranque rechazaría, con los mismos mensajes (una mal formada, una pool que no es una sola dirección, un tipo que la estrategia no puede consumir, un segmento sin datos en vivo); o un warmFrom por encima de 0 para una pool dex adjuntada a una ejecución que ya lee otra. |
402 | Un instrumento comodín en un plan que no lo incluye. |
404 | No existe esa ejecución, o no es tuya; en un quitado, no existe ese adjuntado. |
409 | La ejecución no está corriendo, o la fuente está en otro mercado distinto de los ya adjuntados. |
422 | Un instrumento que la selección registrada de la estrategia deja fuera (una línea instruments de QTScript). |
429 | Un límite de tu plan, que el mensaje nombra con su número: los instrumentos que una ejecución puede leer (el mismo límite que al arrancar, contado sobre todos sus adjuntados), las pools dex que puedes seguir a la vez entre tus ejecuciones (también contadas cuando una ejecución se arranca con una pool); o la plataforma no tiene sitio. |
Una ejecución cuenta para tu límite de ejecuciones en vivo solo mientras tiene una fuente adjuntada. Las ejecuciones que
mantienes en espera, sin ninguna, también están limitadas, por tu plan; el límite se aplica cuando arrancas una así, y un
arranque que lo supera se rechaza con 429.
El sandbox también acepta adjuntados. Su prueba cuenta solo el tiempo con una fuente adjuntada: una ejecución en espera no
la hace avanzar (consulta Cuánto dura el sandbox). Un comando enviado a una ejecución sin fuente adjuntada se rechaza con 409: no hay nada a lo que entregarlo.
La estrategia recibe aviso de cada adjuntado y quitado, consulta QTScript y Programar estrategias en Java.
Calentar la ejecución: warmFrom
Una estrategia que lee una media, una ventana o cualquier otro indicador necesita algo de historia antes
de que sus valores signifiquen algo: la media de los últimos 50 precios no tiene nada que promediar en su
primer tick. Por eso una ejecución arranca en caliente. Antes de su primer tick en vivo reproduce el
feed de mercado desde un momento poco anterior al arranque, y la estrategia ve ese tramo primero, como si
llevara tiempo en marcha. Mientras se pone al día, la ejecución puede mostrar LAGGING, y su primera señal
llega al canal y al flujo solo cuando se ha puesto al día. Las señales sobre el tiempo reproducido
describen hechos anteriores al arranque, así que no se emiten.
warmFrom es como eliges cuánto reproducir: el número de segundos antes del arranque desde los que
reproducir. Se fija en el cuerpo de POST /strategy/{strategyId}/live, junto a sources:
{
"sources": [
{"venueType": "cex", "exchange": "binance", "segment": "spot", "type": "ticker", "instruments": ["BTC/USDT"]}
],
"warmFrom": 300
} warmFrom | Qué ocurre |
|---|---|
| omitido | La plataforma reproduce desde el inicio del bloque de 15 minutos en curso: entre 0 y 900 segundos antes del arranque, según cuándo arranque (0 si arranca justo en un cuarto de hora). La primera barra de una ventana de 15 minutos sale entonces completa. |
0 | Sin reproducción. La ejecución empieza en su arranque: entrega su primera señal en cuanto está en marcha, con indicadores que empiezan vacíos y una primera barra de ventana que puede ser parcial. |
1 a 3600 | La estrategia ve esa cantidad de segundos del feed anteriores al arranque y después continúa en vivo. |
- Es un entero de segundos de
0a3600(una hora). Cualquier otro valor (un número negativo, uno superior a3600, una fracción, texto) se rechaza con400. - Elígelo según lo que necesite la estrategia. Una estrategia con periodos de indicador largos debería
pedir al menos el tiempo que tarda en llenarse su indicador más lento: con
0, sus primeros valores se calculan sobre lo que haya llegado desde el arranque, y si se omite, la reproducción puede ser de solo0segundos (una ejecución que arranca justo en un cuarto de hora) y nunca de más de900. - Solo se puede fijar al arrancar la ejecución. No es uno de los parámetros que acepta
PUT /live/{runId}/paramsy no se puede añadir después: para cambiarlo, detén la ejecución y vuelve a arrancarla. - La ejecución devuelve el valor en vigor como
warmFromcuando la lees (la respuesta de arranque,GET /strategy/{strategyId}/liveyGET /live/{runId}; la respuesta al detener una ejecución no lo incluye): el que pediste o, si lo omitiste, el que eligió la plataforma. Envía ese número para obtener la misma cantidad de calentamiento en otra ejecución. Una ejecución arrancada antes de que existiera este campo no llevawarmFromen absoluto; nunca esnull.
Cuánto dura el sandbox: sandboxMinutes
Toda ejecución empieza con una prueba en la etapa sandbox (consulta Ciclo de vida). Cuánto dura
depende de tu plan: cada plan tiene una prueba más corta, desde una hora hasta un día entero, y la más larga que tiene una
ejecución es de 24 horas. Una ejecución que no pide nada recibe la prueba más corta que da su plan. La prueba cuenta solo el tiempo en que la ejecución tiene una fuente adjuntada (consulta Adjuntar y quitar una fuente): una ejecución que espera no la hace avanzar.
sandboxMinutes es como pides una más larga. Se fija en el cuerpo de POST /strategy/{strategyId}/live, junto a sources:
{
"sources": [
{"venueType": "cex", "exchange": "binance", "segment": "spot", "type": "ticker", "instruments": ["BTC/USDT"]}
],
"sandboxMinutes": 480
} sandboxMinutes | Qué ocurre |
|---|---|
| omitido | La prueba más corta que da tu plan. |
desde la más corta de tu plan hasta 1440 | La ejecución se prueba al menos esos minutos. |
| menos que la más corta de tu plan | 429: el mensaje nombra tu plan y el número. Reintentar con el mismo valor no ayudará. |
- Es un entero de minutos de
5a1440. Cualquier otro valor (texto, una fracción,null, un número fuera del rango) se rechaza con400. - Es un mínimo, no el momento de la promoción. Una prueba tampoco ha terminado hasta que la plataforma ha alimentado a la
ejecución con suficiente feed de mercado para juzgarla, aproximadamente una actualización por cada segundo de la prueba. Una
ejecución sobre un instrumento tranquilo, con pocas actualizaciones, puede quedarse en el sandbox más allá de
sandboxMinutes, hasta las 24 horas, y entonces se juzga con lo que ha recibido. - Solo se puede fijar al arrancar la ejecución. No es uno de los parámetros que acepta
PUT /live/{runId}/params: para cambiarlo, detén la ejecución y vuelve a arrancarla. - La ejecución devuelve el valor en vigor como
sandboxMinutescuando la lees (la respuesta de arranque,GET /strategy/{strategyId}/liveyGET /live/{runId}; la respuesta al detener una ejecución no lo incluye). Una ejecución que no tiene prueba no llevasandboxMinutesen absoluto (nuncanull): una arrancada antes de que existiera este campo, y una que empieza directamente enliveporque la estrategia ya ha pasado por la prueba."sandbox": truepide la prueba, y entonces se aplica el mismo tiempo.
Listar tus ejecuciones
GET /live (necesita un token Bearer) devuelve todas las ejecuciones que has arrancado — cualquier stage, cualquier estado desired, cualquier visibility — de más nueva a más antigua, paginado
igual que GET /live/public (cursor/limit, _links.next.href). No filtra por state: una
prueba sandbox o una ejecución que ya has detenido sigue apareciendo, a diferencia de GET /live/public, que no necesita cabecera Authorization pero solo lista ejecuciones ajenas —
de cualquiera, la tuya incluida — que sean public y estén corriendo (RUNNING).
Leer una ejecución
GET /live/{runId} (necesita un token Bearer) devuelve una de tus ejecuciones por su propio id, sea cual
sea su stage, su estado desired o su visibility y por mucho tiempo que haga que la detuviste: el mismo
estado que da GET /strategy/{strategyId}/live, más updatedAtMs, cuándo cambió la ejecución por última vez.
Ese valor solo avanza, así que si mantienes tu propia copia de una ejecución, aplica una lectura solo si su updatedAtMs es mayor que el que ya tienes. Una ejecución que no es tuya, o que no existe, responde 404; una
ejecución que otra persona ha hecho pública se encuentra con GET /live/public, no aquí.
Visibilidad
Una ejecución es private por defecto — solo tú puedes leer su estado o recibir sus señales. Fijar visibility: public (mediante PATCH /live/{runId}) hace dos cosas:
- aparece en el catálogo de
GET /live/public, listada sin revelar quién es su dueño ni qué estrategia la ejecuta; - su canal de señales (ver abajo) acepta una suscripción WebSocket de cualquiera, no solo de ti.
public es lo que pides, y surte efecto cuando la ejecución está en la etapa live: cuando se promueve, o de inmediato en una ejecución que arranca ahí. Hasta entonces —
mientras es una prueba sandbox — solo tú puedes leerla, por el canal y por las rutas de lectura, y
no aparece en el catálogo; nada de lo que hiciste hay que repetirlo en la promoción.
Quién puede leer qué, según la ejecución:
| La ejecución | Suscribirse a su canal y leer .../signals, .../paper | Listada en GET /live/public |
|---|---|---|
| Cualquier ejecución tuya | Tú, siempre | — |
private | Solo tú | No |
public, todavía en el sandbox | Solo tú (public surte efecto en la promoción) | No |
public, promovida a live | Cualquiera | Sí, mientras está corriendo |
Una URL de flujo es aparte de todo esto: es un secreto que creas
para una ejecución, y quien la tenga puede leer las señales de esa ejecución en cualquiera de las dos etapas,
diga lo que diga su visibility. Tú decides quién la tiene.
relay es aparte: solo decide si las señales de una ejecución se empujan por el canal WebSocket
(opt-in, en cualquiera de las dos etapas) y nunca quién puede leerlas. GET /live/{runId}/signals sirve las señales de una ejecución hayas pedido relay o no.
Volver a private también desconecta a cualquiera que esté suscrito en ese momento a ese canal —
en el mejor esfuerzo, y no deshace el cambio de visibilidad si la desconexión en sí falla.
Parámetros en tiempo de ejecución
params en POST /strategy/{strategyId}/live solo fija los valores con los que arranca una
ejecución. Para cambiar uno mientras la ejecución sigue corriendo, llama a PUT /live/{runId}/params (o la llamada WebSocket equivalente live.params de más abajo — ambas pasan
por la misma validación y aterrizan en el mismo valor en el mismo instante). Cada clave debe ser
una que tu estrategia declare; una clave no declarada es 400.
Un 409 significa que la estrategia compilada de esta ejecución no tiene registro de los parámetros
que declara, así que no se pueden cambiar mientras corre. Una ejecución conserva la versión compilada
con la que arrancó: registra de nuevo la estrategia (POST /strategy con el mismo fuente, que la
compila otra vez) y arranca una ejecución nueva.
El effectiveAtMs de la respuesta no es “ahora” — son unos segundos más adelante, el primer
momento en que el nuevo valor está garantizado que se aplique. Este margen existe para que, si una
ejecución tiene más de un worker de ejecución detrás, todos adopten el cambio en el mismo punto en
lugar de que uno lo aplique unos eventos antes que el otro.
PUT /live/6TzAPiPpsOWwBLdLBZCxwH/params
{"params": {"emaFastPeriod": "12"}}
200
{"runId": "6TzAPiPpsOWwBLdLBZCxwH", "paramsVersion": 2, "effectiveAtMs": 1758330015000} Comandos
POST /live/{runId}/commands le dice algo a una estrategia en marcha sin reiniciarla, para una estrategia que
implementa CommandRequestHandler del motor — una estrategia Java directamente (consulta Programar estrategias en Java), o una estrategia QTScript mediante onCommand { } (consulta QTScript). Acepta {"command": "<texto>"} — una
cadena simple — y un
objeto properties opcional, de tu elección, que viaja sin cambios hasta el propio manejador de la estrategia; command y properties son las únicas claves que puede llevar el cuerpo. Responde 202 con commandId y effectiveAtMs, la posición de mercado en la que lo aplica cada ejecución detrás del run.
Un comando es transitorio, a diferencia de un parámetro: es un evento, no un valor guardado, y nada de él se
escribe en la ejecución. Una réplica que se reinicia reproduce solo su historial de mercado reciente, así que un
comando de antes de esa ventana simplemente no le llega — un par que ya estaba corriendo cuando llegó lo aplica, uno
que arranca después no. Todo lo que la estrategia necesite recordar entre reinicios va en un parámetro
(PUT /live/{runId}/params), que sí tiene un valor guardado.
Un 409 significa una de cuatro cosas, cada una con su propio mensaje: la ejecución no está corriendo; la ejecución no tiene ninguna fuente de datos de mercado adjuntada, así que no hay nada a lo que entregar el comando (consulta Adjuntar y quitar una fuente); la estrategia
compilada de esta ejecución no tiene registro de si maneja comandos (regístrala de nuevo y arranca una ejecución
nueva, igual que el 409 de params); o la estrategia no implementa CommandRequestHandler en absoluto. Un 503 significa que el comando no se pudo entregar ahora mismo y no se envió — no hay una vía alternativa para un
evento como sí la hay para una fila de parámetro, así que reintenta la petición misma.
POST /live/6TzAPiPpsOWwBLdLBZCxwH/commands
{"command": "flatten", "properties": {"instrument": "BTC/USDT"}}
202
{"runId": "6TzAPiPpsOWwBLdLBZCxwH", "commandId": "0e3f2f1a-9c4b-4d3e-8a2f-6b7c5d4e3f21", "effectiveAtMs": 1758330015000} Recibir señales y actualizar parámetros en vivo: la conexión WebSocket
Sondear GET .../live te dice el estado de la ejecución; no transmite su salida. Para recibir
las señales de una ejecución a medida que ocurren, o para enviar una actualización de parámetros
por la misma conexión en lugar de una llamada REST aparte, abre una conexión WebSocket.
La conexión habla el protocolo cliente de Centrifugo v6 (JSON). Su
contrato legible por máquina es asyncapi.yaml, junto al spec OpenAPI: la URL,
cada trama, los nombres de canal, la llamada live.params y los códigos de error, con el payload
de la señal compartido con el esquema REST LiveSignal.
Los SDKs de Java y TypeScript ya envuelven esta conexión (connectLive) — consulta Clientes y SDKs — así que con uno de ellos puede que no necesites hablar el
protocolo directamente. El SDK de Python no: cubre la parte REST de una ejecución en vivo, señales retenidas incluidas, y
un programa en Python recibe las señales según ocurren mediante una URL de flujo. Yendo directo, el cliente más sencillo es una librería oficial de
Centrifugo — centrifuge (JavaScript/TypeScript), centrifuge-java, centrifuge-python y otras — porque ya se encarga de los pings, la
renovación del token y la reconexión que se describen abajo. Con una, solo aportas la URL, una
función que genera un token, el nombre del canal y el método RPC.
Las señales solo llegan a este canal para una ejecución arrancada con relay: true (campo propio
de POST .../live, false por defecto). Llegan desde la primera señal de la ejecución, también en la
etapa sandbox, donde solo tú puedes suscribirte; el mismo canal continúa sin cambios cuando la
ejecución se promueve a live, sobre la misma suscripción: stage pasa de sandbox a live y no
hay que rehacer nada. La ejecución tarda un rato en arrancar en la etapa live, así que el canal puede
quedarse en silencio varios minutos en torno a la promoción; lo que la ejecución produjo entretanto
llega después en orden, y cada señal llega una sola vez. GET/PATCH .../live devuelven en relay lo que se pidió.
- Genera un token.
POST /live/token(JWT bearer, igual que cualquier otro endpoint) devuelve untokende corta duración y suexpiresAtMs. - Conecta. Abre un WebSocket a
wss://rt.qtsurfer.net/connection/websockety envía, como primer mensaje:
Una conexión exitosa responde con tu propio id de{"id": 1, "connect": {"token": "<el token del paso 1>"}}client, y cuánto le queda al token:{"id": 1, "connect": {"client": "<id-de-cliente>", "expires": true, "ttl": 600, "ping": 25, "pong": true}}ttlypingestán en segundos. Un token que no se acepta cierra el socket con el código de cierre3500(invalid token). Desde un cliente que no es un navegador ni Node, una biblioteca WebSocket de Python por ejemplo, esta dirección puede rechazarse en el borde de la red con un403, y unUser-Agento unOriginpropios no lo cambian. Ese cliente lee la ejecución con una URL de flujo en su lugar. - Suscríbete al canal de señales de la ejecución, llamado
sig:<runId>— por ejemplosig:6TzAPiPpsOWwBLdLBZCxwH:
Puedes suscribirte al canal de cualquier ejecución de esta forma, pero la conexión solo se admite realmente en él si eres el dueño de esa ejecución, o es{"id": 2, "subscribe": {"channel": "sig:6TzAPiPpsOWwBLdLBZCxwH"}}publicy ha alcanzado la etapalive— el canal de una ejecución privada ajena, y el de una ejecución pública que todavía está en elsandbox, rechazan la suscripción con{"id": 2, "error": {"code": 103, "message": "permission denied"}}. Cada señal llega entonces como una tramapush, sinid; la señal en sí es supub.data, en la forma de abajo:
Si la ejecución se pone en privado mientras estás suscrito y no es tuya, el servidor te retira con{"push": {"channel": "sig:6TzAPiPpsOWwBLdLBZCxwH", "pub": {"data": {"v": 1, "signalId": "…", …}, "offset": 42}}}{"push": {"channel": "sig:…", "unsubscribe": {"code": 2000, "reason": "server unsubscribe"}}}, y no te vuelve a suscribir. - Llama a
live.params(la forma WebSocket dePUT /live/{runId}/params, solo para el dueño):
Éxito:{"id": 3, "rpc": {"method": "live.params", "data": {"runId": "6TzAPiPpsOWwBLdLBZCxwH", "params": {"emaFastPeriod": "12"}}}}
Fallo (refleja el mismo 400/404/409 del endpoint REST):{"id": 3, "rpc": {"data": {"runId": "6TzAPiPpsOWwBLdLBZCxwH", "paramsVersion": 2, "effectiveAtMs": 1758330015000}}}{"id": 3, "error": {"code": 404, "message": "no such run"}} - Mantén la conexión viva. El servidor envía una trama vacía
{}como ping; responde a cada una con{}(eso es lo que pide"pong": trueen la respuesta de conexión). Si no llega nada durante bastante más depingsegundos, trata la conexión como muerta y reconecta. - Renueva el token antes de que se acabe el
ttl, sobre la misma conexión — genera uno nuevo conPOST /live/tokeny envíalo:
que responde{"id": 4, "refresh": {"token": "<un token nuevo>"}}{"id": 4, "refresh": {"expires": true, "ttl": 600}}. Tus suscripciones no se ven afectadas. Una conexión cuyo token no se renueva a tiempo se cierra con el código de cierre3005(connection expired); reconecta con un token nuevo.
Algunos detalles del protocolo a conocer si escribes tu propio cliente: cada respuesta lleva el id del comando que contesta, las tramas que el servidor envía por su cuenta (pushes, pings) no
llevan ninguno, y una trama WebSocket puede contener varias respuestas, un objeto JSON por línea.
Una página de navegador servida desde el origen de otro sitio se rechaza en el upgrade del
WebSocket (403); un cliente que no envía cabecera Origin, como un programa del lado del
servidor o un SDK, no se ve afectado.
Tras una desconexión, el canal no reproduce por sí solo lo que te perdiste: léelo de vuelta con history mientras la ejecución está en la etapa sandbox (siguiente sección),
o con GET /live/{runId}/signals (más abajo) en cualquiera de las dos etapas, deduplicando por signalId.
Leer señales anteriores por la conexión
Un cliente que se conecta tarde, o que estuvo desconectado un momento, puede leer por la misma conexión las
señales que una ejecución en la etapa sandbox acaba de producir, sin una llamada REST. Envía history en un
canal al que estés suscrito:
{"id": 5, "history": {"channel": "sig:6TzAPiPpsOWwBLdLBZCxwH", "limit": 300}} Responde con las señales, de la más antigua a la más reciente, cada una con el offset con el que se empujó,
y con el epoch y el offset más reciente que guarda el canal:
{"id": 5, "history": {"publications": [{"data": {"v": 1, "signalId": "…", …}, "offset": 41}, {"data": {"v": 1, "signalId": "…", …}, "offset": 42}], "epoch": "SQRGfEAq", "offset": 42}} - Qué contiene. Solo las señales de la etapa
sandbox: las 300 más recientes, sea cual sea su antigüedad, hasta 5 minutos después de la última señal desandboxde la ejecución, cuando se vacía. No se guarda nada de la etapalive: una vez promovida la ejecución, el historial deja de crecer y se vacía 5 minutos después de la última señal desandbox. Para leer más atrás, o cualquier señal delive, usaGET /live/{runId}/signals(más abajo). Una ejecución que arranca enlive(consulta Volver a arrancar no repite la prueba) nunca tiene historial aquí; arráncala con"sandbox": truesi lo necesitas. - Nada se reproduce por sí solo. Suscribirte, y volver a suscribirte tras una desconexión, nunca entrega
señales pasadas;
historyes la única forma de leerlas. - Quién puede leerlo. Una conexión suscrita al canal; mientras una ejecución está en la etapa
sandbox, ese es su propietario. Una conexión que no está suscrita recibe el error103. - Cómo usarlo. Suscríbete primero, para no perder nada, y luego llama a
historyconlimit300. Las señales empujadas entretanto y las de la respuesta se solapan: conserva una sola copia porsignalId. - Tras una desconexión. Vuelve a suscribirte y llama a
historyconsince: eloffsetde la última señal que tienes y elepochde una respuesta anterior dehistory:
La respuesta contiene solo las señales posteriores a esa posición. Un cliente que aún no ha llamado a{"id": 6, "history": {"channel": "sig:6TzAPiPpsOWwBLdLBZCxwH", "limit": 300, "since": {"offset": 42, "epoch": "SQRGfEAq"}}}historyno tieneepoch: llámalo una vez sinsince. - Cuando se pierde el historial. Si la plataforma pierde el historial del canal (por ejemplo cuando se
reinicia el servicio en tiempo real), su
epochcambia, y unsincecon el antiguo responde{"id": 6, "error": {"code": 112, "message": "unrecoverable position"}}. Vuelve a llamar ahistorysinsince; lo que se produjo antes de la pérdida solo está disponible enGET /live/{runId}/signals. limit0no devuelve señales, solo la posición (epochyoffset).
Forma de la señal
Cada señal empujada en un canal sig:<runId> (el pub.data de la trama push):
{
"v": 1,
"signalId": "…",
"runId": "6TzAPiPpsOWwBLdLBZCxwH",
"stage": "live",
"paramsVersion": 2,
"type": "hint",
"kind": "BUY",
"eventTsMs": 1758330012000,
"emittedAtMs": 1758330012040,
"instrument": {"exchange": "binance", "segment": "spot", "symbol": "BTC/USDT"},
"order": {"orderKind": "MARKET", "price": null, "amount": null, "stopPrice": null, "trailPct": null},
"data": {},
"regenerated": false,
"digest": "…"
} | campo | significado |
|---|---|
signalId | Id estable de esta señal exacta — deduplica con él si tu conexión se reconecta a mitad de flujo. |
stage | sandbox o live: la etapa en la que estaba la ejecución cuando produjo la señal. Solo tú recibes una señal sandbox por este canal; todos los admitidos en el canal reciben las live. |
paramsVersion | El conjunto de parámetros vigente cuando se produjo esta señal. |
type | hint, info, marker, o command — más paper al leer el histórico de una ejecución mix (consulta Paper trading; los elementos paper nunca se empujan por este canal). |
kind | BUY/SELL para un hint; el nombre del comando para un command; ausente en otro caso. |
eventTsMs | Hora de mercado en que se produjo la señal. |
emittedAtMs | Hora en que se publicó — siempre ≥ eventTsMs. |
order | Presente solo para un hint. |
data | El payload de forma libre propio de la señal: lo que la estrategia puso ahí con signal.set(...). Quien pueda leer la ejecución puede leerlo, así que en una ejecución public es público. Una señal cuyo data pese más de 8 KiB (8.192 bytes de su JSON) no se empuja por este canal; la ruta de historial la devuelve entera. |
regenerated | true solo para una señal republicada para rellenar un hueco en el histórico registrado — siempre false para una señal que ves por primera vez. |
digest | Hash del contenido, para verificar que dos entregas independientes de la misma señal concuerdan. |
Quién es el dueño de la ejecución, qué estrategia o compilación produjo una señal, y la posición exacta de datos de mercado detrás de ella nunca se incluyen en este canal, sea la ejecución pública o privada.
Un flujo WebSocket plano de una ejecución
La conexión de arriba es un protocolo: un token, una suscripción, tramas propias. Una URL de flujo es la
alternativa sencilla. Es una sola dirección que abres como un WebSocket corriente — desde un script, desde una
herramienta de línea de comandos como websocat, o desde un servicio tuyo que
reenvía tus señales a otros — y cada señal de la ejecución llega como una trama de texto JSON. No hay token
que generar, nada a lo que suscribirse y nada que enviar.
También es la vía de entrada para un cliente que no es un navegador ni Node. La conexión con token, de arriba, puede rechazarse a un cliente así, una biblioteca WebSocket de Python por ejemplo, en el borde de la red; una URL de flujo no lleva clave ni token y se acepta desde cualquier cliente.
Está pensada para tus propias pruebas, para clientes sencillos y para servicios que reenvían tus señales a muchas conexiones por su cuenta: esta dirección está limitada en cuántas conexiones acepta (consulta abajo), así que un servicio que atiende a muchos lectores mantiene una sola conexión y reparte las señales él mismo.
Está disponible desde la etapa sandbox, de modo que puedes probarla antes de que la ejecución se promueva, en los
planes que pueden difundir (los planes Pro y Elite: tu plan es el tier que devuelve GET /account).
Cualquier otro plan se rechaza con 402, nombrando el plan.
Conseguir una
Pídela al arrancar la ejecución, con stream: true en POST /strategy/{strategyId}/live. Activa relay, y
no se puede añadir a una ejecución más tarde. La respuesta lleva la dirección como streamUrl:
{
"runId": "5t5oAmQ4PD0lQRoCU58uE0",
"stage": "SANDBOX",
"relay": true,
"streamUrl": "wss://…"
} GET /strategy/{strategyId}/live devuelve la misma streamUrl mientras la ejecución esté corriendo y tu plan lo
permita. No está en ninguna otra respuesta: ni cuando la ejecución está detenida, ni en GET /live/{runId}, ni
en el catálogo público. Usa la dirección exactamente como se devuelve; es opaca.
Trátala como una contraseña. Cualquiera que la tenga puede leer las señales de la ejecución, también las del sandbox. No la pongas en un repositorio, un log, una captura de pantalla ni un chat compartido. Si puede haberse filtrado, rótala. Eres responsable de a quién se la das y de lo que se haga con las señales que reenvías.
Qué llega
Cada trama de texto es exactamente una señal, el mismo objeto que el pub.data de un envío del canal sig:<runId> (consulta Forma de la señal), stage incluido, de modo que quien recibe
puede distinguir una prueba de sandbox de la real. No hay mensaje de conexión ni envoltorio alguno, y nada que
responder: tu biblioteca de WebSocket responde a los pings que envía el servicio. Una señal cuyo data pese más
de 8 KiB no se envía, igual que en el canal.
websocat "$STREAM_URL" Todo lo que envíes se ignora, y una trama tuya de más de 1 KiB cierra la conexión.
Reconectar
Las conexiones terminan (un reinicio del servicio, un fallo de red), así que un cliente reconecta. Para reanudar
sin huecos, añade el signalId de la última señal que recibiste como parámetro de consulta, ?after=<signalId>: el servicio envía las señales posteriores a esa, y sigue en vivo, cada señal una vez.
Solo conserva las señales más recientes de una ejecución, unos pocos minutos y menos para una ejecución cuyas
señales son grandes. Si la señal que nombras ya no se conserva, la conexión se cierra con 4001 antes de enviar
ninguna trama: lee lo que te perdiste con GET /live/{runId}/signals y vuelve a conectar sin after. Hagas lo que hagas, deduplica por signalId.
Límites, y por qué se cierra una conexión
- Cuenta con 2 conexiones abiertas a la vez en una URL (la segunda cubre el solape mientras reconectas), y 10 desde una misma dirección de cliente. Son los números para los que diseñar, no muros exactos: el servicio
cuenta las conexiones en más de un sitio, así que a veces se acepta una de más. Una conexión que se rechaza se
cierra con
1013una vez abierta, o se deja fuera antes de abrirse, cuando falla el propio handshake (con429, o con un error de pasarela como502). - Un lector que no sigue el ritmo se desconecta; nunca ralentiza a nadie más.
- Una dirección de cliente que insiste en presentar URL que no funcionan se rechaza durante un tiempo (
429).
Una dirección que no es una URL de flujo válida, o una que ha dejado de funcionar, responde 404 al intento de
conexión, sin decir nunca cuál de las dos; 503 significa que lo intentes de nuevo en un momento. Una vez abierta,
una conexión puede cerrarse con:
| Código | Significado | Qué hacer |
|---|---|---|
1008 | La URL ya no funciona: se rotó o se revocó, la ejecución se detuvo, o tu plan ya no te permite difundir. | No reintentes la misma URL. Lee GET /strategy/{strategyId}/live para la actual. |
1013 | Demasiadas conexiones en esta URL o desde esta dirección, la conexión no pudo seguir el ritmo, o el servicio no pudo confirmar la URL por un momento. | Espera y reconecta, con after. |
4001 | La señal de after ya no se conserva. | Lee el historial y conecta sin after. |
1001 | El servicio se está reiniciando. | Reconecta enseguida, con after. |
1009 | Enviaste una trama de más de 1 KiB. | No envíes tramas. |
Si tu plan deja de permitirte difundir, la URL deja de mostrarse y las conexiones abiertas se cierran con 1008,
normalmente en menos de un minuto; si el plan vuelve a permitirte difundir, la misma URL vuelve a funcionar.
Rotar y revocar la URL
POST /live/{runId}/streamda a la ejecución una dirección nueva y retira la antigua: las conexiones en la dirección antigua se cierran con1008en unos 15 segundos. Solo para una ejecución en marcha que se arrancó con un flujo.DELETE /live/{runId}/streamla revoca para siempre: las conexiones se cierran y la dirección responde404. La ejecución sigue corriendo, y no se le puede volver a añadir un flujo: arranca la ejecución de nuevo constream: truepara conseguir uno nuevo. Siempre está permitido, sea cual sea tu plan, y repetirlo no es un error.
Leer las señales que una ejecución ya produjo
El canal de arriba es solo en vivo: lleva lo que ocurre mientras estás conectado, y solo para una
ejecución que pidió relay. GET /live/{runId}/signals sirve el registro en su lugar — las
señales de una ejecución se guardan de todas formas, así que esto funciona tanto si relay estuvo
activo como si no, y en ambas etapas. Úsalo para ponerte al día tras una desconexión, para leer una
ejecución a la que nunca hiciste relay, o simplemente para paginar hacia atrás sobre lo que ya ha
pasado.
GET /v1/live/6TzAPiPpsOWwBLdLBZCxwH/signals?sinceMs=1758330000000&limit=20
200
{
"signals": [ { "signalId": "…", "eventTsMs": 1758330012000, … } ],
"availableSinceMs": 1757725212000,
"_links": {"next": {"href": "/v1/live/6TzAPiPpsOWwBLdLBZCxwH/signals?cursor=eyJzZXEiOjQyfQ&limit=20"}}
} Cada entrada tiene la misma forma que empuja el canal — la tabla de arriba aplica sin cambios,
salvo que aquí stage es la etapa en la que estaba la ejecución cuando se produjo la señal, así
que las señales de una ejecución sandbox se leen como sandbox. Pagina con _links.next mientras
esté presente; limit es 20 por defecto y su tope es 100. Legible por el dueño de la ejecución, y
por cualquiera si la ejecución es public — la misma regla que aplica el canal a una suscripción.
Filtrar por instrumento
instrument es opcional y reduce la página sin cambiar nada más:
instrument | devuelve |
|---|---|
omitido, o * | todos los instrumentos que cubre la ejecución |
BTC/USDT | solo ese par |
*/USDT | cualquier base contra esa cotizada |
BTC/* | esa base contra cualquier cotizada |
BTC/USDT,ETH/EUR | cada par de la lista |
Los símbolos coinciden exactamente, mayúsculas incluidas — pásalos tal como los reporta esta API
(como aparecen en sources de la propia ejecución, o en instrument.symbol de una señal).
Filtrar por tipo
type reduce a uno o más tipos de señal, separados por comas: hint, info, marker, command, paper. Se combina con instrument — ?type=hint&instrument=*/USDT son todos los hints de un par
USDT. Ambos filtros se arrastran en _links.next, así que seguirlo mantiene la misma selección.
La ventana se mueve, y los cursores caducan
Las señales se guardan durante un margen limitado, y las más antiguas se descartan continuamente a medida que llegan otras nuevas. Cuánto puedes leer hacia atrás no es por tanto un número fijo de horas: una ejecución que produce muchas señales consume ese margen más rápido, y también lo hacen otras ejecuciones que lo comparten. Dos consecuencias a tener en cuenta:
availableSinceMsen cada respuesta es el momento más antiguo todavía respondible. Pedir unsinceMsanterior a eso no es un error: te sirven desdeavailableSinceMsen adelante, y el campo te dice que eso es lo que pasó.Un cursor puede caducar, y en una ejecución con mucho tráfico puede caducar en minutos. Cuando la posición a la que apunta ya se descartó, la siguiente página responde
410en vez de servir en silencio una página recortada que parece completa:{"code": 410, "message": "the cursor's position is no longer retained by the signal stream (it now starts at availableSinceMs=1757725212000)"}Trátalo como un resultado normal de paginar un sistema en vivo, no como un fallo: lee el
availableSinceMsque indica y vuelve a empezar desde ahí. Si estás paginando para mostrar un historial largo, trae las páginas que necesites en una sola pasada en vez de mantener un cursor durante el tiempo de reflexión de un usuario.
Paper trading
Arranca una ejecución con un bloque paper y sus hints se ejecutan en simulación desde el primer
tick, como los ejecutaría un backtest — fills, operaciones cerradas, equity y los mismos KPIs que
reporta un backtest:
"paper": {"initialFunding": 1000, "feeRate": 0.001, "percentAmountToLock": 20} Léelo con GET /live/{runId}/paper y GET /live/{runId}/paper/equity. Todo sobre él — la
configuración, una cuenta por moneda de cotización, la curva de equity, la salida mix y los
huecos — está en Paper trading en ejecuciones en vivo.