Estado de órdenes y ejecuciones de usuario en Hyperliquid a través de la Info API

La superficie de solo lectura /info y por qué la observación de órdenes no necesita clave privada

Hyperliquid divide su API HTTP en dos superficies: /info para lecturas y /exchange para escrituras firmadas. El endpoint /info es un POST sin autenticación que acepta un cuerpo JSON con un campo type y parámetros específicos de la solicitud, y devuelve el estado solicitado. Al ser de solo lectura, observar órdenes y ejecuciones nunca requiere una clave privada, lo que significa que el monitoreo puede ejecutarse en un proceso separado, un panel o una cuenta de servicio de solo lectura sin exponer material de firma.

Esto difiere de los endpoints de proveedores JSON-RPC, que también se basan en POST pero siguen el sobre JSON-RPC 2.0 con los campos jsonrpc, method, params e id. La superficie /info es un POST plano a nivel de aplicación, no una llamada a método JSON-RPC, por lo que no debes envolver su cuerpo en un sobre JSON-RPC. La documentación de la API de Hyperliquid es la autoridad para las formas exactas de solicitud y respuesta.

Para lecturas en producción, apunta tu cliente a un endpoint confiable. OnFinality ofrece endpoints RPC de Hyperliquid y un servicio de API que puede actuar como frontend de la superficie /info; la página de la red Hyperliquid lista las rutas de acceso disponibles.

• /info: POST de lectura sin autenticación, el cuerpo es un objeto JSON con un campo type.
• /exchange: ruta de escritura firmada para el envío y la cancelación de órdenes.
• No se necesita clave privada para leer userFills, historicalOrders, frontendOpenOrders u orderStatus.
• No envuelvas los cuerpos de /info en un sobre JSON-RPC 2.0; no es un método JSON-RPC.

Las tres solicitudes de lectura y de qué es autoridad cada una

userFills devuelve el historial de ejecuciones de una cuenta. Cada ejecución incluye px, sz, side, time, fee, closedPnl, oid y tid, y la solicitud acepta un flag opcional aggregateByTime. Esta es la autoridad para la ejecución agregada: si quieres saber cuánto se negoció realmente y a qué precios, userFills es la fuente. La documentación de la API de Hyperliquid define el conjunto exacto de campos y la semántica de agregación.

historicalOrders devuelve el historial de órdenes de la cuenta con su estado, que es la autoridad para las transiciones de estado a nivel de orden. frontendOpenOrders devuelve las órdenes actualmente en reposo, que es la autoridad para lo que está activo en este momento. orderStatus(oid|cloid) es una consulta puntual para una sola orden y es la autoridad para el estado actual de esa orden. El SDK de Python de Hyperliquid muestra las llamadas de referencia del lado del cliente para cada una de estas.

Una ruta de lectura práctica llama a frontendOpenOrders para el libro activo, historicalOrders para el registro reciente de órdenes y userFills para las ejecuciones, y luego las une por oid. La página de APIs de datos históricos y de mercado de Hyperliquid cubre el lado de datos de mercado, que es independiente del estado de tus propias órdenes.

• userFills: historial de ejecuciones; autoridad para fills y comisiones agregadas.
• historicalOrders: historial de órdenes con estado; autoridad para transiciones a nivel de orden.
• frontendOpenOrders: órdenes actualmente en reposo; autoridad para la exposición activa.
• orderStatus(oid|cloid): consulta puntual; autoridad para una sola orden.

La unión discriminada de orderStatus y la ramificación segura

orderStatus se indexa por oid o cloid y devuelve una unión discriminada. Los resultados documentados son order, status, fill, rejected y unknownOid. Cada resultado tiene una forma diferente, por lo que debes ramificar según el discriminador antes de leer los campos. Tratar la respuesta como un único objeto plano es el error de integración más común.

El resultado order describe una orden en reposo, status describe una transición de estado, fill describe una ejecución, rejected describe una orden que fue rechazada y unknownOid significa que el identificador no se encontró. Cuando generas tus propios ids de orden de cliente, la ruta cloid te permite buscar una orden antes de tener un oid, lo cual es útil para flujos de envío idempotentes. La documentación de Hyperliquid es la autoridad sobre cómo una orden pasa del envío a la ejecución y por qué orderStatus se indexa por oid o cloid.

Ramificar de forma segura significa verificar primero el discriminador y luego validar que los campos que necesitas existan para esa rama. Nunca asumas que un campo fill está presente en un resultado order, y nunca asumas que existe un oid en un resultado unknownOid.

• order: detalles de la orden en reposo.
• status: detalles de la transición de estado.
• fill: detalles de la ejecución.
• rejected: orden rechazada; lee el motivo.
• unknownOid: identificador no encontrado; verifica la generación y el envío del cloid.

Por qué userFills y historicalOrders pueden discrepar momentáneamente

userFills y historicalOrders se sirven desde rutas de lectura diferentes y pueden discrepar durante una ventana corta debido al retraso de indexación. Una ejecución puede aparecer en userFills antes de que el estado de la orden correspondiente se actualice en historicalOrders, o viceversa. Esto es normal y no indica pérdida de datos.

La regla de reconciliación es tratar orderStatus como la autoridad para una sola orden y userFills como la autoridad para la ejecución agregada. Cuando los dos discrepan, vuelve a consultar orderStatus para el oid específico y usa ese resultado para resolver el estado de la orden. Para el volumen agregado, las comisiones y closedPnl, confía en userFills. La página de manejo de errores de la API de Hyperliquid cubre la decodificación de rechazos en el envío, que es una fase diferente de esta ruta de lectura posterior al envío.

Si necesitas una instantánea consistente, sondea ambas superficies y únelas por oid, luego aplica una ventana corta de reintentos antes de alertar. No trates una discrepancia transitoria como un fallo.

• El retraso de indexación puede causar discrepancias temporales entre userFills y historicalOrders.
• orderStatus es la autoridad por orden; userFills es la autoridad agregada.
• Une por oid y reintenta antes de alertar por una discrepancia.

Una ruta de lectura ejecutable en Node.js para órdenes abiertas, historial y ejecuciones

El siguiente ejemplo de Node.js hace POST al endpoint /info con las formas de cuerpo correctas, lee órdenes abiertas, órdenes históricas y ejecuciones recientes del usuario, e imprime una tabla reconciliada por orden que une oid con ejecuciones y estado. Usa el fetch integrado disponible en Node.js moderno y no requiere clave privada.

Reemplaza la URL del endpoint con la URL /info de tu proveedor y establece la dirección del usuario. El ejemplo asume las formas de respuesta documentadas por Hyperliquid; si tu proveedor devuelve un envoltorio, ajusta el análisis en consecuencia.

const INFO_URL = 'https://api.hyperliquid.xyz/info';
const USER = '0xYourAccountAddress';

async function info(body) {
  const res = await fetch(INFO_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  if (!res.ok) throw new Error('info HTTP ' + res.status);
  return res.json();
}

async function main() {
  const open = await info({ type: 'frontendOpenOrders', user: USER });
  const history = await info({ type: 'historicalOrders', user: USER });
  const fills = await info({ type: 'userFills', user: USER, aggregateByTime: false });

  const byOid = new Map();
  for (const o of history) {
    const oid = o.order && o.order.oid;
    if (oid == null) continue;
    byOid.set(oid, { oid, status: o.status, fills: [] });
  }
  for (const f of fills) {
    const oid = f.oid;
    if (oid == null) continue;
    if (!byOid.has(oid)) byOid.set(oid, { oid, status: 'unknown', fills: [] });
    byOid.get(oid).fills.push(f);
  }
  for (const o of open) {
    const oid = o.oid;
    if (oid == null) continue;
    if (!byOid.has(oid)) byOid.set(oid, { oid, status: 'open', fills: [] });
  }

  console.log('oid | status | fills | filledSz | avgPx');
  for (const row of byOid.values()) {
    let filledSz = 0;
    let notional = 0;
    for (const f of row.fills) {
      const sz = Number(f.sz);
      const px = Number(f.px);
      filledSz += sz;
      notional += sz * px;
    }
    const avgPx = filledSz > 0 ? (notional / filledSz).toFixed(4) : '-';
    console.log(row.oid + ' | ' + row.status + ' | ' + row.fills.length + ' | ' + filledSz + ' | ' + avgPx);
  }
}

main().catch((e) => { console.error(e); process.exit(1); });

Una consulta puntual con orderStatus para una sola orden

Cuando necesitas el estado de una orden, orderStatus es más barato y preciso que escanear el historial. Pasa oid o cloid en el cuerpo de la solicitud. La respuesta es la unión discriminada descrita anteriormente, así que ramifica según el discriminador antes de leer los campos.

El siguiente ejemplo de curl muestra la forma de la solicitud para una consulta por oid. Reemplaza el oid con un valor real de tu cuenta. Si generas tus propios ids de orden de cliente, usa la forma cloid en su lugar.

curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"orderStatus","user":"0xYourAccountAddress","oid":123456789}'

# cloid form
curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"orderStatus","user":"0xYourAccountAddress","cloid":"0x..."}'

Tabla de resultados para completar con tu propia cuenta

Usa la siguiente tabla para registrar lo que tu endpoint devuelve para una orden conocida. Ejecuta el ejemplo de Node.js, elige un oid y completa cada columna. Esto verifica que tu proveedor devuelve las formas documentadas y que tu lógica de reconciliación une correctamente.

Si una columna está vacía o es inesperada, vuelve a verificar el cuerpo de la solicitud y la rama del discriminador antes de asumir un problema del proveedor. La página de endpoints RPC de Hyperliquid lista las opciones de acceso si necesitas un endpoint diferente.

• oid: el identificador de orden que consultaste.
• discriminador de orderStatus: order, status, fill, rejected o unknownOid.
• estado en historicalOrders: la cadena de estado devuelta para ese oid.
• recuento en userFills: número de ejecuciones unidas a ese oid.
• filledSz: suma de sz de las ejecuciones unidas.
• avgPx: notional dividido por filledSz.
• fee total: suma de fee de las ejecuciones unidas.
• closedPnl total: suma de closedPnl de las ejecuciones unidas.

Modos de fallo: unknownOid, ejecuciones parciales, agregación y unidades de tiempo

unknownOid aparece cuando un cloid nunca fue aceptado o cuando un oid no existe. Si generas ids de orden de cliente, verifica que el cloid que consultas coincida con el que enviaste, incluidos mayúsculas/minúsculas y prefijo. Un cloid que fue rechazado en el envío no se resolverá después.

Las ejecuciones parciales parecen una orden más pequeña si solo lees la última ejecución. Suma siempre sz de todas las ejecuciones unidas al oid y compáralo con el tamaño original de la orden. aggregateByTime colapsa múltiples ejecuciones en una sola fila, lo cual es útil para informes pero oculta el detalle por ejecución; establécelo en false cuando necesites granularidad a nivel de ejecución.

Los campos de tiempo se basan en epoch. Confirma si tu proveedor devuelve segundos o milisegundos y normaliza antes de comparar. El comportamiento de límite de tasa en la superficie info varía según el proveedor; consulta la documentación de límites de tasa del proveedor y aplica retroceso ante respuestas 429. La página de mecánica de tasas de financiación de Hyperliquid muestra un patrón de ruta de lectura similar para un tipo de datos diferente.

• unknownOid: cloid nunca aceptado o oid inexistente.
• Ejecuciones parciales: suma sz de todas las ejecuciones, no leas solo la última.
• aggregateByTime: colapsa ejecuciones; establece false para detalle de ejecución.
• Unidades de tiempo: normaliza segundos vs milisegundos antes de comparar.
• Límites de tasa: retrocede ante 429; el comportamiento varía según el proveedor.

Limitaciones y compensaciones de la superficie info de solo lectura

Debido a que /info no tiene autenticación, no puede reconciliar escrituras. No puedes usarlo para confirmar que una acción firmada fue aceptada; eso requiere la ruta /exchange y su respuesta. Trata /info como una superficie de observación, no como una superficie de confirmación de escritura.

El almacenamiento en caché del proveedor puede introducir datos obsoletos. Algunos proveedores almacenan en caché las respuestas de /info durante ventanas cortas, por lo que una orden recién colocada puede no aparecer de inmediato. Las brechas de los revendedores son otra compensación: un revendedor puede no exponer todos los tipos de solicitud de /info, así que verifica la cobertura antes de construir sobre ella. La página de clearinghouseState de Hyperliquid cubre el estado de margen y posiciones, que es una ruta de lectura diferente del estado de órdenes.

Para el monitoreo en producción, combina las lecturas de /info con tus propios registros de envío y una ventana de reintentos. No asumas que una sola lectura es una instantánea consistente.

• Sin autenticación no hay reconciliación de escrituras; usa /exchange para eso.
• El almacenamiento en caché del proveedor puede retrasar la visibilidad de nuevas órdenes.
• La cobertura de los tipos de solicitud de /info varía entre revendedores.
• Combina las lecturas con registros de envío y una ventana de reintentos.

Lista de verificación de solución de problemas para lecturas de órdenes y ejecuciones

Cuando una lectura parece incorrecta, recorre la lista de verificación en orden. Primero confirma que el tipo y los parámetros del cuerpo de la solicitud coinciden con la forma documentada. Segundo, confirma que estás ramificando según el discriminador de orderStatus. Tercero, confirma que estás uniendo las ejecuciones por oid y sumando sz en lugar de leer una sola ejecución.

Si la discrepancia persiste, compara userFills y historicalOrders para el mismo oid y vuelve a consultar orderStatus. Se espera una discrepancia transitoria; una persistente sugiere un error de solicitud o de análisis. La página de suscripciones WebSocket de Hyperliquid cubre la alternativa de streaming si el sondeo es demasiado lento para tu caso de uso.

Por último, verifica el endpoint en sí. Si tu proveedor devuelve errores o datos truncados, cambia a un endpoint que se sabe que funciona y vuelve a ejecutar la tabla de resultados.

• Verifica el tipo y los parámetros del cuerpo de la solicitud.
• Ramifica según el discriminador de orderStatus.
• Une las ejecuciones por oid y suma sz.
• Vuelve a consultar orderStatus para resolver discrepancias transitorias.
• Cambia de endpoint si los errores persisten.

Próximos pasos para el monitoreo de órdenes y ejecuciones en producción

Construye un pequeño servicio de reconciliación que sondee frontendOpenOrders, historicalOrders y userFills de forma programada, una por oid y exponga una vista por orden. Agrega consultas de orderStatus para las órdenes que necesiten resolución inmediata. Mantén la ruta de lectura separada de la ruta de firma para que una interrupción del monitoreo no pueda afectar el trading.

Para la selección de endpoints y precios, consulta precios de RPC y el centro de aprendizaje de OnFinality para guías relacionadas. Si necesitas actualizaciones de menor latencia, evalúa la ruta WebSocket junto con la ruta de lectura por sondeo.

Documenta tu propia tabla de resultados y política de reintentos, y revísala cuando cambies de proveedor. La ruta de lectura es estable, pero el comportamiento del proveedor en cuanto a almacenamiento en caché y límites de tasa no lo es.

• Separa las rutas de lectura y de firma.
• Sondea y une por oid; agrega orderStatus para consultas urgentes.
• Revisa los precios de RPC y el centro de aprendizaje para guías relacionadas.
• Vuelve a validar la tabla de resultados al cambiar de proveedor.