Hyperliquid MCP Server

A comprehensive Model Context Protocol (MCP) server that wraps the Hyperliquid SDK, providing cryptocurrency trading capabilities to AI assistants.

Overview

This MCP server enables AI assistants to interact with the Hyperliquid exchange for retrieving market data, executing trades, managing positions, and more. It implements the Model Context Protocol to expose the full range of trading functionality.

Features

• 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

Prerequisites

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

Installation

# Clone the repository
git clone https://github.com/TradingBalthazar/hyperliquid-mcp-server.git

# Navigate to the project directory
cd hyperliquid-mcp-server

# Install dependencies
npm install

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

Usage

Start the server by running:

npm start

Or run the demo client:

npm run demo

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

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.

License

MIT