Cómo integrar Hyperliquid en una wallet: guía completa para desarrolladores

A medida que madura el mercado de derivados descentralizados, cada vez más equipos de wallets buscan integrar la operativa de contratos perpetuos de Hyperliquid directamente en su interfaz. El objetivo es ofrecer una experiencia DeFi más completa sin obligar al usuario a saltar entre aplicaciones.

Esta guía está pensada para desarrolladores de wallets. Repasamos las rutas técnicas principales para integrar Hyperliquid: modelo de cuentas, esquemas de firma, llamadas desde frontend/SDK y puntos críticos de seguridad, para que tu equipo pueda avanzar con menos fricción.

Modelo de cuentas de Hyperliquid

Hyperliquid utiliza un sistema de direcciones compatible con EVM, es decir, direcciones en formato Ethereum. Los usuarios firman con claves privadas ECDSA estándar.

Según la documentación oficial, las cuentas se dividen en dos tipos:

• Vault Address: dirección principal a nivel de protocolo, propietaria de los activos.
• Agent Address: dirección secundaria autorizada para firmar ciertas acciones y reducir fricción en operaciones frecuentes.

Para una integración de wallet, el enfoque más común es usar la dirección principal del usuario como Vault Address y, de forma opcional, permitir la autorización de una wallet caliente como Agent para operaciones de alta frecuencia.

Métodos de conexión: WalletConnect vs RPC directo

Opción 1: WalletConnect 2.0

WalletConnect es actualmente uno de los protocolos de conexión más usados entre wallets y aplicaciones Web3. La aplicación web de Hyperliquid soporta WalletConnect 2.0 de forma nativa.

Pasos generales de integración:

1. Implementar en tu app de wallet el manejo de Session Proposal de WalletConnect 2.0.
2. Permitir que el usuario autorice mediante QR o deep link.
3. Escuchar solicitudes como eth_sendTransaction y personal_sign, y devolver las firmas correspondientes.

La ventaja de este enfoque es que es poco invasivo: la wallet no necesita conocer a fondo el protocolo interno de Hyperliquid, solo debe exponer interfaces estándar de firma Ethereum.

Opción 2: integrar directamente el SDK de Hyperliquid en Python/JS

Si quieres ofrecer funciones más profundas dentro de la wallet, como consultar posiciones o colocar órdenes directamente desde tu propia interfaz, puedes usar SDKs compatibles:

pip install hyperliquid-python-sdk

# o

npm install @nktkas/hyperliquid

El SDK de Python de Hyperliquid encapsula gran parte de la lógica de firma y envío de requests, lo que puede simplificar integraciones más avanzadas.

Esquema de firma: EIP-712 estructurado

Todas las operaciones de escritura en Hyperliquid —como colocar órdenes, cancelar órdenes, depósitos y retiros— utilizan firmas estructuradas EIP-712, no simples firmas eth_sign.

Esto tiene un impacto directo en la experiencia y seguridad del usuario:

• Una wallet con soporte adecuado para EIP-712 puede mostrar contenido legible, por ejemplo: “Abrir long BTC perpetual, tamaño 0.01, orden límite 65,000 USDC”.
• Una wallet sin soporte de EIP-712 podría mostrar únicamente bytes en hexadecimal, lo cual genera una mala experiencia y aumenta el riesgo de que el usuario firme algo que no entiende.

Para una integración seria, conviene priorizar el parseo y la visualización clara de mensajes EIP-712. Puedes tomar como referencia el estándar signTypedData_v4 de la especificación EIP-712.

Integración del API principal: flujo para colocar una orden

Ejemplo en JavaScript para colocar una orden límite de compra mediante llamadas directas al API:

import { ethers } from "ethers";

const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";

async function placeOrder(wallet, coin, isBuy, price, size) {
  const nonce = Date.now();

  const orderPayload = {
    type: "order",
    orders: [{
      a: 0,           // asset index (0 = BTC)
      b: isBuy,
      p: price.toString(),
      s: size.toString(),
      r: false,       // reduce-only
      t: { limit: { tif: "Gtc" } }
    }],
    grouping: "na"
  };

  // La definición completa del Domain y Types EIP-712 está en la documentación oficial
  const signature = await wallet._signTypedData(domain, types, orderPayload);

  const body = {
    action: orderPayload,
    nonce,
    signature,
  };

  const resp = await fetch(EXCHANGE_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  return resp.json();
}

Para los detalles completos de Domain y Types, consulta la documentación oficial de Hyperliquid sobre el Exchange Endpoint.

Consulta de balances y posiciones

Las consultas de solo lectura no requieren firma:

async function getAccountInfo(address) {
  const resp = await fetch("https://api.hyperliquid.xyz/info", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "clearinghouseState",
      user: address,
    }),
  });

  return resp.json();
}

La respuesta incluye datos como:

• marginSummary: margen disponible y valor total.
• assetPositions: detalle de posiciones por activo.
• crossMaintenanceMarginUsed: margen de mantenimiento usado en modo cross, entre otros campos.

Puntos clave de seguridad

Al integrar un protocolo de derivados en una wallet, la seguridad debe ser la prioridad.

Aislamiento de claves privadas

La firma de operaciones debe realizarse dentro de un entorno seguro, como Secure Enclave o un dispositivo de hardware. La clave privada nunca debe exponerse al código de la capa de aplicación.

Para una referencia práctica, puedes revisar la arquitectura open source de OneKey y su enfoque de aislamiento mediante hardware wallet.

Confirmación clara de montos y riesgo

Antes de colocar una orden, la wallet debe mostrar una pantalla de confirmación legible para humanos. Como mínimo, debería incluir:

• Activo.
• Dirección de la operación: long o short.
• Tamaño.
• Tipo de orden y precio.
• Apalancamiento, si aplica.
• Precio estimado de liquidación, cuando esté disponible.

En trading de perpetuos, ocultar o simplificar demasiado esta información puede llevar a errores costosos.

Límites para Agent Address

Si usas el modo Agent, la interfaz debe permitir que el usuario revoque la autorización en cualquier momento. También conviene mostrar de forma visible qué Agent Address está autorizada actualmente.

Un Agent suele usarse para automatización o trading frecuente, pero no debe confundirse con la dirección principal propietaria de los fondos.

Protección contra replay attacks

Utiliza correctamente el mecanismo de nonce de Hyperliquid. Cada orden debe tener un nonce monotónicamente creciente para reducir el riesgo de ataques de repetición.

Arquitectura recomendada: integrar con OneKey

OneKey Hardware Wallet soporta de forma nativa firmas Ethereum EIP-712. Además, su SDK open source ofrece APIs de firma estructurada que pueden servir como referencia para integraciones profundas con protocolos EVM de derivados como Hyperliquid.

Para equipos que quieren ofrecer trading de perpetuos dentro de una wallet, vale la pena tomar como referencia el enfoque de OneKey Perps: combinar una experiencia de trading fluida con protección basada en hardware, sin sacrificar seguridad por velocidad.

Si estás evaluando un flujo práctico para usuarios finales, puedes descargar OneKey y probar OneKey Perps para operar perpetuos desde un entorno diseñado con foco en autocustodia y control de firmas.

Preguntas frecuentes

Q1: ¿Qué métodos de conexión soporta Hyperliquid?

Hyperliquid soporta wallets como MetaMask, wallets compatibles con WalletConnect 2.0 y acceso programático mediante firma directa con clave privada. En teoría, cualquier wallet Ethereum capaz de realizar firmas ECDSA puede integrarse.

Q2: ¿Cuál es la diferencia entre Agent Address y la dirección principal?

Una Agent Address es una dirección secundaria autorizada por la dirección principal. Normalmente se usa para bots o flujos de trading automatizado. El Agent puede ejecutar acciones específicas, como colocar órdenes, pero no retirar fondos, lo que reduce el impacto potencial si esa clave se ve comprometida.

Q3: ¿Necesito pedir permiso o una licencia de API al equipo de Hyperliquid?

No. Hyperliquid es un protocolo sin permisos. El Info Endpoint es público y las operaciones de escritura en el Exchange Endpoint solo requieren una firma EIP-712 válida. No hace falta whitelist ni autorización previa.

Q4: ¿Cómo muestro el PnL no realizado en la UI de la wallet?

El endpoint clearinghouseState devuelve assetPositions. Dentro de cada posición encontrarás el campo unrealizedPnl, que puedes mostrar directamente en la interfaz. Ten en cuenta que este valor está denominado en USDC.

Q5: ¿Cuál es la dirección del testnet?

El endpoint de testnet de Hyperliquid es:

https://api.hyperliquid-testnet.xyz/

Puedes usarlo durante el desarrollo para probar funciones sin involucrar fondos reales.

Aviso de riesgo

Este artículo es una referencia técnica de integración y no constituye asesoría financiera, legal ni de inversión. El trading de contratos perpetuos implica riesgos elevados, especialmente por el uso de apalancamiento. Los desarrolladores deben comprender bien las reglas del protocolo y diseñar controles de seguridad adecuados antes de llevar una integración a producción.