APIs de Datos Históricos y de Mercado de Hyperliquid: Consulta de Operaciones, OHLCV, Funding e Historial de la Cartera de Órdenes

Respuesta Directa: Cómo Obtener Datos Históricos de Hyperliquid

Para recuperar datos históricos de mercado de Hyperliquid para análisis y backtesting, se utilizan dos superficies complementarias: la API nativa de Hyperliquid (POST HTTP a /info y suscripciones WebSocket) para el estado en vivo y reciente, y los archivos de datos históricos publicados por separado (archivos de operaciones, funding y OHLCV) para un historial más profundo. La API nativa proporciona operaciones recientes, velas, funding y instantáneas de la cartera de órdenes, pero no sirve la profundidad completa del historial de la cartera de órdenes ni velas muy antiguas; para eso, se necesitan los archivos o un revendedor de terceros. Esta guía recorre cada superficie, muestra ejemplos concretos de solicitud/respuesta y proporciona una lista de verificación para la toma de decisiones.

La fuente principal de esta guía es la documentación oficial de Hyperliquid en hyperliquid.gitbook.io. Todos los hosts de endpoints, campos de solicitud y formas de respuesta están documentados allí; donde los límites específicos o las ventanas de retención no están documentados, los documentos indican que varían, por lo que esta guía evita inventar números.

• API nativa: POST /info para operaciones, velas, funding e instantáneas de la cartera de órdenes; WebSocket para suscripciones en tiempo real.
• Archivos históricos: Archivos públicos para operaciones, funding y OHLCV, actualizados periódicamente, que cubren un historial más largo.
• Revendedores de terceros: Servicios como HypeRPC y QuickNode ofrecen APIs de datos extendidas y acceso SQL, pero son referencias independientes, no oficiales.

Entendiendo las Superficies de la API de Datos de Hyperliquid

La API de Hyperliquid se divide en dos categorías principales: la API nativa que habla directamente con los validadores, y los archivos de datos históricos que se generan y alojan por separado. La API nativa se divide además en un endpoint HTTP (POST /info) para consultar el estado actual y el historial reciente, y endpoints WebSocket (ws2 y otros) para suscripciones en tiempo real. Los archivos son archivos (a menudo comprimidos) que contienen operaciones históricas, tasas de funding y datos OHLCV, y se actualizan según un horario.

La API nativa es ideal para aplicaciones que necesitan el último estado o datos de las últimas horas o días. Por ejemplo, puedes obtener las últimas 500 operaciones para una moneda, la tasa de funding actual o la parte superior de la cartera de órdenes. Sin embargo, la API nativa no proporciona la profundidad completa del historial de la cartera de órdenes (todos los niveles a lo largo del tiempo) ni velas más antiguas que un cierto período (la retención exacta no está documentada; varía). Para backtesting profundo, necesitas los archivos.

Los archivos son publicados por Hyperliquid y están disponibles para descarga. Cubren operaciones, funding y OHLCV para todos los pares perpetuos y al contado. La cobertura exacta (fecha de inicio, frecuencia de actualización) está documentada en la página de documentación de Hyperliquid; se recomienda consultar allí para obtener los últimos detalles. Revendedores de terceros como HypeRPC y QuickNode también ofrecen APIs de datos históricos, pero son independientes y pueden tener una cobertura y precios diferentes.

• API nativa: POST /info (HTTP) y WebSocket (ws2) para datos en vivo y recientes.
• Archivos: Archivos públicos para operaciones, funding y OHLCV, actualizados periódicamente.
• Terceros: HypeRPC, QuickNode, etc., ofrecen APIs extendidas pero no son oficiales.

Uso de la API Nativa /info para Datos de Mercado Recientes

El endpoint /info es un endpoint HTTP POST que acepta un objeto de solicitud JSON. El tipo de solicitud se especifica en el campo 'type'. Para datos históricos de mercado, los tipos de solicitud más relevantes son 'trades', 'candleSnapshot' y 'fundingHistory'. La respuesta es un array JSON de objetos.

Por ejemplo, para obtener operaciones recientes de BTC, envías una solicitud con tipo 'trades' y el símbolo de la moneda. La respuesta incluye campos como 'time', 'px', 'sz', 'side' y 'tid'. Para OHLCV, usas 'candleSnapshot' con parámetros como 'req' (intervalo), 'coin', 'startTime' y 'endTime'. La respuesta incluye 't', 'o', 'h', 'l', 'c', 'v' y 'n' (número de operaciones).

Las formas exactas de solicitud y respuesta están documentadas en los documentos de la API de Hyperliquid. A continuación se muestra un ejemplo concreto para operaciones y velas.

// Ejemplo: Obtener operaciones recientes de BTC (usando fetch de Node.js)
const response = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'trades', coin: 'BTC' })
});
const trades = await response.json();
console.log(trades);
// Salida esperada: array de objetos de operación, p.ej.,
// [{"time":1730000000000,"px":"65000.0","sz":"0.1","side":"B","tid":123456,"coin":"BTC"}]

// Ejemplo: Obtener velas de 1h para BTC en un rango de tiempo específico
const candlesResponse = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'candleSnapshot',
    req: { coin: 'BTC', interval: '1h', startTime: 1730000000000, endTime: 1730003600000 }
  })
});
const candles = await candlesResponse.json();
console.log(candles);
// Salida esperada: array de objetos de vela, p.ej.,
// [{"t":1730000000000,"o":"65000.0","h":"65100.0","l":"64900.0","c":"65050.0","v":"100.0","n":123}]

Suscripciones WebSocket para Datos en Tiempo Real y Recientes

Para datos de mercado en tiempo real, Hyperliquid proporciona endpoints WebSocket. El endpoint principal es wss://api.hyperliquid.xyz/ws, y puedes suscribirte a canales como 'trades', 'candle', 'l2Book' y 'userFills'. Estas suscripciones envían actualizaciones a medida que ocurren, lo cual es útil para monitoreo en vivo pero no para backtesting histórico.

Sin embargo, las suscripciones WebSocket también se pueden utilizar para acumular datos con el tiempo. Por ejemplo, puedes suscribirte al canal 'candle' para construir tu propio historial OHLCV. El formato del mensaje de suscripción está documentado en los documentos de WebSocket de Hyperliquid. A continuación se muestra un ejemplo simple en Node.js usando el paquete 'ws'.

// Ejemplo de WebSocket en Node.js (requiere el paquete 'ws': npm install ws)
const WebSocket = require('ws');
const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

ws.on('open', () => {
  // Suscribirse a operaciones de BTC
  ws.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'trades', coin: 'BTC' } }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'trades') {
    console.log('Operación:', msg.data);
    // Cada operación tiene campos como time, px, sz, side, tid
  }
});

ws.on('error', (err) => console.error('Error de WebSocket:', err));

Acceso a Archivos Históricos para un Historial Profundo

Cuando necesitas datos más antiguos de los que proporciona la API nativa, o la profundidad completa de la cartera de órdenes, debes utilizar los archivos históricos. Hyperliquid publica estos archivos en una URL pública (documentada en los documentos de Hyperliquid). Los archivos suelen ser archivos comprimidos (por ejemplo, .csv.gz) que puedes descargar y procesar localmente.

Los archivos incluyen datos de operaciones, tasas de funding y datos OHLCV. La nomenclatura exacta de los archivos y el horario de actualización están documentados en la página de documentación de Hyperliquid. Por ejemplo, los archivos de operaciones podrían estar organizados por fecha y moneda. Para usarlos, descargas los archivos relevantes y los analizas.

Revendedores de terceros como HypeRPC y QuickNode también ofrecen APIs de datos históricos que pueden proporcionar un acceso más fácil mediante SQL o REST. Estos son servicios independientes y pueden tener una cobertura y precios diferentes; siempre consulta su documentación.

• Consulta los documentos oficiales de Hyperliquid para la URL y el formato de los archivos.
• Descarga y analiza archivos localmente para backtesting.
• Considera revendedores de terceros por conveniencia, pero verifica su calidad de datos.

Lista de Verificación para la Toma de Decisiones: Qué Superficie para tu Necesidad de Datos

Para elegir la superficie de API correcta, considera el tipo y la antigüedad de los datos que necesitas. La tabla a continuación mapea las necesidades comunes de datos a la superficie recomendada.

Para operaciones recientes (últimos minutos), usa la API nativa o WebSocket. Para velas, la API nativa proporciona velas recientes, pero para velas más antiguas, usa los archivos. El historial de funding está disponible a través de la API nativa para períodos recientes, pero para análisis de funding a largo plazo, usa los archivos. La parte superior de la cartera de órdenes está disponible a través de la API nativa, pero el historial de profundidad completa no; usa archivos o revendedores si están disponibles.

• Operaciones recientes (últimos minutos): API nativa (tipo 'trades') o WebSocket.
• Operaciones históricas (días/semanas): Archivos.
• Velas OHLCV recientes: API nativa (tipo 'candleSnapshot').
• OHLCV histórico: Archivos.
• Historial de funding: API nativa (tipo 'fundingHistory') para reciente; archivos para largo plazo.
• Parte superior de la cartera de órdenes: API nativa (tipo 'l2Book') o WebSocket.
• Historial de profundidad completa de la cartera de órdenes: No disponible desde la API nativa; consulta archivos o terceros.

Fallos Comunes y Solución de Problemas

Al trabajar con las APIs de datos de Hyperliquid, puedes encontrar problemas como limitación de velocidad, formatos de solicitud incorrectos o datos faltantes. Aquí hay fallos comunes y cómo solucionarlos.

Limitación de velocidad: La API de Hyperliquid tiene límites de velocidad que varían según el endpoint y el tipo de suscripción. Si recibes HTTP 429 o desconexiones de WebSocket, probablemente estás excediendo el límite. Consulta la guía de límites de velocidad de la API de Hyperliquid para obtener detalles y mejores prácticas.

Solicitud no válida: Asegúrate de que tu JSON de solicitud coincida con el esquema documentado. Por ejemplo, la solicitud 'candleSnapshot' requiere un objeto 'req' con 'coin', 'interval', y opcionalmente 'startTime' y 'endTime'. Campos faltantes o tipos incorrectos resultarán en un error.

Datos no encontrados: Si solicitas operaciones para una moneda que no existe o un rango de tiempo sin datos, la API puede devolver un array vacío. Verifica el símbolo de la moneda y el rango de tiempo.

Problemas de conexión WebSocket: Si tu conexión WebSocket se cae, implementa lógica de reconexión con retroceso exponencial. Además, asegúrate de enviar el formato de mensaje de suscripción correcto.

• HTTP 429: Reduce la velocidad de las solicitudes y respeta los límites de velocidad.
• JSON no válido: Valida tu solicitud contra los documentos.
• Respuestas vacías: Verifica el símbolo de la moneda y el rango de tiempo.
• Desconexiones de WebSocket: Implementa lógica de reconexión.

Compensaciones y Limitaciones

La API nativa es rápida y fácil de usar, pero tiene limitaciones: solo proporciona una cantidad limitada de datos históricos (la retención exacta no está documentada), y no proporciona el historial de profundidad completa de la cartera de órdenes. Los archivos proporcionan un historial profundo pero requieren descargar y procesar archivos grandes, lo que puede llevar tiempo y requerir almacenamiento significativo.

Los revendedores de terceros pueden ofrecer un acceso más conveniente, pero son independientes y pueden tener una calidad de datos, cobertura y precios diferentes. Siempre verifica los datos contra fuentes oficiales cuando sea posible.

Para aplicaciones de producción, considera usar una combinación: usa la API nativa para datos en tiempo real y los archivos para backtesting histórico. Para necesidades de datos de alta frecuencia, es posible que necesites construir tu propio sistema de recopilación de datos utilizando suscripciones WebSocket.

Próximos Pasos y Lecturas Adicionales

Ahora que entiendes las superficies de la API de datos de Hyperliquid, puedes comenzar a construir tus propios pipelines de datos. Para más contexto sobre la infraestructura de Hyperliquid, consulta la descripción general de la red Hyperliquid. Si estás interesado en endpoints RPC, consulta los endpoints RPC de Hyperliquid (Asistente RPC). Para guías relacionadas, consulta Suscripciones WebSocket de Hyperliquid, Latencia RPC de Hyperliquid y Límites de velocidad de la API de Hyperliquid.

Para información general sobre servicios de API, visita la página de servicios de API y precios de RPC. Explora el centro de aprendizaje de OnFinality para más tutoriales y guías.

• Explora los documentos oficiales de Hyperliquid para obtener los últimos detalles de la API.
• Consulta revendedores de terceros como HypeRPC y QuickNode para servicios de datos extendidos.
• Únete a la comunidad de Hyperliquid para soporte y discusiones.