Hyperliquid MCP Server - Complete Implementation

This MCP (Model Context Protocol) server provides a comprehensive wrapper around the Hyperliquid SDK, exposing the full range of trading capabilities for both spot and futures markets to AI assistants. It enables AI assistants to interact with the Hyperliquid exchange for retrieving market data, executing trades, managing positions, and more.

Features

Comprehensive API Coverage

• Complete implementation of all Hyperliquid SDK APIs for both spot and futures trading
• Market data retrieval (prices, order books, candles)
• Order placement and management (market, limit, trigger, TWAP)
• Position management (leverage, margin, closing)
• Account information and balances
• Funding rate information
• Transfers and withdrawals
• Vault management
• Sub-account management
• Referral system integration

Technical Features

• Proper authentication using both private key and wallet address
• Comprehensive error handling and validation
• Real-time market data access
• Support for client order IDs (cloid) for order tracking
• Support for both testnet and mainnet

Identified APIs and Implementation

Based on a thorough examination of the Hyperliquid SDK repository, I've identified and implemented the following APIs:

Market Data APIs

| API | Description | Implementation | |-----|-------------|----------------| | getAllMids | Get all mid prices for all available cryptocurrencies | Direct mapping to SDK's info.getAllMids() | | getL2Book | Get order book data for a symbol | Direct mapping to SDK's info.getL2Book() | | getCandleSnapshot | Get historical candle data | Direct mapping to SDK's info.getCandleSnapshot() | | getMetaAndAssetCtxs | Get metadata and asset contexts for perpetual futures | Direct mapping to SDK's info.perpetuals.getMetaAndAssetCtxs() | | getSpotMetaAndAssetCtxs | Get metadata and asset contexts for spot markets | Direct mapping to SDK's info.spot.getSpotMetaAndAssetCtxs() |

Account Information APIs

| API | Description | Implementation | |-----|-------------|----------------| | getClearinghouseState | Get perpetual futures account state | Direct mapping to SDK's info.perpetuals.getClearinghouseState() | | getSpotClearinghouseState | Get spot account state | Direct mapping to SDK's info.spot.getSpotClearinghouseState() | | getUserOpenOrders | Get open orders | Direct mapping to SDK's info.getUserOpenOrders() | | getUserFills | Get trade fills | Direct mapping to SDK's info.getUserFills() | | getUserFillsByTime | Get trade fills by time range | Direct mapping to SDK's info.getUserFillsByTime() | | getUserFunding | Get funding payments | Direct mapping to SDK's info.perpetuals.getUserFunding() | | getFundingHistory | Get funding rate history | Direct mapping to SDK's info.perpetuals.getFundingHistory() | | getPredictedFundings | Get predicted funding rates | Direct mapping to SDK's info.perpetuals.getPredictedFundings() |

Order Management APIs

| API | Description | Implementation | |-----|-------------|----------------| | placeOrder | Place an order (market, limit, trigger) | Direct mapping to SDK's exchange.placeOrder() | | placeTwapOrder | Place a TWAP order | Direct mapping to SDK's exchange.placeTwapOrder() | | cancelOrder | Cancel an order | Direct mapping to SDK's exchange.cancelOrder() | | cancelOrderByCloid | Cancel an order by client order ID | Direct mapping to SDK's exchange.cancelOrderByCloid() | | cancelTwapOrder | Cancel a TWAP order | Direct mapping to SDK's exchange.cancelTwapOrder() | | modifyOrder | Modify an existing order | Direct mapping to SDK's exchange.modifyOrder() |

Position Management APIs

| API | Description | Implementation | |-----|-------------|----------------| | updateLeverage | Update leverage for a symbol | Direct mapping to SDK's exchange.updateLeverage() | | updateIsolatedMargin | Update isolated margin for a position | Direct mapping to SDK's exchange.updateIsolatedMargin() | | marketClose | Close a position with a market order | Implemented via SDK's custom.marketClose() | | closeAllPositions | Close all positions | Implemented via SDK's custom.closeAllPositions() |

Transfer and Withdrawal APIs

| API | Description | Implementation | |-----|-------------|----------------| | usdTransfer | Transfer USDC to another wallet | Direct mapping to SDK's exchange.usdTransfer() | | initiateWithdrawal | Withdraw USDC to Arbitrum | Direct mapping to SDK's exchange.initiateWithdrawal() | | spotTransfer | Transfer spot assets to another wallet | Direct mapping to SDK's exchange.spotTransfer() | | transferBetweenSpotAndPerp | Transfer between spot and perpetual accounts | Direct mapping to SDK's exchange.transferBetweenSpotAndPerp() |

Vault Management APIs

| API | Description | Implementation | |-----|-------------|----------------| | createVault | Create a new vault | Direct mapping to SDK's exchange.createVault() | | getVaultDetails | Get vault details | Direct mapping to SDK's info.getVaultDetails() | | vaultTransfer | Transfer funds between vault and wallet | Direct mapping to SDK's exchange.vaultTransfer() | | vaultDistribute | Distribute funds from vault to followers | Direct mapping to SDK's exchange.vaultDistribute() | | vaultModify | Modify vault configuration | Direct mapping to SDK's exchange.vaultModify() |

Sub-Account Management APIs

| API | Description | Implementation | |-----|-------------|----------------| | createSubAccount | Create a new sub-account | Direct mapping to SDK's exchange.createSubAccount() | | getSubAccounts | Get all sub-accounts | Direct mapping to SDK's info.getSubAccounts() | | subAccountTransfer | Transfer funds between sub-accounts (perpetual) | Direct mapping to SDK's exchange.subAccountTransfer() | | subAccountSpotTransfer | Transfer spot assets between sub-accounts | Direct mapping to SDK's exchange.subAccountSpotTransfer() |

Miscellaneous APIs

| API | Description | Implementation | |-----|-------------|----------------| | setReferrer | Set a referrer code | Direct mapping to SDK's exchange.setReferrer() | | referral | Get referral information | Direct mapping to SDK's info.referral() | | setDisplayName | Set display name for leaderboard | Direct mapping to SDK's exchange.setDisplayName() | | getUserRole | Get the role of a user | Direct mapping to SDK's info.getUserRole() | | approveAgent | Approve an agent to trade on behalf of the user | Direct mapping to SDK's exchange.approveAgent() | | approveBuilderFee | Approve a builder fee | Direct mapping to SDK's exchange.approveBuilderFee() |

Authentication Implementation

The MCP server implements authentication using both private key and wallet address:

1. Private Key Authentication: The server accepts a private key via environment variable or configuration file. This private key is used to sign transactions and authenticate with the Hyperliquid API.

2. Wallet Address Authentication: The server also accepts a wallet address, which is used for read-only operations. If a private key is provided but no wallet address, the server will derive the wallet address from the private key.

3. Vault Address Support: For vault operations, the server also supports specifying a vault address.

Authentication validation is performed before executing any operation that requires it, ensuring that the user is properly authenticated before attempting to execute trades or access account information.

Error Handling and Validation

The MCP server implements comprehensive error handling and validation:

1. Client Validation: Before executing any operation, the server validates that the Hyperliquid client is initialized.

2. Authentication Validation: For operations that require authentication, the server validates that the user is properly authenticated.

3. Parameter Validation: The server validates all parameters before passing them to the SDK, ensuring that they are of the correct type and format.

4. Error Handling: The server catches and handles all errors from the SDK, providing clear error messages to the user.

5. Logging: The server logs all operations and errors, making it easier to debug issues.

Implementation Challenges and Special Considerations

1. Market Order Implementation

Hyperliquid's API doesn't have a direct "market order" endpoint. Instead, market orders are implemented as aggressive limit orders with Immediate-or-Cancel (IOC) time-in-force. To ensure execution, we apply a slippage factor to the current price:

// 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. Spot Market Symbol Handling

Spot market symbols in Hyperliquid have a "-SPOT" suffix. The MCP server handles this transparently, adding the suffix when needed:

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

3. Order Response Parsing

The response format from the Hyperliquid API for order placement is complex and requires careful parsing to extract the order ID:

// 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. Numeric Value Handling

The Hyperliquid API often returns numeric values as strings. The MCP server converts these to numbers for easier consumption:

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

5. WebSocket Support

The Hyperliquid SDK supports WebSocket connections for real-time data. The MCP server initializes the client with WebSocket support enabled:

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

Prerequisites

• Node.js (v14 or higher)
• A Hyperliquid account
• An Ethereum private key for authentication (required for trading)
• Your wallet address (required for trading)

Configuration

The server can be configured using environment variables or a configuration file:

Environment Variables

• HYPERLIQUID_PRIVATE_KEY: Your Ethereum private key for authentication (required for trading)
• HYPERLIQUID_WALLET_ADDRESS: Your wallet address (required for trading)
• HYPERLIQUID_VAULT_ADDRESS: Your vault address (optional, for vault operations)
• HYPERLIQUID_TESTNET: Set to 'true' to use testnet, 'false' for mainnet (default: false)
• LOG_LEVEL: Logging level - 'debug', 'info', 'warn', or 'error' (default: 'info')

Configuration File

You can also create a .hyperliquid-config.json file in the same directory as the server with the following structure:

{
  "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"]
}

Running the Server

Start the server by running:

node hyperliquid-mcp-server-complete.js

Available Tools

The server provides a comprehensive set of tools for interacting with the Hyperliquid exchange. Here are some examples:

Market Data Tools

• getMarketPrice: Get the current price for a specified cryptocurrency
• getOrderBook: Get the current order book for a specified cryptocurrency
• getCandleData: Get historical candle data for a specified cryptocurrency
• getAllMids: Get all mid prices for all available cryptocurrencies

Account Information Tools

• getAccountInfo: Get information about the user's perpetual futures account
• getSpotAccountInfo: Get information about the user's spot trading account
• getUserOpenOrders: Get all open orders for the user
• getUserFills: Get recent fills for the user

Order Management Tools

• placeMarketOrder: Place a market order for a specified cryptocurrency
• placeLimitOrder: Place a limit order for a specified cryptocurrency
• placeTriggerOrder: Place a trigger order (stop loss or take profit)
• placeTwapOrder: Place a TWAP (Time-Weighted Average Price) order
• cancelOrder: Cancel an existing order
• cancelOrderByCloid: Cancel an order by client order ID
• cancelAllOrders: Cancel all open orders
• modifyOrder: Modify an existing order

Position Management Tools

• updateLeverage: Update the leverage for a specified cryptocurrency
• updateIsolatedMargin: Update the isolated margin for a position
• closePosition: Close an open position
• closeAllPositions: Close all open positions

Transfer and Withdrawal Tools

• usdTransfer: Transfer USDC to another wallet
• initiateWithdrawal: Withdraw USDC to Arbitrum
• spotTransfer: Transfer spot assets to another wallet
• transferBetweenSpotAndPerp: Transfer funds between spot and perpetual accounts

Vault Management Tools

• createVault: Create a new vault
• getVaultDetails: Get details about a vault
• vaultTransfer: Transfer funds between vault and perpetual futures wallet
• vaultDistribute: Distribute funds from a vault to followers
• vaultModify: Modify vault configuration

Sub-Account Management Tools

• createSubAccount: Create a new sub-account
• getSubAccounts: Get all sub-accounts for the user
• subAccountTransfer: Transfer funds between sub-accounts (perpetual)
• subAccountSpotTransfer: Transfer spot assets between sub-accounts

Available Resources

The server provides the following resources:

• market-data: Market data for popular cryptocurrencies in the perpetual futures market
• account-info: Account information including balances and positions for perpetual futures
• spot-market-data: Market data for popular cryptocurrencies in the spot market
• spot-account-info: Account information including balances for spot trading
• open-orders: All open orders for the user
• positions: All open positions for the user
• funding-rates: Current funding rates for all cryptocurrencies

Security Considerations

• Private Key Security: Your Ethereum private key provides full access to your funds. Never share it or expose it in public repositories.
• Use Testnet First: Always test your setup on testnet before using real funds on mainnet.
• Limit Access: Restrict access to the MCP server to trusted AI assistants and applications.

Disclaimer

Trading cryptocurrencies involves significant risk. This tool is provided for educational and informational purposes only. Always understand the risks involved before trading, and never trade with funds you cannot afford to lose.