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:

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.
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.
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:

Client Validation: Before executing any operation, the server validates that the Hyperliquid client is initialized.
Authentication Validation: For operations that require authentication, the server validates that the user is properly authenticated.
Parameter Validation: The server validates all parameters before passing them to the SDK, ensuring that they are of the correct type and format.
Error Handling: The server catches and handles all errors from the SDK, providing clear error messages to the user.
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.