Servidor MCP de Hyperliquid: Implementación completa

Este servidor MCP (Protocolo de Contexto de Modelo) proporciona un envoltorio completo para el SDK de Hyperliquid, exponiendo a los asistentes de IA todas las capacidades de negociación para los mercados al contado y de futuros. Permite a los asistentes de IA interactuar con la plataforma Hyperliquid para recuperar datos de mercado, ejecutar operaciones, gestionar posiciones y mucho más.

Características

Cobertura completa de API

Implementación completa de todas las API del SDK de Hyperliquid tanto para operaciones al contado como de futuros
Recuperación de datos de mercado (precios, libros de órdenes, velas)
Colocación y gestión de órdenes (mercado, límite, disparador, TWAP)
Gestión de posiciones (apalancamiento, margen, cierre)
Información y saldos de cuentas
Información sobre la tasa de financiación
Transferencias y retiros
Gestión de bóvedas
Gestión de subcuentas
Integración del sistema de referencias

Características técnicas

Autenticación adecuada utilizando tanto la clave privada como la dirección de la billetera
Manejo integral de errores y validación
Acceso a datos de mercado en tiempo real
Soporte para identificadores de pedidos de clientes (cloid) para seguimiento de pedidos
Soporte tanto para testnet como para mainnet

API identificadas e implementación

Basándome en un examen exhaustivo del repositorio del SDK de Hyperliquid, identifiqué e implementé las siguientes API:

API de datos de mercado

API	Descripción	Implementación
`getAllMids`	Obtenga todos los precios medios para todas las criptomonedas disponibles	Asignación directa a `info.getAllMids()` del SDK
`getL2Book`	Obtener datos del libro de órdenes para un símbolo	Asignación directa a la `info.getL2Book()` del SDK
`getCandleSnapshot`	Obtener datos históricos de velas	Asignación directa a `info.getCandleSnapshot()`
`getMetaAndAssetCtxs`	Obtenga metadatos y contextos de activos para futuros perpetuos	Asignación directa a `info.perpetuals.getMetaAndAssetCtxs()` del SDK
`getSpotMetaAndAssetCtxs`	Obtenga metadatos y contextos de activos para mercados al contado	Asignación directa a `info.spot.getSpotMetaAndAssetCtxs()` del SDK

API de información de cuenta

API	Descripción	Implementación
`getClearinghouseState`	Obtener el estado de la cuenta de futuros perpetuos	Asignación directa a `info.perpetuals.getClearinghouseState()` del SDK
`getSpotClearinghouseState`	Obtener el estado de la cuenta al contado	Asignación directa a `info.spot.getSpotClearinghouseState()` del SDK
`getUserOpenOrders`	Obtener órdenes abiertas	Asignación directa a la `info.getUserOpenOrders()` del SDK
`getUserFills`	Obtener rellenos comerciales	Asignación directa a `info.getUserFills()` del SDK
`getUserFillsByTime`	Obtener rellenos comerciales por rango de tiempo	Asignación directa a la `info.getUserFillsByTime()`
`getUserFunding`	Recibir pagos de financiación	Asignación directa a la información del SDK `info.perpetuals.getUserFunding()`
`getFundingHistory`	Obtener el historial de tasas de financiación	Asignación directa a `info.perpetuals.getFundingHistory()` del SDK
`getPredictedFundings`	Obtenga tasas de financiación previstas	Asignación directa a la información del SDK `info.perpetuals.getPredictedFundings()`

API de gestión de pedidos

API	Descripción	Implementación
`placeOrder`	Realizar una orden (de mercado, límite, disparador)	Asignación directa al `exchange.placeOrder()` del SDK
`placeTwapOrder`	Realizar un pedido de TWAP	Asignación directa al `exchange.placeTwapOrder()` del SDK
`cancelOrder`	Cancelar un pedido	Asignación directa al `exchange.cancelOrder()` del SDK
`cancelOrderByCloid`	Cancelar un pedido por ID de pedido del cliente	Asignación directa al `exchange.cancelOrderByCloid()`
`cancelTwapOrder`	Cancelar un pedido de TWAP	Asignación directa al `exchange.cancelTwapOrder()`
`modifyOrder`	Modificar un pedido existente	Asignación directa al `exchange.modifyOrder()` del SDK

API de gestión de posiciones

API	Descripción	Implementación
`updateLeverage`	Actualizar el apalancamiento de un símbolo	Asignación directa al `exchange.updateLeverage()` del SDK
`updateIsolatedMargin`	Actualizar el margen aislado de una posición	Asignación directa al `exchange.updateIsolatedMargin()`
`marketClose`	Cerrar una posición con una orden de mercado	Implementado a través de `custom.marketClose()` del SDK
`closeAllPositions`	Cerrar todas las posiciones	Implementado a través de `custom.closeAllPositions()` del SDK

API de transferencia y retiro

API	Descripción	Implementación
`usdTransfer`	Transferir USDC a otra billetera	Asignación directa al `exchange.usdTransfer()` del SDK
`initiateWithdrawal`	Retirar USDC a Arbitrum	Asignación directa al `exchange.initiateWithdrawal()` del SDK
`spotTransfer`	Transferir activos al contado a otra billetera	Asignación directa al `exchange.spotTransfer()` del SDK
`transferBetweenSpotAndPerp`	Transferencia entre cuentas al contado y perpetuas	Asignación directa al `exchange.transferBetweenSpotAndPerp()` del SDK

API de gestión de bóvedas

API	Descripción	Implementación
`createVault`	Crear una nueva bóveda	Asignación directa al `exchange.createVault()` del SDK
`getVaultDetails`	Obtener detalles de la bóveda	Asignación directa a `info.getVaultDetails()` del SDK
`vaultTransfer`	Transferir fondos entre la bóveda y la billetera	Asignación directa a `exchange.vaultTransfer()` del SDK
`vaultDistribute`	Distribuir fondos de la bóveda a los seguidores	Asignación directa a `exchange.vaultDistribute()` del SDK
`vaultModify`	Modificar la configuración de la bóveda	Asignación directa a `exchange.vaultModify()` del SDK

API de gestión de subcuentas

API	Descripción	Implementación
`createSubAccount`	Crear una nueva subcuenta	Asignación directa al `exchange.createSubAccount()` del SDK
`getSubAccounts`	Obtener todas las subcuentas	Asignación directa a `info.getSubAccounts()` del SDK
`subAccountTransfer`	Transferencia de fondos entre subcuentas (perpetua)	Asignación directa al `exchange.subAccountTransfer()` del SDK
`subAccountSpotTransfer`	Transferir activos al contado entre subcuentas	Asignación directa al `exchange.subAccountSpotTransfer()` del SDK

API diversas

API	Descripción	Implementación
`setReferrer`	Establecer un código de referencia	Asignación directa al `exchange.setReferrer()` del SDK
`referral`	Obtener información de referencia	Asignación directa a `info.referral()` del SDK
`setDisplayName`	Establecer un nombre para mostrar en la tabla de clasificación	Asignación directa al `exchange.setDisplayName()` del SDK
`getUserRole`	Obtener el rol de un usuario	Asignación directa a `info.getUserRole()` del SDK
`approveAgent`	Aprobar a un agente para que opere en nombre del usuario	Asignación directa al `exchange.approveAgent()` del SDK
`approveBuilderFee`	Aprobar una tarifa de construcción	Asignación directa al `exchange.approveBuilderFee()`

Implementación de autenticación

El servidor MCP implementa la autenticación utilizando tanto la clave privada como la dirección de la billetera:

Autenticación de clave privada : El servidor acepta una clave privada mediante una variable de entorno o un archivo de configuración. Esta clave privada se utiliza para firmar transacciones y autenticarse con la API de Hyperliquid.
Autenticación de la dirección de la billetera : El servidor también acepta una dirección de billetera, que se utiliza para operaciones de solo lectura. Si se proporciona una clave privada, pero no la dirección de la billetera, el servidor la derivará de la clave privada.
Compatibilidad con direcciones de bóveda : para las operaciones de bóveda, el servidor también admite la especificación de una dirección de bóveda.

La validación de autenticación se realiza antes de ejecutar cualquier operación que lo requiera, garantizando que el usuario esté correctamente autenticado antes de intentar ejecutar operaciones o acceder a la información de la cuenta.

Manejo de errores y validación

El servidor MCP implementa un manejo y validación de errores integral:

Validación del cliente : antes de ejecutar cualquier operación, el servidor valida que el cliente Hyperliquid esté inicializado.
Validación de autenticación : para las operaciones que requieren autenticación, el servidor valida que el usuario esté correctamente autenticado.
Validación de parámetros : el servidor valida todos los parámetros antes de pasarlos al SDK, garantizando que sean del tipo y formato correctos.
Manejo de errores : el servidor detecta y maneja todos los errores del SDK, proporcionando mensajes de error claros al usuario.
Registro : el servidor registra todas las operaciones y errores, lo que facilita la depuración de problemas.

Desafíos de implementación y consideraciones especiales

1. Implementación de órdenes de mercado

La API de Hyperliquid no tiene un punto de acceso directo para órdenes de mercado. En su lugar, las órdenes de mercado se implementan como órdenes límite agresivas con tiempo de vigencia de "Inmediato o Cancelación" (IOC). Para garantizar la ejecución, aplicamos un factor de deslizamiento al precio actual:

// Apply 0.5% slippage for market orders to ensure execution
const slippagePrice = isBuy ?
  currentPrice * 1.005 : // Buy 0.5% higher than mid price
  currentPrice * 0.995;  // Sell 0.5% lower than mid price

2. Manejo de símbolos del mercado al contado

Los símbolos del mercado al contado en Hyperliquid tienen el sufijo "-SPOT". El servidor MCP gestiona esto de forma transparente, añadiendo el sufijo cuando es necesario:

// For spot market orders, we need to use the same API endpoint but with the spot symbol
const spotSymbol = `${symbol}-SPOT`;

3. Análisis de la respuesta del pedido

El formato de respuesta de la API de Hyperliquid para la realización de pedidos es complejo y requiere un análisis cuidadoso para extraer el ID del pedido:

// Extract order ID from the response
let orderId = null;
if (result.response && result.response.data && result.response.data.statuses) {
  for (const status of result.response.data.statuses) {
    if (status.resting) {
      orderId = status.resting.oid;
      break;
    } else if (status.filled) {
      orderId = status.filled.oid;
      break;
    }
  }
}

4. Manejo de valores numéricos

La API de Hyperliquid suele devolver valores numéricos como cadenas. El servidor MCP los convierte a números para facilitar su uso:

// Convert string values to numbers
const result = {};
for (const [symbol, price] of Object.entries(allMids)) {
  result[symbol] = parseFloat(price);
}

5. Compatibilidad con WebSockets

El SDK de Hyperliquid admite conexiones WebSocket para datos en tiempo real. El servidor MCP inicializa el cliente con la compatibilidad con WebSocket habilitada:

client = new Hyperliquid({
  privateKey: config.privateKey,
  testnet: config.testnet,
  walletAddress: config.walletAddress,
  vaultAddress: config.vaultAddress,
  enableWs: true
});

Prerrequisitos

Node.js (v14 o superior)
Una cuenta hiperlíquida
Una clave privada de Ethereum para autenticación (necesaria para el comercio)
La dirección de su billetera (requerida para operar)

Configuración

El servidor se puede configurar utilizando variables de entorno o un archivo de configuración:

Variables de entorno

HYPERLIQUID_PRIVATE_KEY : Su clave privada de Ethereum para autenticación (requerida para operar)
HYPERLIQUID_WALLET_ADDRESS : La dirección de su billetera (necesaria para operar)
HYPERLIQUID_VAULT_ADDRESS : Su dirección de bóveda (opcional, para operaciones de bóveda)
HYPERLIQUID_TESTNET : Establézcalo en 'verdadero' para usar la red de prueba, en 'falso' para la red principal (valor predeterminado: falso)
LOG_LEVEL : Nivel de registro: 'depuración', 'información', 'advertencia' o 'error' (predeterminado: 'información')

Archivo de configuración

También puede crear un archivo .hyperliquid-config.json en el mismo directorio que el servidor con la siguiente estructura:

{
  "privateKey": "your-ethereum-private-key",
  "walletAddress": "your-wallet-address",
  "vaultAddress": "your-vault-address",
  "testnet": false,
  "logLevel": "info",
  "popularCoins": ["BTC", "ETH", "SOL", "AVAX", "ARB", "DOGE", "LINK", "MATIC"]
}

Ejecución del servidor

Inicie el servidor ejecutando:

node hyperliquid-mcp-server-complete.js

Herramientas disponibles

El servidor proporciona un conjunto completo de herramientas para interactuar con el intercambio de Hyperliquid. A continuación, se muestran algunos ejemplos:

Herramientas de datos de mercado

getMarketPrice : obtiene el precio actual de una criptomoneda específica
getOrderBook : obtiene el libro de órdenes actual para una criptomoneda específica
getCandleData : obtiene datos históricos de velas para una criptomoneda específica
getAllMids : Obtenga todos los precios medios de todas las criptomonedas disponibles

Herramientas de información de la cuenta

getAccountInfo : obtiene información sobre la cuenta de futuros perpetuos del usuario
getSpotAccountInfo : obtiene información sobre la cuenta de operaciones al contado del usuario
getUserOpenOrders : obtiene todos los pedidos abiertos para el usuario
getUserFills : obtiene los rellenos recientes del usuario

Herramientas de gestión de pedidos

placeMarketOrder : Realizar una orden de mercado para una criptomoneda específica
placeLimitOrder : coloca una orden limitada para una criptomoneda específica
placeTriggerOrder : coloca una orden de activación (stop loss o take profit)
placeTwapOrder : Realizar un pedido TWAP (Precio promedio ponderado en el tiempo)
cancelOrder : Cancelar un pedido existente
cancelOrderByCloid : Cancelar un pedido por ID de pedido del cliente
cancelAllOrders : Cancelar todos los pedidos abiertos
modifyOrder : Modificar un pedido existente

Herramientas de gestión de posiciones

updateLeverage : Actualiza el apalancamiento de una criptomoneda específica
updateIsolatedMargin : Actualiza el margen aislado para una posición
closePosition : Cerrar una posición abierta
closeAllPositions : Cerrar todas las posiciones abiertas

Herramientas de transferencia y retiro

usdTransfer : transfiere USDC a otra billetera
initiateWithdrawal : Retirar USDC a Arbitrum
spotTransfer : transfiere activos spot a otra billetera
transferBetweenSpotAndPerp : transfiere fondos entre cuentas al contado y perpetuas

Herramientas de gestión de bóvedas

createVault : Crea una nueva bóveda
getVaultDetails : obtener detalles sobre una bóveda
vaultTransfer : transfiere fondos entre la bóveda y la billetera de futuros perpetuos
vaultDistribute : Distribuye fondos desde una bóveda a los seguidores
vaultModify : Modificar la configuración de la bóveda

Herramientas de gestión de subcuentas

createSubAccount : Crea una nueva subcuenta
getSubAccounts : obtiene todas las subcuentas del usuario
subAccountTransfer : Transferir fondos entre subcuentas (perpetuo)
subAccountSpotTransfer : Transferir activos al contado entre subcuentas

Recursos disponibles

El servidor proporciona los siguientes recursos:

market-data : Datos de mercado de criptomonedas populares en el mercado de futuros perpetuos
account-info : Información de la cuenta, incluidos saldos y posiciones para futuros perpetuos
spot-market-data : Datos de mercado de criptomonedas populares en el mercado spot
spot-account-info : Información de la cuenta, incluidos los saldos para operaciones al contado
open-orders : todas las órdenes abiertas para el usuario
positions : Todas las posiciones abiertas para el usuario
funding-rates : tasas de financiación actuales para todas las criptomonedas

Consideraciones de seguridad

Seguridad de la clave privada : Tu clave privada de Ethereum te da acceso completo a tus fondos. Nunca la compartas ni la expongas en repositorios públicos.
Utilice Testnet primero : pruebe siempre su configuración en Testnet antes de utilizar fondos reales en Mainnet.
Limitar acceso : restrinja el acceso al servidor MCP a aplicaciones y asistentes de IA confiables.

Descargo de responsabilidad

Operar con criptomonedas conlleva un riesgo significativo. Esta herramienta se proporciona únicamente con fines educativos e informativos. Siempre comprenda los riesgos antes de operar y nunca opere con fondos que no pueda permitirse perder.

Hyperliquid MCP Server