Hyperliquid no publica documentación específica para HIP-4. Lo que sigue lo hemos sacado de probar la API en directo: peticiones reales, respuestas reales. Si vas a construir algo sobre los mercados de predicción de Hyperliquid, esto es lo que necesitas saber antes de escribir una línea de código.
Un solo endpoint para leerlo todo
Toda la lectura de datos pasa por el mismo sitio:
POST https://api.hyperliquid.xyz/info
Content-Type: application/json
No hay autenticación ni API key. Es información pública: cualquier petición vale mientras lleve el type correcto en el cuerpo.
outcomeMeta: el mapa del catálogo
El primer paso siempre es el mismo: averiguar qué mercados existen y qué identificador tiene cada uno.
curl -X POST https://api.hyperliquid.xyz/info -H "Content-Type: application/json" -d '{"type":"outcomeMeta"}'
La respuesta trae dos listas:
questions— el evento legible ("2026 World Cup Champion"), con susnamedOutcomesy las reglas de resolución completas.outcomes— los contratos individuales. Cada uno tiene un campooutcome, que es su identificador numérico.
Ese campo outcome es la pieza clave. Ojo: es el ID que viene en el objeto, NO la posición del elemento en el array. Confundirlos es el primer error que vas a cometer.
Hoy el catálogo es pequeño (~23 outcomes en mainnet): Mundial 2026, decisión de la Fed, IPC y los binarios diarios de BTC, ETH, SOL y HYPE. No hay endpoint para pedir un solo mercado: se pide el catálogo entero y se filtra en tu código.
El encoding: la parte que nadie explica
Cada mercado tiene DOS contratos —Sí y No— y cada uno necesita su propio identificador de asset. La fórmula:
encoding = 10 × outcome + side (side: 0 = Sí, 1 = No)
Si el outcome con "outcome": 813 es "Francia gana la semifinal":
- Sí → 10 × 813 + 0 = 8130
- No → 10 × 813 + 1 = 8131
Y aquí va el detalle que te hará perder una tarde si no lo sabes: para consultar datos, ese número va prefijado con almohadilla: "#8130". Sin el #, la API te devuelve null sin explicar por qué.
curl -X POST https://api.hyperliquid.xyz/info -H "Content-Type: application/json" -d '{"type":"l2Book","coin":"#8130"}'
Para firmar órdenes el identificador es otro: 100000000 + encoding (cien millones más el encoding). Son dos numeraciones distintas para el mismo contrato, según si lees o si operas.
l2Book: profundidad, pero con truco
El libro del Sí y el libro del No son el mismo libro, reflejado. Si pides el asset del Sí y ves una mejor compra a 0,31, es matemáticamente la misma orden que "vender No a 0,69". Los dos lados suman 1,00 siempre.
Consecuencia directa para tu código: si buscas liquidez, consulta los dos lados. A veces el que te interesa parece vacío y toda la profundidad está expresada en el reflejo.
allMids: el precio de todo, de una vez
Para un dashboard, no vayas mercado por mercado:
curl -X POST https://api.hyperliquid.xyz/info -H "Content-Type: application/json" -d '{"type":"allMids"}'
Devuelve todos los precios medios de golpe, con las claves ya en formato #encoding. Es la llamada más barata que puedes hacer y la que más bucles te ahorra.
candleSnapshot: el histórico
Mismo encoding, distinto type:
curl -X POST https://api.hyperliquid.xyz/info -H "Content-Type: application/json" -d '{"type":"candleSnapshot","req":{"coin":"#8130","interval":"1h","startTime":1751328000000,"endTime":1752537600000}}'
Los timestamps van en milisegundos, no en segundos. Es el fallo más común al portar código de otras APIs: si pones segundos, te devuelve un array vacío y no te dice por qué.
El precio ES la probabilidad
El precio del contrato (entre 0,001 y 0,999) es la probabilidad. No hay que normalizar nada. Si el mid del Sí es 0,21, el mercado dice 21%.
Donde sí hay que pensar es al comparar los dos lados: en teoría suman 1, pero con el spread los mids pueden no sumar exactamente 1,00 si el libro está desequilibrado.
Cómo distinguir un precio real de uno fantasma
Esto es lo más importante del artículo. Que la API devuelva un precio no significa que haya nadie con quien operar.
Nos hemos encontrado mercados con precio de referencia en allMids pero con l2Book completamente vacío en ambos lados. Un frontend mal hecho pintaría ese precio como si fuera operable. No lo es: tu orden se quedaría esperando eternamente.
Antes de mostrar un precio como "disponible", comprueba que l2Book trae al menos un nivel real en el lado que te interesa. Si el array de niveles viene vacío, no hay mercado: hay un número.
Lo que falta por documentar
Con honestidad: esto es ingeniería inversa, no documentación oficial. No hemos encontrado especificación pública de límites de peticiones, esquema OpenAPI ni versionado. Si construyes en producción, mete manejo de errores defensivo: la respuesta puede cambiar de forma sin aviso, porque oficialmente HIP-4 sigue en fase de pruebas.