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

Integrations