Hyperliquid clearinghouseState: lectura de margen y riesgo de liquidación

La solicitud de información clearinghouseState y la forma documentada de su respuesta

Hyperliquid expone el estado de la cuenta a través de la info API, una superficie de solo lectura que acepta un POST a la ruta info con un cuerpo JSON que nombra el tipo de solicitud. La solicitud clearinghouseState toma una dirección de usuario y devuelve el resumen de margen de la cuenta, sus posiciones por activo y un campo de margen de mantenimiento cruzado. La documentación de Hyperliquid para el endpoint de información de perpetuos describe la forma de la respuesta, incluyendo entradas de posición por activo con tamaño, precio de entrada y valor de posición, y un resumen de margen que contiene el valor de la cuenta, el margen total usado y la posición nocional total.

Trata los nombres exactos de los campos y cualquier campo adicional como documentados pero sujetos a cambios entre versiones de la API. El hábito correcto es registrar la respuesta sin procesar una vez, confirmar los nombres de los campos contra la documentación actual en Documentación de Hyperliquid: endpoint de información de perpetuos y solo entonces escribir código que los lea. Codificar de forma rígida un nombre de campo que viste en una publicación de blog es la forma en que un monitor empieza a devolver undefined silenciosamente y reporta una cuenta saludable.

La misma cuenta puede consultarse a través de los endpoints RPC de Hyperliquid (RPC Assistant) si prefieres una ruta gestionada, pero el cuerpo de la solicitud y la forma de la respuesta son del protocolo, no del proveedor. El comportamiento específico del proveedor, como el almacenamiento en caché, los límites de tasa y la semántica de reintentos, se documenta por proveedor y varía, así que verifícalo contra el endpoint que realmente llamas.

• clearinghouseState es una solicitud de información de solo lectura; no coloca ni cancela órdenes.
• La respuesta incluye un resumen de margen a nivel de cuenta más entradas de posición por activo.
• Los nombres de los campos están documentados, pero deben verificarse contra la respuesta actual antes de codificarlos de forma rígida.

Por qué la info API y la exchange API son superficies diferentes

El endpoint de información es un POST de solo lectura sin autenticación. La colocación de órdenes, la cancelación y cualquier acción que cambie el estado se firman contra el endpoint de exchange usando una clave privada. Esta separación es la propiedad de seguridad más importante de construir alertas de liquidación de esta manera: un proceso de monitoreo que solo lee clearinghouseState nunca necesita una clave privada, por lo que un monitor comprometido no puede mover fondos.

Vale la pena afirmar esa propiedad con claridad porque el patrón alternativo, incrustar una clave de firma en un panel o servicio de alertas, convierte una herramienta de riesgo de solo lectura en un riesgo de custodia. Si tu monitor necesita actuar ante una infracción, mantén la clave de firma en un proceso separado con su propio límite de autorización, y deja que el monitor emita un evento en lugar de una transacción.

La página del servicio API describe cómo OnFinality expone estas superficies, y el artículo Manejo de errores de la API de Hyperliquid y rechazos de órdenes cubre qué sucede en el lado firmado cuando se rechaza una solicitud. Para el monitoreo, la ruta de solo lectura es la que importa.

• Endpoint de información: POST de solo lectura, sin autenticación, sin clave privada.
• Endpoint de exchange: solicitudes firmadas, requiere clave privada, cambia el estado.
• Mantén la clave de firma fuera de cualquier proceso que solo necesite leer el estado de la cuenta.

Margen cruzado, margen aislado y por qué la distinción cambia cada número

En una cuenta con margen cruzado, el colateral se comparte entre posiciones, por lo que la salud de una posición es función de toda la cuenta. En una posición aislada, el margen se asigna solo a esa posición, por lo que su salud depende únicamente de su propio colateral y tamaño. La documentación de margen de Hyperliquid en Documentación de Hyperliquid: margen describe ambos modos y los requisitos de margen de mantenimiento que aplican.

Esta distinción es la fuente más común de un número de riesgo incorrecto. Un llamador que lee el resumen de margen a nivel de cuenta y lo aplica a una sola posición aislada calcula una distancia de liquidación sin sentido, porque el resumen de la cuenta incluye colateral que la posición aislada no puede usar. Antes de calcular cualquier cosa, determina en qué modo está la posición y qué resumen le aplica.

El vocabulario de modos de cuenta que los lectores buscan a continuación, margen de cartera, cruzado versus aislado, activos de colateral, cuenta unificada y modo de cobertura, todos describen esta misma bifurcación. Si no estás seguro de qué modo usa una cuenta, el enfoque más seguro es leer la entrada de posición y el resumen de la cuenta por separado, etiquetarlos en tu salida y nunca mezclarlos en un solo número.

• Margen cruzado: colateral compartido, la salud de la posición depende de toda la cuenta.
• Margen aislado: colateral asignado por posición, la salud depende solo de esa posición.
• Nunca apliques el resumen a nivel de cuenta a una posición aislada.

Orden de lectura campo por campo que evita los errores clásicos

Lee primero los campos a nivel de cuenta: el valor de la cuenta y el margen total usado dan una ratio de margen, y el margen de mantenimiento cruzado da el colchón antes de la liquidación. Luego lee las entradas de posición por activo, que describen la posición en lugar de la cuenta. Mezclar ambos es la fuente más común de un número de riesgo incorrecto, porque el valor nocional de una posición no es la posición nocional total de la cuenta.

Una disciplina útil es imprimir el resumen de la cuenta y las entradas de posición en bloques separados, con etiquetas explícitas, para que quien lea la salida pueda ver qué número provino de qué nivel. Cuando calcules una distancia, indica la fórmula en la salida junto al resultado, para que el número pueda auditarse en lugar de confiarse.

El artículo Mecánica de las tasas de financiación de Hyperliquid explica cómo la acumulación de financiación mueve el valor de la cuenta entre sondeos, que es por lo que los campos a nivel de cuenta pueden desviarse incluso cuando no ha ocurrido ninguna operación.

• Nivel de cuenta: valor de la cuenta, margen total usado, margen de mantenimiento cruzado.
• Nivel de posición: tamaño, precio de entrada, valor de posición, por activo.
• Etiqueta cada bloque en la salida para que la fuente de cada número sea visible.

Por qué el precio de liquidación se deriva en lugar de devolverse

El endpoint de cuenta no promete un precio de liquidación. El precio de liquidación es una cantidad derivada: depende de los requisitos de margen de mantenimiento, el apalancamiento, el tamaño de la posición y el colateral disponible para esa posición o cuenta. Como esas entradas cambian con la financiación, con nuevas posiciones y con el modo de margen, un precio de liquidación devuelto sería una instantánea que queda obsoleta de inmediato.

La consecuencia práctica es que debes calcular la distancia a partir del colchón de margen de mantenimiento en lugar de intentar leer un precio de liquidación. El colchón es la cantidad que el propio mercado usa para decidir cuándo actuar, por lo que una distancia derivada de él está más cerca del mecanismo que un precio derivado de una fórmula que adivinaste.

Si quieres un número parecido a un precio para un panel, derívalo y etiquétalo como una estimación con la fórmula mostrada. No lo presentes como un valor proporcionado por el mercado.

• El precio de liquidación se deriva del margen de mantenimiento, el apalancamiento, el tamaño y el colateral.
• El colchón de margen de mantenimiento es la cantidad sobre la que actúa el mercado.
• Cualquier salida parecida a un precio debe etiquetarse como estimación con su fórmula.

Un monitor Node.js ejecutable para clearinghouseState

El monitor a continuación hace un POST del cuerpo documentado de la solicitud de información para clearinghouseState, lee la respuesta e imprime el tamaño y el nocional por activo junto con el colchón de margen de mantenimiento de la cuenta. Luego imprime una distancia calculada a la liquidación claramente etiquetada con la fórmula mostrada, para que el lector pueda auditarla. Reemplaza el endpoint y la dirección por los tuyos.

El código lee los nombres de los campos de forma defensiva e imprime la respuesta sin procesar una vez cuando falta un campo, que es la forma más rápida de descubrir que una versión de la API ha renombrado algo. No firma nada y no necesita una clave privada.

// monitor.js — read-only Hyperliquid clearinghouseState monitor
// Run: node monitor.js
// No private key required. Info endpoint is read-only.

const ENDPOINT = process.env.HL_INFO_URL || 'https://api.hyperliquid.xyz/info';
const USER = process.env.HL_USER || '0xYourAccountAddress';

async function fetchClearinghouseState(user) {
  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'clearinghouseState', user })
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

function num(v) {
  const n = Number(v);
  return Number.isFinite(n) ? n : null;
}

function printState(state) {
  const summary = state.marginSummary || {};
  const accountValue = num(summary.accountValue);
  const totalMarginUsed = num(summary.totalMarginUsed);
  const totalNtlPos = num(summary.totalNtlPos);
  const crossMaint = num(state.crossMaintenanceMargin);

  console.log('--- ACCOUNT SUMMARY ---');
  console.log('accountValue        :', accountValue);
  console.log('totalMarginUsed     :', totalMarginUsed);
  console.log('totalNtlPos         :', totalNtlPos);
  console.log('crossMaintenanceMargin:', crossMaint);

  if (accountValue !== null && totalMarginUsed !== null && totalMarginUsed > 0) {
    console.log('marginRatio         :', (totalMarginUsed / accountValue).toFixed(4));
  }

  console.log('--- POSITIONS ---');
  for (const p of state.assetPositions || []) {
    const pos = p.position || {};
    const szi = num(pos.szi);
    const entry = num(pos.entryPx);
    const posValue = num(pos.positionValue);
    console.log({
      coin: pos.coin,
      szi,
      entryPx: entry,
      positionValue: posValue
    });
  }

  // Distance to liquidation, derived from the maintenance-margin buffer.
  // Formula: distance = (accountValue - crossMaintenanceMargin) / accountValue
  // This is an estimate, not a venue-provided liquidation price.
  if (accountValue !== null && crossMaint !== null && accountValue > 0) {
    const buffer = accountValue - crossMaint;
    const distance = buffer / accountValue;
    console.log('--- COMPUTED DISTANCE (estimate) ---');
    console.log('formula: (accountValue - crossMaintenanceMargin) / accountValue');
    console.log('buffer  :', buffer.toFixed(2));
    console.log('distance:', distance.toFixed(4));
  } else {
    console.log('Missing fields; dumping raw response for inspection:');
    console.log(JSON.stringify(state, null, 2));
  }
}

(async () => {
  try {
    const state = await fetchClearinghouseState(USER);
    printState(state);
  } catch (err) {
    console.error('monitor failed:', err.message);
    process.exitCode = 1;
  }
})();

Una tabla de resultados para completar con tu propia cuenta

Ejecuta el monitor contra tu propia cuenta en varios momentos y registra el valor de la cuenta, el margen total usado, el margen de mantenimiento y la distancia calculada. Esto convierte una pregunta vaga de "qué tan cerca estoy" en una tendencia que puedes umbralizar. La tabla a continuación es una plantilla; los valores son tuyos para medir, no nuestros para afirmar.

Como la acumulación de financiación mueve el valor de la cuenta entre sondeos, una sola lectura no es una tendencia. Toma lecturas a un intervalo fijo, anota cualquier operación o transferencia entre ellas y observa la dirección de la columna de distancia en lugar de su valor absoluto.

• Columnas de la tabla de resultados: marca de tiempo, valor de la cuenta, margen total usado, margen de mantenimiento cruzado, distancia calculada, notas.
• Toma lecturas a un intervalo fijo para que la tendencia sea comparable.
• Registra operaciones y transferencias en la columna de notas para que un cambio abrupto sea explicable.

Modos de fallo: cachés obsoletas, rutas de indexación, deriva de financiación y alertas sobre el campo equivocado

Una respuesta en caché obsoleta hace que la cuenta parezca más saludable de lo que es. Si tu proveedor almacena en caché las respuestas de información, un monitor que sondea más rápido de lo que se refresca la caché verá el mismo estado repetidamente y se perderá un movimiento. Verifica el comportamiento de la caché contra la documentación de tu proveedor y considera un parámetro que evite la caché o un segundo endpoint para confirmación.

Una posición puede existir en una ruta de indexación de mercado o activo y no en otra, por lo que un monitor que lee solo una ruta puede reportar una cuenta plana mientras hay una posición abierta en otro lugar. La acumulación de financiación mueve el valor de la cuenta entre sondeos incluso sin operaciones, por lo que una distancia calculada una vez y almacenada no es una distancia. Y alertar solo sobre el valor de la cuenta es una trampa: el colchón de margen de mantenimiento es la cantidad que realmente predice la liquidación, así que un valor de cuenta que parece cómodo puede asentarse sobre un colchón delgado.

Los artículos Datos históricos de mercado de Hyperliquid y Precio del oráculo e información de subastas de Hyperliquid cubren superficies de datos adyacentes que pueden ayudarte a verificar de forma cruzada lo que reporta el endpoint de cuenta.

• Caché obsoleta: el mismo estado devuelto repetidamente, movimientos perdidos.
• Ruta de indexación: una posición visible en una ruta y no en otra.
• Deriva de financiación: el valor de la cuenta cambia sin operaciones.
• Campo equivocado: alertar sobre el valor de la cuenta en lugar del colchón de margen de mantenimiento.

Solución de problemas de un monitor que reporta el número de riesgo incorrecto

Cuando el número parece incorrecto, primero vuelca la respuesta sin procesar y compara los nombres de los campos con la documentación actual. Un campo renombrado devuelve undefined, y la aritmética sobre undefined produce NaN, que muchos paneles representan como cero. Segundo, confirma el modo de margen: si la posición es aislada, el resumen a nivel de cuenta no aplica, y la solución es leer el colateral propio de la posición en lugar del de la cuenta.

Tercero, revisa las unidades. Algunos campos son cadenas, otros son números y algunos están escalados. Analiza explícitamente y registra el valor analizado junto al valor sin procesar. Cuarto, compara la marca de tiempo de la respuesta con tu hora de sondeo; si el proveedor almacena en caché, la respuesta puede ser más antigua de lo que crees.

Si llamas a través de un endpoint gestionado, la página de Precios de RPC describe el comportamiento a nivel de plan, y el centro de aprendizaje de OnFinality reúne los artículos relacionados de Hyperliquid en un solo lugar.

• Vuelca la respuesta sin procesar y verifica los nombres de los campos antes de confiar en la aritmética.
• Confirma el modo de margen antes de aplicar el resumen de la cuenta.
• Analiza y registra las unidades explícitamente; las cadenas y los enteros escalados son comunes.
• Compara la marca de tiempo de la respuesta con la hora de sondeo para detectar el almacenamiento en caché.

Limitaciones y compensaciones de una herramienta de riesgo solo de observación

Esta es una herramienta de observación. Lee el estado y calcula un número; no predice el momento de la liquidación y no puede ver una posición siendo cerrada por el propio motor del mercado entre sondeos. Un monitor que sondea cada minuto tiene un punto ciego de un minuto, y ninguna precisión de fórmula elimina eso.

La compensación está entre la frecuencia de sondeo y el costo. Un sondeo más rápido reduce el punto ciego pero aumenta el volumen de solicitudes y la probabilidad de alcanzar los límites de tasa del proveedor, que varían según el proveedor y se documentan por plan. Otra compensación está entre simplicidad y completitud: un monitor que solo lee clearinghouseState es fácil de razonar pero ciego a posiciones en otras rutas de indexación, mientras que un monitor que lee todo es más difícil de auditar.

Indica estos límites en la propia herramienta. Un número de distancia presentado sin su fórmula, su marca de tiempo y su punto ciego invita al exceso de confianza.

• Solo observación: sin predicción del momento de la liquidación.
• Punto ciego entre sondeos; la frecuencia se compensa con el costo y los límites de tasa.
• Simplicidad versus completitud: una ruta es auditable pero parcial.

Próximos pasos: de una sola lectura a una tendencia umbralizada

Empieza ejecutando el monitor una vez y confirmando los nombres de los campos contra la respuesta actual. Luego ejecútalo a un intervalo fijo, completa la tabla de resultados y establece un umbral en la columna de distancia en lugar de en el valor de la cuenta. Cuando la distancia cruce el umbral, emite un evento; mantén cualquier clave de firma en un proceso separado.

Para ir más lejos, añade una segunda fuente de datos para verificación cruzada, revisa el artículo Mecánica de las tasas de financiación de Hyperliquid para saber cómo la financiación mueve el valor de la cuenta, y usa la referencia de endpoints RPC de Hyperliquid (RPC Assistant) para confirmar el endpoint que llamas. El centro de aprendizaje de OnFinality reúne el conjunto completo de Hyperliquid, y la página del servicio API describe cómo llegar a estas superficies a través de OnFinality.

• Confirma los nombres de los campos una vez y luego automatiza a un intervalo fijo.
• Umbraliza la distancia calculada, no el valor de la cuenta.
• Mantén las claves de firma fuera del proceso de monitoreo.
• Verifica de forma cruzada con una segunda fuente de datos antes de actuar.