Hyperliquid orderUpdates WebSocket: Seguimiento del ciclo de vida de órdenes

Alcance y propósito del canal orderUpdates

El canal orderUpdates de Hyperliquid es una suscripción WebSocket de ámbito de usuario. Entrega transiciones de estado de órdenes solo para la cuenta especificada en la solicitud de suscripción. Un feed público de datos de mercado no puede sustituirlo porque las actualizaciones de órdenes son privadas del usuario autenticado. Según la documentación de suscripciones WebSocket de Hyperliquid, el mensaje de suscripción incluye un tipo y un objeto de suscripción que nombra el canal y, para canales de ámbito de usuario, la dirección del usuario.

Este canal es esencial para aplicaciones que necesitan visibilidad en tiempo real de los eventos del ciclo de vida de las órdenes, como paneles de trading, sistemas de gestión de órdenes y estrategias automatizadas. Complementa el estado de órdenes de Hyperliquid a través de la API de información de solo lectura al proporcionar actualizaciones basadas en push, pero no reemplaza las consultas históricas. Para una visión general más amplia de la conectividad de Hyperliquid, consulta la página de red de Hyperliquid.

• Ámbito de usuario: solo entrega órdenes de la cuenta suscrita.
• Requiere un mensaje de suscripción válido con la dirección del usuario.
• Complementa, pero no reemplaza, la API de información para el historial.

Formato del mensaje de suscripción e identificación del canal

Para recibir actualizaciones de órdenes, un cliente envía una solicitud de suscripción JSON-RPC 2.0 a través de una conexión WebSocket establecida. La solicitud debe incluir un objeto de suscripción con el nombre del canal y la dirección del usuario. Los nombres exactos de los campos y cualquier parámetro adicional están documentados y pueden variar según la versión de la API, por lo que siempre debes verificar contra el payload actual. La especificación JSON-RPC 2.0 define la semántica de solicitud/respuesta, mientras que la especificación JSON-RPC de Ethereum proporciona una referencia para patrones de suscripción similares, aunque Hyperliquid tiene su propia implementación.

Un mensaje de suscripción típico se parece al ejemplo de código a continuación. Ten en cuenta que la dirección del usuario debe estar en minúsculas o con checksum según lo requiera la API. Después de suscribirte, el servidor comenzará a enviar mensajes orderUpdates para ese usuario.

const WebSocket = require('ws');
const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

ws.on('open', () => {
  const subscribeMsg = {
    method: 'subscribe',
    subscription: {
      type: 'orderUpdates',
      user: '0xYourAddressHere'
    }
  };
  ws.send(JSON.stringify(subscribeMsg));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'orderUpdates') {
    console.log('Order update:', msg.data);
  }
});

Campos del objeto de orden y semántica de instantáneas

Cada mensaje orderUpdates contiene una instantánea completa de una orden, no un delta. El payload incluye campos como coin, oid (ID de orden), cloid (ID de orden del cliente), side, tipo de orden, precio, tamaño, tamaño original, estado y marcas de tiempo. Los nombres exactos de los campos y los campos adicionales están documentados y pueden variar según la versión de la API, por lo que siempre debes inspeccionar el payload en vivo. Debido a que el mensaje es una instantánea, el comportamiento correcto del cliente es hacer upsert de la orden por su identificador (oid o cloid) en lugar de aplicar un incremento. Un cliente que trata los mensajes como deltas contará dos veces las ejecuciones parciales.

Por ejemplo, si una orden se ejecuta parcialmente, el campo size refleja el tamaño restante y el estado indica el estado actual. El tamaño original permanece constante. Este diseño simplifica la gestión de estado: siempre tienes el estado actual de la orden sin necesidad de reproducir el historial. Sin embargo, también significa que si pierdes un mensaje, tu estado local queda obsoleto hasta la próxima actualización o reconciliación.

• Instantánea, no delta: reemplaza el registro completo de la orden en cada actualización.
• Clave por oid o cloid para hacer upsert correctamente.
• Campos como size y status reflejan el estado actual.

Vocabulario de estados de orden y transiciones de estado

El campo de estado de la orden codifica la etapa del ciclo de vida. Una orden se crea con estado 'open'. Luego puede pasar a 'partially filled' a medida que ocurren ejecuciones y finalmente terminar en 'filled', 'cancelled' o 'rejected'. Las cadenas de estado exactas están documentadas y pueden variar según la versión de la API, por lo que debes verificar contra la documentación actual. Un cliente debe basar su máquina de estados en el campo de estado en lugar del orden de llegada de los mensajes, porque los mensajes WebSocket pueden llegar desordenados o retrasarse.

Comprender estas transiciones es crucial para construir un rastreador de órdenes fiable. Por ejemplo, una orden podría pasar de open a partially filled a filled, o de open a cancelled. Las órdenes rechazadas pueden nunca aparecer como open. La guía Manejo de rechazo de órdenes de Hyperliquid cubre la decodificación de errores para órdenes rechazadas. Trata siempre el estado como el indicador autoritativo del estado actual de la orden.

• open: la orden está activa y sin ejecutar.
• partially filled: se ha ejecutado parte de la cantidad.
• filled: ejecutada por completo.
• cancelled: cancelada por el usuario o el sistema.
• rejected: no aceptada por el exchange.

Reconciliación del flujo en vivo con la API de información

Una suscripción WebSocket solo entrega eventos observados mientras el socket está abierto. Cualquier reconexión o reinicio del proceso pierde las transiciones ocurridas durante la desconexión. Por lo tanto, la única forma correcta de reconstruir el historial de órdenes es reconciliar contra la ruta de lectura de la API de información. La documentación del endpoint de información de Hyperliquid describe endpoints como historicalOrders, frontendOpenOrders y userFills. Estos proporcionan el conjunto autoritativo de órdenes.

Al reconectar, vuelve a emitir la suscripción, luego obtén el conjunto autoritativo de órdenes de la API de información y compáralo con tu instantánea local. Trata el resultado de la API de información como la fuente de verdad. Esto asegura que cualquier actualización perdida se corrija. Para una inmersión más profunda en la superficie de órdenes de la API de información, consulta Estado de órdenes de Hyperliquid a través de la API de información.

• WebSocket es solo en vivo; el historial requiere la API de información.
• Al reconectar, vuelve a suscribirte y obtén las órdenes autoritativas.
• Compara el estado local con la API de información y aplica correcciones.

Construcción de un rastreador de órdenes reanudable en Node.js

Para hacer que el flujo sea reanudable, registra el último estado de orden observado por oid en un almacén local. Al reconectar, vuelve a emitir la suscripción, luego obtén el conjunto autoritativo de órdenes de la API de información y compáralo con tu instantánea local. El ejemplo de código a continuación demuestra una implementación mínima usando Node.js y la librería ws. Mantiene un Map de órdenes con clave oid, lo actualiza en cada mensaje orderUpdates y, al reconectar, obtiene las órdenes abiertas de la API de información para reconciliar.

Este patrón asegura que tu estado local permanezca consistente incluso si la conexión WebSocket se cae. Ten en cuenta que la llamada a la API de información es una solicitud POST al endpoint /info con un cuerpo JSON que especifica el tipo y el usuario. El formato exacto de la solicitud está documentado y puede variar según la versión de la API.

const WebSocket = require('ws');
const fetch = require('node-fetch');

const user = '0xYourAddressHere';
const orders = new Map(); // oid -> order snapshot

async function fetchOpenOrders() {
  const res = await fetch('https://api.hyperliquid.xyz/info', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'frontendOpenOrders', user })
  });
  return res.json();
}

async function reconcile() {
  const openOrders = await fetchOpenOrders();
  for (const order of openOrders) {
    orders.set(order.oid, order);
  }
  console.log('Reconciled', orders.size, 'orders');
}

function connect() {
  const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');
  ws.on('open', () => {
    ws.send(JSON.stringify({
      method: 'subscribe',
      subscription: { type: 'orderUpdates', user }
    }));
    reconcile();
  });
  ws.on('message', (data) => {
    const msg = JSON.parse(data);
    if (msg.channel === 'orderUpdates') {
      for (const update of msg.data) {
        orders.set(update.oid, update);
      }
    }
  });
  ws.on('close', () => {
    setTimeout(connect, 1000);
  });
}

connect();

Método de medición y tabla de resultados

Para verificar el comportamiento del canal orderUpdates contra tu propio endpoint, puedes instrumentar tu cliente para registrar la secuencia de estados de una orden de prueba. Coloca una orden pequeña, luego registra cada mensaje orderUpdates con su marca de tiempo, oid, estado y tamaño. Después de que la orden alcance un estado terminal, compara la secuencia observada con el ciclo de vida esperado. Este método es reproducible y no se basa en benchmarks fabricados.

Usa la tabla a continuación para registrar tus observaciones. Completa los valores reales de tu prueba. Esto te ayuda a confirmar que tu cliente maneja correctamente las instantáneas y transiciones.

• Timestamp: cuándo se recibió el mensaje.
• oid: identificador de la orden.
• Status: cadena de estado reportada.
• Size: tamaño restante.
• Expected next state: basado en el ciclo de vida.

Limitaciones y compensaciones del canal orderUpdates

El canal orderUpdates no es un historial completo. Solo entrega eventos mientras el socket está abierto, por lo que cualquier desconexión crea vacíos. Tampoco proporciona ejecuciones directamente; para detalle a nivel de ejecución, usa los canales de trades y userFills de Hyperliquid. Además, el canal es de ámbito de usuario, por lo que no puede usarse para monitoreo del libro de órdenes de todo el mercado. Para detección de actividad, consulta Detección de heartbeat de WebSocket de Hyperliquid.

Otra compensación es que los mensajes de instantánea pueden ser más grandes que los deltas, lo que aumenta el ancho de banda. Sin embargo, la simplicidad de hacer upsert por oid a menudo supera este costo. Finalmente, los nombres exactos de los campos y las cadenas de estado están documentados y pueden variar según la versión de la API, por lo que los clientes deben estar preparados para adaptarse.

• Sin historial: vacíos al desconectar.
• Ámbito de usuario: no para datos públicos de mercado.
• El tamaño de la instantánea puede ser mayor que los deltas.
• Los nombres de los campos pueden variar según la versión de la API.

Solución de problemas comunes

Si no estás recibiendo mensajes orderUpdates, primero verifica que tu mensaje de suscripción esté correctamente formateado y que la dirección del usuario coincida con la cuenta. Comprueba que la conexión WebSocket esté abierta y que no estés siendo limitado por rate limits. Para límites de tasa y salud del endpoint, consulta los endpoints RPC de Hyperliquid (RPC Assistant). Si los mensajes llegan pero tu estado local es incorrecto, asegúrate de estar haciendo upsert por oid y no aplicando deltas.

Si ves mensajes duplicados o desordenados, confía en el campo de estado y las marcas de tiempo para resolver conflictos. Siempre reconcilia con la API de información después de reconexiones. Para el manejo de errores, consulta Manejo de rechazo de órdenes de Hyperliquid.

• Verifica el formato de suscripción y la dirección del usuario.
• Comprueba la conexión WebSocket y los límites de tasa.
• Haz upsert por oid; no apliques deltas.
• Reconcilia con la API de información al reconectar.

Próximos pasos y recursos adicionales

Para profundizar tu comprensión, explora el centro de aprendizaje de OnFinality para más guías sobre Hyperliquid y mecánicas de WebSocket. Si necesitas endpoints RPC fiables para tu aplicación, considera el servicio de API y revisa los precios de RPC para opciones. Para una lista completa de endpoints de Hyperliquid, consulta los endpoints RPC de Hyperliquid (RPC Assistant).

También puedes revisar la documentación oficial de suscripciones WebSocket de Hyperliquid y la documentación del endpoint de información para los detalles más recientes. Prueba siempre tu implementación contra la API en vivo para asegurar la compatibilidad.

• Explora más guías en OnFinality Learn.
• Considera el servicio de API de OnFinality para endpoints fiables.
• Revisa la documentación oficial de Hyperliquid para actualizaciones.