Mecánica de las tasas de financiación de Hyperliquid: predictedFundings vs fundingHistory

Por qué un perpetuo necesita financiación

Un futuro perpetuo no tiene vencimiento, así que nada fuerza su precio de vuelta hacia el spot o índice subyacente como lo hace la liquidación en un contrato con fecha. La financiación reemplaza esa liquidación ausente: es una transferencia de efectivo recurrente entre el lado largo y el corto del libro que crea un incentivo para mantener el lado que cotiza con descuento y reducir el lado que cotiza con prima. Cuando el perpetuo cotiza por encima del índice, los largos pagan a los cortos; cuando cotiza por debajo, los cortos pagan a los largos. El mecanismo se describe en la documentación oficial de financiación de Hyperliquid, que es la fuente primaria autorizada para el calendario y los parámetros.

La consecuencia práctica para cualquiera que construya un panel o un bot es que la financiación no es una comisión que el exchange te cobra de forma aislada. Es una transferencia entre pares cuyo signo depende de tu lado y cuya magnitud depende del diferencial entre el perpetuo y el índice. Si estás largo y la tasa es positiva, tu posición pierde financiación; si estás corto, la recibes. Equivocar la convención de signo es la causa más común de atribución incorrecta de PnL.

• Perpetuo = sin vencimiento, así que la financiación sustituye la presión de liquidación.
• Tasa positiva: los largos pagan a los cortos. Tasa negativa: los cortos pagan a los largos.
• La tasa responde al diferencial entre el perpetuo y el oráculo, no al volumen de negociación spot.

La convención de acumulación horaria y por qué 'multiplicar por tres' es un error

En Hyperliquid, la financiación se acumula con un calendario horario y la tasa publicada se expresa por hora. Muchos venues más antiguos cotizan una tasa de ocho horas, así que un desarrollador que arrastra el hábito de multiplicar una tasa cotizada por tres para obtener una cifra diaria sobreestimará la financiación de Hyperliquid por un factor de tres. La cifra diaria correcta es la tasa horaria multiplicada por 24, y la cifra anualizada correcta depende del supuesto de capitalización que declares explícitamente. Los límites exactos de acotación, el intervalo y la precisión de la tasa devuelta son valores documentados; trátalos como 'documentado / varía' y confírmalos contra la documentación actual en lugar de codificar una constante en tu bot.

El pago de una posición es sencillo una vez que el intervalo es correcto: pago = notional de la posición x tasa de financiación x horas mantenidas, con el signo tomado desde la perspectiva de la posición. Una posición larga con tasa positiva tiene un pago negativo (paga); una posición corta con tasa positiva tiene un pago positivo (recibe). Como la tasa es por hora, una posición mantenida durante una fracción de hora no se cobra una hora completa bajo el calendario documentado, pero debes verificar el límite exacto de acumulación contra la documentación antes de confiar en una precisión sub-horaria.

• La tasa de Hyperliquid es por hora; no reutilices una convención de ocho horas.
• Diario = horario x 24. Anualizado requiere un supuesto de capitalización declarado.
• Pago = notional x tasa x horas, con signo desde la perspectiva de la posición.

Composición de prima y tasa de interés: qué mueve realmente la tasa

Conceptualmente, una tasa de financiación de perpetuo se compone de un componente de prima que refleja cuánto se aleja el mark del perpetuo del índice subyacente, más un componente de tasa de interés que refleja el costo de carry entre ambos lados. En Hyperliquid la tasa responde al diferencial entre el perpetuo y el oráculo en lugar del volumen spot, por lo que un mercado tranquilo puede seguir teniendo una tasa significativa si el perpetuo está sesgado de forma persistente. El precio del oráculo que ancla este diferencial se trata en nuestra guía sobre precios del oráculo de Hyperliquid y la subasta del builder.

Como la tasa es función de un diferencial vivo, no es una constante que puedas cachear durante un día. Se actualiza durante el intervalo, que es precisamente por lo que la API separa un valor predicho de un historial realizado. Si tu estrategia depende de la financiación, necesitas tanto la estimación prospectiva para decidir como la serie realizada para contabilizar.

• El componente de prima sigue el diferencial entre el perpetuo y el índice.
• El componente de tasa de interés refleja el carry entre ambos lados.
• La tasa es dinámica; no la caches como una constante diaria.

predictedFundings: una estimación prospectiva, no un pago

predictedFundings devuelve la financiación predicha actual para cada par de venue/activo. Es una estimación prospectiva que cambia durante el intervalo, y es la entrada correcta para una decisión: ¿debo abrir, mantener o cerrar una posición dado hacia dónde se dirige la financiación? No es la tasa que realmente pagarás, porque la tasa realizada se fija en el momento de la acumulación. Trata el valor predicho como una señal, no como una cifra contable.

La división por venue importa aquí. Hyperliquid admite múltiples venues, incluidos los dex HIP-3 y pares de perpetuo y spot, y predictedFundings devuelve entradas por par de venue/activo. Comparar una cotización de un dex HIP-3 con un número de perp principal es un error de categoría que corromperá silenciosamente un filtro de arbitraje. Indexa siempre tu búsqueda tanto por venue como por activo, y confirma la forma de la solicitud y la respuesta contra la referencia oficial del endpoint info de Hyperliquid antes de parsearla.

• predictedFundings = estimación prospectiva, cambia durante el intervalo.
• Úsalo para decidir, no para contabilizar.
• Indexa por venue Y activo; nunca compares entre venues a ciegas.

fundingHistory: tasas realizadas por hora en una ventana acotada

fundingHistory devuelve las tasas realizadas por hora ya acumuladas en una ventana acotada. Esta es la entrada para contabilidad, atribución de PnL y backtests, porque estas tasas realmente ocurrieron. La ventana es acotada, así que asumir que es ilimitada es un modo de fallo real: si solicitas más historial del que devuelve el endpoint, obtendrás silenciosamente una serie truncada y tu backtest comenzará en el lugar equivocado. La longitud y la ventana temporal se comportan según lo documentado; confirma los límites actuales en lugar de asumir un recuento fijo.

Una instantánea de financiación y un pago de financiación son objetos diferentes. fundingHistory te da tasas; no te da el importe en dólares que pagó tu cuenta. Para obtener el pago debes combinar la serie de tasas realizadas con el notional de tu posición y el período de tenencia. Esta distinción es el núcleo de leer la financiación correctamente, y es por lo que un panel que solo grafica fundingHistory puede parecer correcto mientras informa un PnL incorrecto.

• fundingHistory = tasas realizadas, ventana acotada, para contabilidad y backtests.
• Una tasa no es un pago; debes combinarla con notional y horas.
• No asumas que la ventana es ilimitada.

Calcular la financiación realizada desde el estado de la cuenta de perpetuo

Para calcular la financiación realizada de una cuenta, lee el estado de la cuenta de perpetuo mediante clearinghouseState para la posición, su notional de entrada y su margen, y luego combínalo con la serie de tasas horarias realizadas de fundingHistory. El notional de la posición multiplicado por cada tasa horaria realizada, sumado durante las horas mantenidas, da el componente de financiación del PnL. Concilia el resultado contra el historial de valor de la propia cuenta para detectar errores de signo: si tu financiación calculada mueve el valor de la cuenta en dirección opuesta al cambio observado, tu convención de signo está invertida.

Este es un método de verificación, no un resultado medido. Rellena la tabla de resultados a continuación con tu propio endpoint y cuenta para que los números sean reproducibles por ti. Nuestra guía sobre APIs de datos históricos y de mercado de Hyperliquid cubre el lado de recuperación de estas series; esta página cubre el mecanismo y la aritmética.

• Lee clearinghouseState para posición, notional de entrada y margen.
• Combínalo con la serie de tasas horarias realizadas de fundingHistory.
• Concilia contra el historial de valor de la cuenta para detectar errores de signo.

Script Node ejecutable: tasa predicha, serie realizada, cifra anualizada y pago

El script a continuación obtiene predictedFundings y fundingHistory para una moneda, imprime la tasa horaria predicha actual, las últimas N tasas realizadas, una cifra anualizada con el supuesto de capitalización declarado explícitamente, y el pago de financiación calculado para un tamaño de posición dado durante un número de horas dado. Reemplaza el endpoint con la URL de tu propio proveedor y ajusta la moneda y los parámetros de posición. Usa solo la API /info nativa y el fetch integrado de Node.

Ten en cuenta que la cifra anualizada aquí usa multiplicación simple por 24 x 365 sin capitalización, y el script imprime ese supuesto para que no puedas confundirlo con un rendimiento compuesto. Si prefieres capitalización, decláralo y cambia la fórmula; el punto es que el supuesto sea explícito, no oculto.

// funding.js — Node 18+ (built-in fetch)
const ENDPOINT = process.env.HL_INFO_URL || 'https://api.hyperliquid.xyz/info';
const COIN = process.env.COIN || 'BTC';
const POSITION_NOTIONAL = Number(process.env.NOTIONAL || 10000); // USD
const HOURS_HELD = Number(process.env.HOURS || 24);
const LAST_N = Number(process.env.LAST_N || 24);

async function post(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 annualiseSimple(hourlyRate) {
  // Simple (non-compounded) annualisation: hourly * 24 * 365
  return hourlyRate * 24 * 365;
}

(async () => {
  // 1) Current predicted funding for each venue/asset pair
  const predicted = await post({ type: 'predictedFundings' });
  const match = (predicted || []).find(
    (row) => JSON.stringify(row).includes(COIN)
  );
  console.log('predictedFundings match:', JSON.stringify(match, null, 2));

  // 2) Realised per-hour rates over a bounded window
  const history = await post({
    type: 'fundingHistory',
    coin: COIN,
    startTime: Date.now() - 1000 * 60 * 60 * 24 * 7,
  });
  const rates = (history || []).map((r) => Number(r.fundingRate));
  const lastN = rates.slice(-LAST_N);
  console.log(`last ${lastN.length} realised hourly rates:`, lastN);

  const latestRealised = lastN[lastN.length - 1] ?? 0;
  console.log('latest realised hourly rate:', latestRealised);
  console.log(
    'annualised (simple, x24x365, no compounding):',
    annualiseSimple(latestRealised)
  );

  // 3) Funding payment for a position over N hours
  // payment = notional * rate * hours, signed from the position's perspective.
  // Positive rate => longs pay shorts. Flip sign for a short position.
  const isLong = true;
  const sign = isLong ? -1 : 1;
  const payment = sign * POSITION_NOTIONAL * latestRealised * HOURS_HELD;
  console.log(
    `funding payment for ${isLong ? 'long' : 'short'} ` +
      `${POSITION_NOTIONAL} USD over ${HOURS_HELD}h: ${payment.toFixed(4)} USD`
  );
})().catch((e) => {
  console.error('funding script failed:', e.message);
  process.exit(1);
});

Tabla de resultados: mide la financiación contra tu propio endpoint

Usa la tabla a continuación para registrar lo que realmente devuelve tu endpoint. No trates ninguna fila como una medición específica de OnFinality; estos son campos para que los rellenes desde tu propio proveedor y cuenta. Ejecuta el script anterior y luego concilia el pago calculado contra el cambio de valor de la cuenta que observes en la misma ventana.

Si el pago calculado y el cambio observado del valor de la cuenta discrepan en signo, tu lado de posición o el signo de la tasa está invertido. Si discrepan en magnitud, verifica si usaste la tasa realizada o la predicha, y si tu cifra de horas mantenidas coincide con el límite de acumulación.

• Moneda / venue: el par exacto de activo y venue que consultaste.
• Tasa horaria predicha: valor de predictedFundings en el momento de la consulta.
• Última tasa horaria realizada: última entrada de fundingHistory.
• Anualizada (simple, x24x365): supuesto declarado, sin capitalización.
• Notional de la posición y horas mantenidas: tus entradas.
• Pago de financiación calculado: notional x tasa x horas, con signo.
• Cambio observado del valor de la cuenta: de tu propio historial de valor.
• ¿Coincide el signo? ¿Coincide la magnitud? Anota cualquier discrepancia.

Fallos comunes al leer la financiación de Hyperliquid

Los fallos a continuación son los que con más frecuencia corrompen un panel de financiación o un bot de arbitraje. Cada uno es un malentendido del mecanismo más que un bug de la API, por lo que sobreviven a la revisión de código. Para problemas a nivel de solicitud, como cuerpos malformados u órdenes rechazadas, consulta Manejo de errores de la API de Hyperliquid y rechazos de órdenes.

Leer lo predicho como realizado es lo más dañino: hace que tu contabilidad dependa de un valor que cambia durante el intervalo. Anualizar con el intervalo equivocado sobreestima o subestima por un factor fijo. Asumir que la ventana de financiación es ilimitada trunca los backtests silenciosamente. Ignorar la división por venue corrompe las comparaciones entre venues. Mezclar PnL no realizado con financiación confunde dos componentes diferentes del PnL. Asumir una precisión o un redondeo que la API no promete produce una deriva que se acumula durante muchas horas.

• Leer lo predicho como realizado.
• Anualizar con una convención de ocho horas en lugar de horaria.
• Asumir que la ventana de financiación es ilimitada.
• Ignorar la división por venue (dex HIP-3 vs perp principal).
• Mezclar PnL no realizado con financiación.
• Asumir una precisión o un redondeo que la API no promete.

Lista de verificación para la resolución de problemas

Recorre esta lista en orden cuando una cifra de financiación parezca incorrecta. Va desde la comprobación más barata (signo) hasta la más costosa (conciliación contra el historial de la cuenta). Si estás depurando conectividad o comportamiento de suscripción en lugar de aritmética, nuestra guía sobre suscripciones WebSocket de Hyperliquid cubre el lado de streaming.

Mantén la lista junto a tu código para que la siguiente persona que toque el módulo de financiación tenga una ruta definida. La mayoría de los bugs de financiación se detectan en el paso uno o dos.

• Confirma que la tasa es por hora, no por ocho horas.
• Confirma que usaste lo realizado (fundingHistory), no lo predicho, para contabilizar.
• Confirma que el signo coincide con tu lado de posición.
• Confirma que la clave de venue/activo coincide con el venue real de la posición.
• Confirma que la ventana de historial no fue truncada.
• Concilia el pago calculado contra el historial de valor de la cuenta.
• Confirma que ninguna constante de acotación o precisión codificada se ha desviado de la documentación.

Limitaciones y supuestos

Esta guía describe el mecanismo documentado y la forma de la API; no afirma ninguna tasa, latencia o límite específicos de OnFinality. Todos los límites, ventanas y precisiones son 'documentado / varía' y deben confirmarse contra la documentación actual de Hyperliquid y la documentación de tu proveedor. La cifra anualizada del script usa multiplicación simple sin capitalización, y ese supuesto se imprime en lugar de ocultarse.

El método de conciliación asume que puedes leer tu propio historial de valor de la cuenta en la misma ventana que la serie de financiación. Si la granularidad de tu historial de valor es más gruesa que la acumulación horaria, espera pequeños residuales y trátalos como ruido de medición en lugar de como un bug. Para la selección de proveedor y el comportamiento del endpoint, consulta Endpoints y proveedores RPC de Hyperliquid.

• No se afirma ninguna tasa, latencia o límite específicos de OnFinality.
• Límites, ventanas, precisión: documentado / varía.
• El supuesto de anualización es simple, sin capitalización y declarado.
• Los residuales de conciliación pueden reflejar la granularidad del historial de valor.

Próximos pasos

Empieza ejecutando el script contra tu propio endpoint y rellenando la tabla de resultados. Luego integra la serie realizada en tu atribución de PnL para que la financiación sea un componente de primera clase en lugar de un residual. Si estás construyendo un filtro de arbitraje, indexa cada comparación por venue y activo antes de clasificar oportunidades.

Para el lado de recuperación de trades, OHLCV e historial de financiación, lee APIs de datos históricos y de mercado de Hyperliquid. Para el precio del oráculo que ancla la prima, lee Precios del oráculo de Hyperliquid y la subasta del builder. Para elegir un endpoint, empieza por Endpoints y proveedores RPC de Hyperliquid, y para planes y rendimiento consulta Precios de RPC y el servicio de API. Explora más guías de mecanismos en el centro de aprendizaje de OnFinality y la página de la red Hyperliquid.

• Ejecuta el script, rellena la tabla de resultados y concilia contra el historial de la cuenta.
• Haz que la financiación sea un componente de PnL de primera clase.
• Indexa las comparaciones de arbitraje por venue y activo.
• Confirma todos los límites y ventanas contra la documentación actual antes de codificar.