Hyperliquid MCP Server 🚀

Model Context Protocol (MCP) server for Hyperliquid — 48 tools for trading, monitoring, risk management, and security on the Hyperliquid perpetual DEX.

Built on the official hyperliquid-python-sdk with production-grade error handling.

---

Features

📡 Tier 1 — Monitoring (15 tools)

• Real-time user state, positions, balances
• Open orders, trade history, funding history
• Market data: mid prices, L2 order book, candlesticks
• Sub-accounts, staking, fee structure

💹 Tier 2 — Trading (10 tools)

• Limit, market, and trigger orders
• Bracket orders (entry + TP + SL)
• Position management: modify, close, leverage
• Funding rate impact calculator

⚠️ Tier 3 — Risk Management (10 tools)

• Order risk validation before execution
• Liquidation price estimation
• Margin health monitoring
• Portfolio health check & simulation
• Auto leverage adjustment

🔒 Tier 4 — Security (8 tools)

• Wallet & configuration validation
• Preflight checks before trading
• API Wallet / Agent Mode setup
• Trading limits, rate limiting
• Audit trail & emergency stop

📊 Bonus Analytics (5 tools)

• Position analysis with P&L and risk scoring
• Performance metrics (win rate, Sharpe, drawdown)
• Multi-coin comparison
• Strategy backtesting (MA/RSI/Momentum)
• Market sentiment analysis

---

Quick Start

1. Install

git clone https://github.com/samimiair/hyperliquid-mcp.git
cd hyperliquid-mcp
pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit .env with your wallet details:
#   HYPERLIQUID_PRIVATE_KEY=your_64_char_hex_key
#   HYPERLIQUID_ACCOUNT_ADDRESS=0xYourWalletAddress

3. Run

./run.sh

Or run directly with Hermes:

hermes mcp add hyperliquid --command /path/to/hyperliquid-mcp/run.sh
hermes config set mcp_servers.hyperliquid.cwd /path/to/hyperliquid-mcp
hermes config set mcp_servers.hyperliquid.timeout 120

---

Environment Variables

Variable	Required	Description
HYPERLIQUID_PRIVATE_KEY	✅	Your wallet private key (64 hex chars)
HYPERLIQUID_ACCOUNT_ADDRESS	✅	Your wallet address (0x...)
HYPERLIQUID_API_WALLET	❌	API wallet for Agent Mode
HYPERLIQUID_TESTNET	❌	Set to "true" for testnet (default: mainnet)

---

Architecture

hyperliquid-mcp/
├── main.py            # MCP server entry point (48 tools)
├── api_client.py      # Hyperliquid API wrapper (SDK-based)
├── trading.py         # Order placement & management
├── monitoring.py      # Market data & state queries
├── risk_mgmt.py       # Risk validation & simulation
├── security.py        # Wallet & configuration checks
├── validators.py      # Input validation
├── rate_limiter.py    # API rate limiting
├── alert_manager.py   # Error & alert handling
├── wallet.py          # (Deprecated) Legacy wallet code
├── run.sh             # Startup script with env validation
├── .env.example       # Configuration template
└── requirements.txt   # Dependencies

---

Security

• Never commit your .env file — it's in .gitignore
• All secrets are read from environment variables
• The run.sh script validates required env vars before starting
• Use API Wallet / Agent Mode to limit trading permissions
• Emergency stop tool (emergency_stop) closes all positions instantly

---

License

MIT