Órdenes vs. trades vs. fills en Hyperliquid

En Hyperliquid, una orden es una instrucción de compra o venta, un trade es un emparejamiento entre dos órdenes, y un fill es el lado de una cuenta en ese emparejamiento. Cada trade produce exactamente dos fills, uno por cuenta. Esta guía recorre el payload de cada registro en HyperCore, las claves que los unen y los casos de fallo que rompen la conciliación en producción.

Los tres registros llegan por streams distintos y cambian en momentos distintos, así que el código que los trata como lo mismo termina desincronizado del exchange. Todo lo que sigue se verificó con datos en vivo de la mainnet de Hyperliquid, y los dos scripts de esta guía funcionan hoy contra la API pública de Hyperliquid.

¿Cuál es la diferencia entre una orden, un trade y un fill?

HyperCore es el motor de exchange nativo de Hyperliquid, separado del entorno de smart contracts HyperEVM. Ejecuta un libro de órdenes completamente onchain, así que cada colocación de orden, cada cancelación y cada emparejamiento queda registrado en un bloque.

Los tres registros describen esa actividad desde ángulos distintos:

Un trade es la vista que tiene el mercado de un emparejamiento, por eso lista ambas cuentas y ninguna comisión. Un fill es la vista que tiene la cuenta del mismo emparejamiento, así que incluye la comisión que pagó esa cuenta, la posición que tenía antes y la orden de la que proviene. Las actualizaciones de orden describen la orden en sí y, como muestra la siguiente sección, son más escasas de lo que la mayoría de los desarrolladores espera.

Si estás construyendo un bot de trading o un rastreador de portafolio, los fills son la fuente de verdad de lo que se ejecutó, y las actualizaciones de orden son la fuente de verdad de lo que sigue en el libro.

¿Cómo es una actualización de orden?

Una actualización de orden se emite cuando cambia el estado de una orden. El payload envuelve la orden en un registro de estado:

Los campos más importantes para el seguimiento del estado son:

• oid. El ID de orden asignado por el exchange. Los fills lo referencian, así que es la clave de unión entre una orden y sus ejecuciones.
• origSz y sz. El tamaño al colocar la orden y el tamaño que sigue en el libro al momento de este registro de estado.
• status. El nuevo estado. open, filled, canceled y triggered son los más comunes, y hay una larga cola de motivos específicos de rechazo y cancelación como badAloPxRejected, reduceOnlyCanceled, selfTradeCanceled y liquidatedCanceled.
• tif. Time in force (vigencia de la orden). Gtc permanece en el libro hasta que se cancela, Alo (add liquidity only) se rechaza si cruzaría el spread, y Ioc (immediate or cancel) toma lo que puede y descarta el resto.
• cloid. Un ID de orden opcional que define el cliente, útil para asociar una orden con la solicitud que envió tu sistema.

La referencia de userOrderUpdates lista cada valor de estado observado en la salida de los nodos e indica que la lista no es exhaustiva. Trata un string de estado desconocido como un estado terminal que registras e investigas, no como un error fatal.

Tres comportamientos de las actualizaciones de orden rompen las máquinas de estado ingenuas.

Un fill parcial no produce una actualización de orden. Cuando observamos cuentas en vivo, una orden en el libro que se ejecutó parcialmente emitió open, luego uno o más fills, y después nada hasta llegar a un estado terminal. Cuando una orden así se cancela más tarde, el registro canceled incluye el tamaño restante en sz. Si necesitas el tamaño restante en vivo de una orden abierta, calcúlalo a partir de los fills o consulta las órdenes abiertas bajo demanda.

Un estado filled no siempre significa ejecución completa. Una orden Ioc que empareja parte de su tamaño termina con estado filled y un sz distinto de cero, que es el remanente no ejecutado que se descartó. En una muestra de 45 segundos de una cuenta activa, 72 de las 127 órdenes Ioc que llegaron a filled todavía tenían tamaño restante. Revisa sz antes de tratar una orden como completa.

El campo hash solo se completa en open. Los registros cancelados y rechazados tienen un hash nulo, así que el hash de transacción no sirve como clave para el historial de órdenes.

¿Cómo es un trade?

El stream trades publica cada emparejamiento de un mercado. Cada registro es pequeño:

side es el lado del taker, donde A (ask) significa que el taker vendió y B (bid) significa que el taker compró. users siempre lista primero al comprador y después al vendedor, así que el taker es users[0] cuando side es B y users[1] cuando side es A. En el ejemplo de arriba el taker vendió, lo que hace que 0xe4f5...c0c4 sea el taker y 0x4cf1...e717 el comprador cuya orden estaba en el libro.

Una orden taker que barre varias órdenes del libro produce varios trades. Cada uno tiene su propio tid, y comparten el mismo hash y time porque una sola transacción los causó a todos. Eso significa que hash identifica la transacción, no el trade.

Algunos trades llevan un hash todo en ceros. En una muestra de 80 trades recientes en ocho mercados, 7 tenían hash en cero. El que rastreamos resultó ser un tramo de TWAP, que el exchange ejecuta en nombre del usuario sin una nueva transacción firmada, y la documentación del endpoint info de Hyperliquid confirma que los fills de TWAP llevan un hash en cero. El código que une trades con transacciones por hash tiene que manejar ese caso.

Usa trades para datos de todo el mercado, como la cinta de operaciones, el volumen y los gráficos de precios. Para cualquier cosa sobre una cuenta específica, suscríbete a los fills, porque el registro de trade no tiene comisiones, ni ID de orden, ni contexto de posición.

¿Cómo es un fill?

Un fill es el lado de una cuenta en un trade. Estos son los dos fills del trade de ETH de arriba, obtenidos de mainnet:

Ambos fills comparten el tid, el precio, el tamaño y el tiempo del trade. Todo lo demás es específico de la cuenta:

• oid. La orden que produjo este fill. El comprador y el vendedor tienen cada uno la suya.
• crossed. true para el taker, false para el maker (la orden que estaba en el libro).
• fee. La comisión que pagó esta cuenta. Un valor negativo es un reembolso para el maker, como en el fill del comprador de arriba. builderFee, cuando está presente, es la parte que se paga a un builder (un frontend o app que enrutó la orden) y ya está incluida en fee.
• startPosition, dir y closedPnl. El tamaño de la posición antes del fill, una etiqueta de visualización como Open Long o Close Short, y el PnL realizado que cerró este fill. Con ellos puedes reconstruir el historial de posiciones solo a partir de los fills.
• liquidation. Nulo en los fills normales. En una liquidación, indica la cuenta liquidada, el precio de marca y si la liquidación pasó por el mercado o por el backstop.
• twapId. La orden TWAP que produjo el fill, cuando la hay.

Las comisiones, los reembolsos, el PnL realizado y los detalles de liquidación existen solo en los fills, así que cualquier libro contable o reporte de impuestos tiene que construirse a partir de ellos.

¿Cómo se unen las órdenes, los trades y los fills?

Dos claves cubren casi todas las uniones:

Las dos primeras filas son la base sobre la que conviene construir. Verificamos la unión de trade a fill con datos en vivo: tomamos un trade de trades y luego consultamos los fills de ambas direcciones del array users. Cada dirección tenía exactamente un fill con el tid del trade, uno con crossed: true y otro con crossed: false.

El tamaño restante de una orden se deriva de la unión de fill a orden:

Esa fórmula se cumple para toda orden, y es la que debes preferir en lugar del sz de la última actualización de orden que viste.

¿Cómo concilias el estado de las órdenes a partir de los fills?

El script de abajo se suscribe a las actualizaciones de orden y a los fills de una cuenta, lleva la cuenta del tamaño ejecutado de cada orden a partir de sus fills y verifica ese cálculo contra el sz que reporta el exchange cuando la orden llega a un estado terminal. Funciona con una versión reciente de Node con soporte integrado de WebSocket y no necesita dependencias.

Ejecútalo contra cualquier dirección activa, por ejemplo una tomada del array users de un trade reciente. La salida de una ejecución de 45 segundos contra una cuenta con mucha actividad se veía así:

La primera línea es el snapshot con el que empieza la suscripción. Las tres siguientes son una orden Ioc que barrió dos órdenes del libro, produjo dos fills y terminó como filled con 7.52 HYPE sin ejecutar. Las dos últimas son una orden Alo que quedó en el libro, ejecutó 0.02 ZEC como maker y se canceló con el resto todavía abierto. En las 115 órdenes que llegaron a un estado terminal con fills en esa ejecución, el tamaño restante derivado de los fills coincidió siempre con el sz que reportó el exchange.

Tres detalles del script son importantes. Los tamaños son strings, y sumarlos como floats de JavaScript produce desviaciones de redondeo en órdenes de larga duración con muchos fills parciales, así que el script los suma como enteros escalados. Además, la verificación se ejecuta desde ambos handlers. Un estado terminal guarda el sz reportado, y cualquier fill que llegue después vuelve a ejecutar la comparación, así que una orden cuyo último fill llega después de su estado filled muestra waiting for fills y luego ok en lugar de una falsa discrepancia. Por último, los fills se deduplican antes de tocar el estado, así que un fill que llega dos veces, por ejemplo en el snapshot después de una reconexión o desde un backfill que se superpone con el stream en vivo, se cuenta una sola vez.

La documentación de WebSocket de Hyperliquid describe tid como un hash de 50 bits e indica que el tiempo de bloque, coin y tid juntos forman el ID de trade único a nivel global, así que el script usa como clave de los fills coin, time y tid. Un trade y sus dos fills comparten los tres. Esa clave es única para una sola cuenta. Si sigues muchas cuentas en un mismo proceso, agrégale user, porque ambos lados de un trade comparten el resto.

¿Qué falla en producción?

La mayoría de los bugs de conciliación vienen de los siguientes casos.

• Entregas superpuestas. Cuando vuelves a suscribirte, el stream nativo userFills empieza con un snapshot de fills recientes (isSnapshot: true), y un backfill se superpone con lo que el stream en vivo ya entregó. Deduplica los fills por user, coin, time y tid, y las actualizaciones de orden por oid más status más statusTimestamp.
• Secuencia entre streams. Las actualizaciones de orden y los fills llegan por canales separados. No asumas que un fill llega antes que el estado filled de su orden, ni al revés. Indexar el estado por oid, dejar que cualquiera de los dos eventos cree el registro y volver a ejecutar la verificación cuando llega un fill tardío, como hace el script, elimina esa dependencia.
• Desconexiones. Una suscripción WebSocket solo entrega lo que ocurre mientras está conectada, así que cualquier caída necesita un backfill. Guarda el tiempo del último fill que procesaste y consulta los fills desde ese punto, como se muestra abajo.
• Fills de tramos de TWAP. Los tramos de TWAP se ejecutan con un hash en cero. En la API pública de Hyperliquid, el fill de tramo que rastreamos apareció en userTwapSliceFills y no en userFillsByTime, así que un backfill que solo lee userFillsByTime puede perderlos.
• Estados desconocidos. Se agregan nuevos motivos de rechazo y cancelación. Maneja los valores desconocidos sin que el programa falle, y trata triggerCondition como un string de visualización. El precio de activación legible por máquina es triggerPx.
• Identificadores de mercado. Los valores de coin codifican el tipo de mercado. BTC es el perpetuo, los mercados spot usan strings @index como @107, los mercados de resultados usan #N, y los mercados HIP-3 desplegados por terceros usan dex:name, como se describe en la documentación de mercados, activos y DEX. Los valores de coin distinguen mayúsculas de minúsculas, así que compáralos de forma exacta y nunca los pases a minúsculas.
• Avanzar un checkpoint demasiado pronto. Persiste el tiempo de tu último fill solo después de que el fill se haya escrito en el almacenamiento. Si avanzas primero, una caída entre los dos pasos pierde un fill sin dejar rastro.

Hacer backfill de los fills de un rango de tiempo requiere un bucle corto. userFillsByTime devuelve los fills del más antiguo al más reciente, con un máximo de 2,000 por respuesta según la documentación del endpoint info de Hyperliquid, así que el bucle se reinicia en el tiempo más reciente que vio y deja que la misma clave de deduplicación absorba la superposición:

Contra la misma cuenta con mucha actividad, una ventana de 30 minutos devolvió 6,049 fills en cuatro páginas. Pasa el resultado por el mismo handler onFill que usa el stream, y el conjunto de deduplicación evita que la superposición entre el backfill y el stream en vivo se cuente dos veces.

La misma documentación indica que solo los 10,000 fills más recientes están disponibles a través de userFillsByTime. Al ritmo anterior, eso equivale a menos de una hora de historial, así que una caída más larga en una cuenta así de activa queda fuera de lo que el endpoint público puede devolver. Dimensiona tus alertas para que un consumidor desconectado se detecte con holgura dentro de esa ventana.

¿Cómo cambia esto el streaming de HyperCore de Alchemy?

El streaming de HyperCore en Alchemy usa el mismo envelope que las suscripciones nativas, así que los payloads de arriba y la lógica de unión no cambian. Las diferencias están en lo que cada frame te dice sobre su bloque de origen y en cuánto puede cubrir una sola suscripción.

Cada frame de datos incluye metadatos de nivel superior junto con el payload nativo, entre ellos subscriptionId, blockHeight y blockTime. Las actualizaciones de orden y los fills siguen llegando por canales separados, pero cada frame indica el bloque del que proviene, lo que te da un punto de referencia común cuando alineas los dos streams.

Las suscripciones también aceptan arrays. Las suscripciones nativas toman un solo user o coin, mientras que las nuestras aceptan users, coins y builders, así que una sola suscripción puede cubrir todo un conjunto de cuentas. Cada registro de fill y de orden incluye su user, lo que convierte la clave de deduplicación multicuenta de arriba en el caso por defecto en lugar del caso límite.

Algunos streams existen para que no tengas que derivarlos de un feed amplio:

• liquidationFills. Solo los fills que incluyen una liquidación, filtrados por mercado.
• builderFills y builderOrderUpdates. Fills y actualizaciones de orden atribuidos a una dirección de builder, para apps que enrutan órdenes y necesitan seguir su propio flujo y sus comisiones.
• allFills. Fills de todas las cuentas en los mercados seleccionados, con el esquema completo de fill en lugar del registro de trade, más reducido.

Para ejecutar el script de conciliación contra nuestro endpoint, apunta HL_WS_URL a la URL de WebSocket que recibes con el acceso anticipado, autentícate como se describe en la documentación del ciclo de vida de la conexión de HyperCore y suscríbete a userOrderUpdates en lugar de orderUpdates. Nuestros frames de actualización de orden envuelven los registros de estado en un array orders, así que léelos desde msg.data.orders en lugar de msg.data. Para el historial, nuestra API REST de HyperCore agregará userFillsByTime y historicalOrders con paginación basada en cursores. Ambos están documentados en la guía para consultar el historial de trading de una wallet, pero todavía no se pueden llamar, así que mientras tanto el script de backfill de arriba usa el endpoint público de Hyperliquid.

¿Cómo obtienes acceso al streaming de HyperCore?

El streaming de HyperCore está en acceso anticipado, como parte del trabajo en HyperCore que anunciamos en junio. Haces streaming desde nodos de Hyperliquid que operamos nosotros, así que no hay ningún hl-node que correr, y si ya construyes sobre Alchemy, lo habilitamos en la API key que usas hoy. Empieza con la descripción general de la HyperCore Data API para ver los streams y los métodos REST, y luego solicita acceso anticipado a HyperCore para obtener los detalles de conexión y trabajar directamente con nuestro equipo.

Si estás eligiendo entre transportes de streaming para el resto de tu stack, nuestra comparación de webhooks, WebSockets y gRPC cubre los trade-offs. Para el lado HyperEVM de Hyperliquid, consulta nuestra guía de RPC de Hyperliquid.