Capital de bóvedas de Hyperliquid a través de la Info API

Mecánica de la bóveda y el modelo de contabilidad de participaciones

Una bóveda de Hyperliquid es una cuenta mancomunada en la que otros usuarios depositan a cambio de participaciones. La posición económica del depositante es participaciones por precio de la participación en lugar de un saldo en dólares almacenado, por lo que la lectura del lado de la cuenta devuelve un número de participaciones y una cifra de capital que debe conciliarse con los totales de la propia bóveda en lugar de tratarse como números independientes. La documentación de bóvedas de Hyperliquid describe este modelo de participaciones y la contabilidad del depositante que se deriva de él.

Esto importa porque la lectura ingenua de la fila de bóveda de una cuenta parece un saldo, pero en realidad es una cantidad derivada. Si tratas el capital devuelto como un valor almacenado y además lo sumas con el capital de perpetuos o spot, duplicas el colateral. El modelo mental correcto es que la bóveda posee el colateral y el depositante posee un derecho sobre una fracción de él.

• Bóveda = cuenta mancomunada; depositante = tenedor de participaciones.
• Capital del depositante = participaciones × precio de la participación, no un saldo almacenado.
• El valor total de la bóveda y las participaciones en circulación se mueven tanto con depósitos, retiros y PnL de trading.
• Los nombres de los campos y los campos adicionales están documentados / varían según la versión de la API; verifícalos con la respuesta en vivo.

Dos rutas de lectura: con alcance de cuenta vs con alcance de bóveda

El endpoint info expone dos rutas de lectura distintas que responden a preguntas diferentes. La lectura con alcance de cuenta devuelve las posiciones del llamador o de una dirección observada en bóvedas, incluido el número de participaciones de esa dirección y el capital atribuible a ella. La lectura con alcance de bóveda devuelve el estado agregado de la bóveda, incluido el valor total y el conjunto de depositantes. Un llamador que quiere saber 'cómo le va a esta bóveda' y un llamador que quiere saber 'cuál es la exposición de este usuario' no deben usar la misma solicitud.

La documentación del endpoint info de Hyperliquid enumera los tipos de solicitud y sus parámetros. Trata los nombres exactos de las solicitudes y los campos de respuesta como documentados / varían según la versión de la API, y confírmalos con la respuesta en vivo antes de codificarlos de forma fija. La página de endpoints RPC de Hyperliquid (RPC Assistant) es un buen punto de partida para seleccionar el endpoint, y el artículo Hyperliquid clearinghouseState: margen y liquidación cubre la lectura del lado de perpetuos que a menudo se confunde con el capital de la bóveda.

• Lectura con alcance de cuenta: posiciones de bóveda del usuario, número de participaciones, capital atribuible.
• Lectura con alcance de bóveda: estado agregado de la bóveda, valor total, conjunto de depositantes.
• No uses una sola solicitud para responder a ambas preguntas.
• Confirma los nombres de las solicitudes y los campos con la respuesta en vivo.

Capital de bóveda vs capital de cuenta spot y de perpetuos

clearinghouseState informa el valor de la cuenta de perpetuos y el margen, los saldos spot son una superficie separada, y una posición de bóveda es una tercera cosa distinta. Sumarlos sin deduplicar el colateral duplica el conteo y produce un total incorrecto, que es el error más común en los paneles de bóvedas. El colateral de la bóveda ya está reflejado en el valor total de la bóveda; el derecho del depositante es una fracción de eso, no un saldo adicional.

Si necesitas una vista consolidada, decide explícitamente si estás informando el valor total de la bóveda, el capital atribuible del depositante, o ambos en paralelo. Informar ambos está bien siempre que los etiquetes y nunca los sumes. Los artículos Mecánica de las tasas de financiación de Hyperliquid y Precio del oráculo y subasta del builder de Hyperliquid cubren lecturas adyacentes que también son fáciles de confundir con el estado de la bóveda.

• clearinghouseState = valor de la cuenta de perpetuos y margen.
• Saldos spot = superficie separada.
• Posición de bóveda = tercera superficie; no las sumes sin deduplicar.
• Etiqueta por separado el valor total de la bóveda y el capital atribuible del depositante.

Derivar el precio de la participación y aislar el rendimiento del gestor

El valor por participación de la bóveda es el valor total de la bóveda dividido por las participaciones en circulación. Debido a que ambas cantidades se mueven con depósitos, retiros y PnL de trading, una cifra de rendimiento calculada solo a partir del capital bruto confunde los depósitos con los rendimientos. El lector debe calcular el cambio en el precio de la participación en lugar del cambio en el capital, que es la única medida que aísla el rendimiento del gestor de los flujos de efectivo.

Un depósito aumenta tanto el valor total como las participaciones en circulación, por lo que el precio de la participación no cambia en el momento del depósito. Una ganancia de trading aumenta el valor total sin cambiar las participaciones, por lo que el precio de la participación sube. Por eso el cambio en el precio de la participación es la señal de rendimiento significativa y el cambio en el capital no lo es. La documentación de bóvedas de Hyperliquid describe el modelo de participaciones que hace que esto sea cierto.

• Precio de la participación = valor total de la bóveda / participaciones en circulación.
• Depósito: suben tanto el valor total como las participaciones; el precio de la participación no cambia.
• Ganancia de trading: sube el valor total, las participaciones no cambian; sube el precio de la participación.
• Rendimiento = cambio en el precio de la participación, no cambio en el capital.

Leer el estado agregado de la bóveda y la posición de la cuenta en Node.js

El script a continuación lee el estado agregado de una bóveda y la posición de bóveda de una cuenta a través del endpoint info, concilia el número de participaciones con las participaciones totales, deriva el valor por participación, toma una instantánea y muestra una tabla. Usa un único POST por solicitud y mantiene las dos lecturas separadas para que la conciliación sea explícita. Reemplaza el endpoint y los nombres de las solicitudes con los valores documentados para tu versión de la API.

Debido a que el endpoint info responde sobre el estado actual, el almacén de instantáneas del script es el historiador. Ejecútalo según una programación y agrega cada lectura a un archivo o base de datos; una sola lectura no es una medición de rendimiento.

// Node.js 18+ (global fetch). Replace endpoint and request names with your API version.
const ENDPOINT = process.env.HL_INFO_ENDPOINT || 'https://api.hyperliquid.xyz/info';
const VAULT = process.env.HL_VAULT_ADDRESS || '0xVaultAddress';
const ACCOUNT = process.env.HL_ACCOUNT_ADDRESS || '0xAccountAddress';

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

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

async function main() {
  // Vault-scoped read: aggregate state. Request name varies by API version.
  const vaultState = await info({ type: 'vaultDetails', vaultAddress: VAULT });
  // Account-scoped read: this address's vault positions.
  const accountState = await info({ type: 'userVaultEquities', user: ACCOUNT });

  const totalValue = num(vaultState?.totalValue ?? vaultState?.value);
  const totalShares = num(vaultState?.totalShares ?? vaultState?.shares);
  const sharePrice = (totalValue !== null && totalShares) ? totalValue / totalShares : null;

  const rows = Array.isArray(accountState) ? accountState : (accountState?.vaultEquities || []);
  const row = rows.find(r => (r.vaultAddress || r.vault || '').toLowerCase() === VAULT.toLowerCase());
  const accountShares = row ? num(row.shares ?? row.vaultShares) : null;
  const accountEquity = row ? num(row.equity ?? row.vaultEquity) : null;

  const reconciledEquity = (accountShares !== null && sharePrice !== null)
    ? accountShares * sharePrice : null;

  const snapshot = {
    ts: new Date().toISOString(),
    vault: VAULT,
    totalValue, totalShares, sharePrice,
    accountShares, accountEquity, reconciledEquity
  };

  console.log('vault | totalValue | totalShares | sharePrice | accountShares | accountEquity | reconciledEquity');
  console.log([
    snapshot.vault, snapshot.totalValue, snapshot.totalShares,
    snapshot.sharePrice, snapshot.accountShares,
    snapshot.accountEquity, snapshot.reconciledEquity
  ].join(' | '));

  // Append to your own snapshot store; this is the historian.
  const fs = require('fs');
  fs.appendFileSync('vault-snapshots.ndjson', JSON.stringify(snapshot) + '\n');
}

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

Conciliar el número de participaciones con las participaciones totales

El paso de conciliación es donde la mayoría de los paneles fallan. La lectura con alcance de cuenta devuelve un número de participaciones y una cifra de capital; la lectura con alcance de bóveda devuelve el valor total y las participaciones totales. Si accountShares × sharePrice no es aproximadamente igual a accountEquity, o las dos lecturas se tomaron a través de una transición de estado o los nombres de los campos difieren de la documentación. Trata una discrepancia como una señal para volver a leer, no como un número para promediar.

Debido a que el endpoint info responde sobre el estado actual, una sola instantánea debe tomarse lo más cerca posible de ser atómica, según lo permita la API. Si tu cliente puede emitir las dos lecturas consecutivamente sin otro trabajo en medio, hazlo; si no, registra las marcas de tiempo y descarta las instantáneas donde la brecha sea lo suficientemente grande como para importar en tu caso de uso.

• accountShares × sharePrice debería ser aproximadamente igual a accountEquity.
• Discrepancia = volver a leer, no promediar.
• Toma ambas lecturas lo más cerca posible de ser atómicas, según lo permita la API.
• Registra las marcas de tiempo y descarta las instantáneas con brechas grandes.

Construir una serie temporal y medir el rendimiento

Una sola lectura del precio de la participación no es una medición de rendimiento. El lector debe muestrear y almacenar lecturas, y debido a que el endpoint info responde sobre el estado actual, el propio almacén de instantáneas del lector es el historiador. El método de medición es reproducible: muestrea con una cadencia fija, almacena cada instantánea y calcula el cambio en el precio de la participación durante la ventana.

La tabla a continuación es una plantilla para completar con los resultados de tu propio endpoint. No compares tus números con los de nadie más; el rendimiento derivado depende de tu cadencia de muestreo y no es comparable entre implementaciones.

• Muestrea con una cadencia fija (por ejemplo, cada 5 minutos).
• Almacena cada instantánea con una marca de tiempo.
• Calcula el cambio en el precio de la participación durante la ventana.
• Informa la cadencia junto con el resultado.

Results Table (fill with your own endpoint's readings)

| Timestamp (UTC) | Vault | Total Value | Total Shares | Share Price | Account Shares | Account Equity | Reconciled Equity |
|-----------------|-------|-------------|--------------|-------------|----------------|----------------|-------------------|
|                 |       |             |              |             |                |                |                   |
|                 |       |             |              |             |                |                |                   |
|                 |       |             |              |             |                |                |                   |

Derived performance over the window:
  sharePriceChange = (lastSharePrice - firstSharePrice) / firstSharePrice
  cadence = <your sampling interval>
  note = not comparable across implementations

Clases de fallo y solución de problemas

Separa las clases de fallo antes de depurar. Un identificador de bóveda que no existe devuelve un resultado vacío en lugar de un error. Una cuenta sin posición en una bóveda devuelve una fila faltante en lugar de un cero. Una versión de la API cuyos nombres de campo difieren de la documentación devuelve una respuesta que se analiza pero produce valores nulos. Una respuesta que es internamente inconsistente se leyó a través de dos llamadas durante una transición de estado, por lo que una sola instantánea debe tomarse lo más cerca posible de ser atómica, según lo permita la API.

Para fallos a nivel de orden, el artículo Manejo de errores de la API de Hyperliquid y rechazos de órdenes cubre la superficie de rechazo. Para la selección de endpoints y la conectividad, consulta endpoints RPC de Hyperliquid (RPC Assistant) y la página de red de Hyperliquid.

• Resultado vacío: el identificador de bóveda no existe.
• Fila faltante: la cuenta no tiene posición en la bóveda.
• Nulos después del análisis: los nombres de los campos difieren de la documentación.
• Respuesta inconsistente: lecturas tomadas a través de una transición de estado.
• Vuelve a leer en lugar de promediar cuando falla la conciliación.

Limitaciones y compensaciones

Nada de esto es asesoramiento de inversión. El rendimiento derivado depende de la propia cadencia de muestreo del lector y, por lo tanto, no es comparable entre implementaciones. Las comisiones de la bóveda y los términos de participación del gestor deben leerse de la propia configuración de la bóveda en lugar de inferirse del movimiento del capital o del precio de la participación. La disponibilidad de campos depende del proveedor y de la versión, por lo que los nombres de las solicitudes y los campos de respuesta que se muestran aquí están documentados / varían según la versión de la API y deben verificarse con la respuesta en vivo.

El endpoint info responde sobre el estado actual, por lo que cualquier vista histórica es una construcción del propio lector. Esa construcción es tan buena como su cadencia y su manejo de las brechas. Si necesitas una vista de cartera consolidada, decide explícitamente cómo evitarás duplicar el colateral entre las superficies de perpetuos, spot y bóveda.

• No es asesoramiento de inversión.
• El rendimiento derivado depende de la cadencia y no es comparable entre implementaciones.
• Las comisiones de la bóveda y los términos de participación del gestor provienen de la propia configuración de la bóveda.
• La disponibilidad de campos depende del proveedor y de la versión.
• Las vistas históricas son una construcción del propio lector.

Próximos pasos para la integración

Comienza confirmando los nombres de las solicitudes y los campos de respuesta con la respuesta en vivo para tu versión de la API. Luego conecta las dos rutas de lectura en tu cliente, agrega la verificación de conciliación y comienza a muestrear con una cadencia fija. Una vez que tengas unos días de instantáneas, calcula el cambio en el precio de la participación durante la ventana e informa la cadencia junto con el resultado.

Para acceso en producción, revisa precios de RPC y la página del servicio de API, y explora el centro de aprendizaje de OnFinality para lecturas adyacentes de Hyperliquid. La página de red de Hyperliquid enumera los endpoints y los detalles de red que necesitarás.

• Confirma los nombres de las solicitudes y los campos con la respuesta en vivo.
• Conecta ambas rutas de lectura y agrega la verificación de conciliación.
• Muestrea con una cadencia fija y almacena instantáneas.
• Calcula el cambio en el precio de la participación e informa la cadencia.
• Revisa las páginas de precios y del servicio de API para acceso en producción.