Hyperliquid Mcp

Hyperliquid MCP Server

A Model Context Protocol (MCP) server for Hyperliquid perpetual trading using the official Python SDK. This server provides AI assistants with secure, reliable access to Hyperliquid's trading platform.

Features

✅ Official SDK - Built on the official Hyperliquid Python SDK with proper signing ✅ Complete Coverage - All trading endpoints: orders, positions, market data, vaults ✅ Secure - Proper EIP-712 signing with agent mode support ✅ Bracket Orders - Atomic entry + TP + SL order placement ✅ Market Data - Real-time prices, order books, funding rates, candles ✅ Live WebSocket State Engine - In-memory order book mirror for instant, low-latency reads ✅ Microstructure Signals - Server-computed OBI, micro-price, and spread (bps) in a ~20-token payload ✅ Trade-Flow Signals - Server-computed CVD, aggressor volume, and trade-flow imbalance from the live trade tape ✅ Monte Carlo Risk - Vectorized GBM simulation (10k+ paths) returning VaR, terminal distribution, and probability of profit ✅ Account Management - Positions, balances, fills, funding history ✅ Testnet Support - Test strategies safely before going live

Prerequisites

• Python 3.10 or higher
• uv or uvx for package management
• A Hyperliquid account with deposited funds

Installation

Using uvx (Recommended)

# Install and run directly from PyPI
uvx --from mcp-hyperliquid hyperliquid-mcp

Using pip

# Install with pip
pip install mcp-hyperliquid

# Run
mcp-hyperliquid

Local Development

# Clone and install from source
git clone https://github.com/Dakkshin/hyperliquid-mcp.git
cd hyperliquid-mcp
uv sync

# Run locally
uv run python -m hyperliquid_mcp.server

Local Development Configuration

If you're running from source code locally, use this configuration:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/hyperliquid-mcp",
        "run",
        "python",
        "-m",
        "hyperliquid_mcp.server"
      ],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
        "HYPERLIQUID_TESTNET": "false"
      }
    }
  }
}

Replace /path/to/hyperliquid-mcp with the actual path to your cloned repository.

Configuration

1. Register Your Wallet on Hyperliquid

IMPORTANT: Your wallet must be registered on Hyperliquid before trading.

Mainnet:

1. Go to https://app.hyperliquid.xyz
2. Connect your wallet
3. Deposit funds from Arbitrum One (any amount registers your wallet)

Testnet:

1. Go to https://app.hyperliquid-testnet.xyz
2. Connect your wallet
3. Get testnet funds from the faucet or bridge

2. Configure Your MCP Client

Environment variables are now configured directly in your MCP client settings (no .env file needed).

Claude Desktop / Kiro

Add to your mcp.json configuration file:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["--from", "mcp-hyperliquid", "hyperliquid-mcp"],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
        "HYPERLIQUID_TESTNET": "false"
      }
    }
  }
}

Required Environment Variables:

• HYPERLIQUID_PRIVATE_KEY - Your wallet's private key for signing transactions

Optional Environment Variables:

• HYPERLIQUID_ACCOUNT_ADDRESS - For agent/API wallet mode (advanced)
• HYPERLIQUID_TESTNET - Set to "true" for testnet, "false" or omit for mainnet
• HYPERLIQUID_VAULT_ADDRESS - For vault trading

Full Configuration Example

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["--from", "mcp-hyperliquid", "hyperliquid-mcp"],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "0x1234567890abcdef...",
        "HYPERLIQUID_ACCOUNT_ADDRESS": "0xYourTradingAccountAddress...",
        "HYPERLIQUID_TESTNET": "false",
        "HYPERLIQUID_VAULT_ADDRESS": "0xVaultAddress..."
      }
    }
  }
}

Other MCP Clients

Configure according to your client's documentation, using:

• Command: uvx or python
• Args: ["--from", "mcp-hyperliquid", "hyperliquid-mcp"] or ["-m", "hyperliquid_mcp.server"]
• Environment: Add the required environment variables in your client's env configuration

Available Tools

Account & Position Management

• hyperliquid_get_account_info - Get complete account summary
• hyperliquid_get_positions - Get all open positions
• hyperliquid_get_balance - Get account balance and withdrawable amount

Order Management

• hyperliquid_place_order - Place a single order
• hyperliquid_place_bracket_order - Place entry + TP + SL atomically
• hyperliquid_cancel_order - Cancel a specific order
• hyperliquid_cancel_all_orders - Cancel all open orders
• hyperliquid_modify_order - Modify an existing order
• hyperliquid_place_twap_order - Place TWAP order (coming soon)
• hyperliquid_cancel_twap_order - Cancel TWAP order (coming soon)

Order Queries

• hyperliquid_get_open_orders - Get all open orders
• hyperliquid_get_order_status - Get status of specific order
• hyperliquid_get_user_fills - Get trade fill history
• hyperliquid_get_user_funding - Get funding payment history

Market Data

• hyperliquid_get_meta - Get exchange metadata (assets, leverage, etc.)
• hyperliquid_get_all_mids - Get current mid prices for all assets
• hyperliquid_get_order_book - Get order book depth (top depth levels per side, default 5; served from a live WebSocket mirror)
• hyperliquid_get_microstructure - Get dense edge-level signals (OBI, micro-price, spread in bps) computed server-side
• hyperliquid_get_orderflow - Get dense trade-flow signals (CVD, aggressor buy/sell volume, trade-flow imbalance) over a recent window, computed server-side
• hyperliquid_get_recent_trades - Get recent trades
• hyperliquid_get_historical_funding - Get funding rate history
• hyperliquid_get_candles - Get OHLCV candle data

Risk & Quant

• hyperliquid_run_monte_carlo - Run a vectorized GBM Monte Carlo price simulation and return an aggregated risk profile (VaR, terminal-price distribution, probability of profit), computed server-side

Vault Management

• hyperliquid_vault_details - Get vault details
• hyperliquid_vault_performance - Get vault performance metrics

Utility

• hyperliquid_get_server_time - Get server timestamp

Usage Examples

Example 1: Check Account Balance

Show me my Hyperliquid account balance

The AI will call hyperliquid_get_balance and show you:

• Account value
• Margin used
• Withdrawable amount
• Available balance

Example 2: Get Market Data

What's the current price of SOL on Hyperliquid? Show me the order book too.

The AI will:

1. Call hyperliquid_get_meta to find SOL's index
2. Call hyperliquid_get_all_mids for current price
3. Call hyperliquid_get_order_book for depth

By default hyperliquid_get_order_book returns the top 5 levels per side (pass depth for more). The book is served instantly from a live WebSocket mirror when fresh, and each response carries a source field ("websocket" or "rest") so you know how fresh it is.

Example 3: Gauge Market Pressure (Microstructure)

Is there buy or sell pressure on HYPE right now, and how tight is the spread?

The AI calls hyperliquid_get_microstructure and gets back a dense signal computed server-side (no raw book parsing needed):

{"asset":"HYPE","source":"websocket","depth":5,"OBI":0.62,"micro_price":1.452,"mid":1.451,"spread_bps":2.1}

• OBI (Order Book Imbalance) — bid share of top-depth volume; >0.5 means bids are heavier (upward pressure).
• micro_price — Stoikov fair value that reacts faster than the plain mid.
• spread_bps — bid-ask spread in basis points (tightening ≈ liquid/imminent move, widening ≈ thin).

This is far cheaper on tokens than fetching the raw order book — prefer it when you only need to read market pressure rather than inspect individual levels.

Example 4: Read Trade Flow (Order Flow / CVD)

Over the last minute, is BTC seeing net buying or selling on Hyperliquid?

The AI calls hyperliquid_get_orderflow (optionally with window_secs, default 60) and gets a dense signal computed server-side from the executed-trade tape:

{"asset":"BTC","source":"websocket","window_secs":60,"buy_vol":12.34,"sell_vol":9.87,"CVD":2.47,"TFI":0.111,"trades":143,"vwap":61234.5,"last_px":61240.0,"duration_s":59.8}

• buy_vol / sell_vol — aggressor-signed volume ("B" = buy aggressor, "A" = sell aggressor).
• CVD — cumulative volume delta over the window (buy_vol − sell_vol); positive = net buying.
• TFI — trade-flow imbalance in [-1, 1] (0 = balanced); the flow analog of OBI.
• vwap / last_px / trades / duration_s — window VWAP, last print, trade count, and actual span covered.

Where get_microstructure reads the resting book, get_orderflow reads executed flow — use them together to see both intent and action.

Example 5: Simulate Downside Risk (Monte Carlo)

If I hold BTC for the next 7 days, what's my downside risk?

The AI calls hyperliquid_run_monte_carlo (defaults: 1h candles, lookback_days=30, days_forward=7, iterations=10000). The server estimates volatility from recent candles, runs the paths through a vectorized Geometric Brownian Motion model in numpy, and returns only the aggregated risk profile:

{"asset":"BTC","interval":"1h","days_forward":7,"lookback_days":30,"drift":"zero","s0":61240.0,"steps":168,"iterations":10000,"sigma_per_step":0.0031,"mu_per_step":0.0,"mean_terminal":61230.4,"median_terminal":61180.2,"p05_terminal":56120.7,"p95_terminal":66540.9,"expected_return":-0.0002,"VaR_5pct":0.0836,"prob_profit":0.497}

• VaR_5pct — 5% Value at Risk as a positive loss magnitude (here ≈ 8.4% worst-case over the horizon at the 5th percentile).
• p05_terminal / median_terminal / p95_terminal — terminal-price percentiles bracketing the outcome distribution.
• prob_profit — share of paths ending above the current price.
• drift — "zero" by default (conservative for risk); pass use_historical_drift=true to use the historical mean return as drift.

Only the summary crosses the wire — the thousands of simulated paths never leave the server, so it stays cheap on tokens while doing the heavy compute in Python.

Example 6: Place a Bracket Order

Place a bracket order on Hyperliquid:
- Pair: SOL-USD
- Side: BUY (LONG)
- Size: 4.12 SOL (~$900)
- Entry: $218.00
- Target: $219.50 (+0.7%)
- Stop Loss: $216.80 (-0.8%)

The AI will:

1. Call hyperliquid_get_meta to get SOL's asset index (5)
2. Call hyperliquid_place_bracket_order with:

• asset: 5
• isBuy: true
• size: "4.12"
• entryPrice: "218.00"
• takeProfitPrice: "219.50"
• stopLossPrice: "216.80"

This places 3 orders atomically:

• Entry order at $218.00
• Take profit trigger at $219.50 (reduce-only)
• Stop loss trigger at $216.80 (reduce-only)

Example 7: Check Positions and Close

Show me my open positions. If I have a SOL position, close it at market price.

The AI will:

1. Call hyperliquid_get_positions
2. If SOL position exists, call hyperliquid_place_order with:

• Opposite side (sell if long, buy if short)
• Market order (price = "0")
• Reduce-only enabled

Example 8: View Recent Trading Activity

Show me my last 50 trades from the past 24 hours

The AI will:

1. Calculate timestamps (now - 24h to now)
2. Call hyperliquid_get_user_fills with time range
3. Format and display the results

Asset Index Reference

Use hyperliquid_get_meta to get the full list. Common assets:

| Index | Asset | Index | Asset | Index | Asset | | ----- | ----- | ----- | ----- | ----- | ----- | | 0 | BTC | 1 | ETH | 5 | SOL | | 10 | LTC | 11 | ARB | 14 | SUI | | 18 | LINK | 25 | XRP | 27 | APT |

Order Types

Limit Order (Good-Till-Cancel)

order_type = {"limit": {"tif": "Gtc"}}

Market Order (Immediate or Cancel)

price = "0"  # Setting price to 0 makes it a market order
order_type = {"limit": {"tif": "Ioc"}}

Trigger Order (Stop Loss / Take Profit)

order_type = {
    "trigger": {
        "triggerPx": "100.5",  # Trigger price
        "isMarket": False,      # False for limit, True for market
        "tpsl": "tp"            # "tp" for take profit, "sl" for stop loss
    }
}

Error Handling

"User or API Wallet does not exist"

Problem: Your wallet isn't registered on Hyperliquid.

Solution:

1. Go to app.hyperliquid.xyz (or testnet URL)
2. Connect your wallet
3. Deposit any amount from Arbitrum
4. This registers your wallet

"Order value must be at least $10"

Problem: Your order size is too small.

Solution: Ensure size * price >= $10

Example:

• SOL at $200: Need at least 0.05 SOL
• BTC at $50,000: Need at least 0.0002 BTC

"Invalid signature"

Problem: Private key mismatch or signing error.

Solution:

1. Check your HYPERLIQUIDPRIVATEKEY is correct
2. Ensure it matches the wallet address you registered
3. If using agent mode, verify HYPERLIQUIDACCOUNTADDRESS

Agent Mode (Advanced)

Agent mode allows an API wallet to sign transactions for a different trading account.

Use case: Keep your main account safe while allowing an API wallet to trade.

Setup:

HYPERLIQUID_PRIVATE_KEY=0xApiWalletPrivateKey...
HYPERLIQUID_ACCOUNT_ADDRESS=0xMainTradingAccountAddress...

Requirements:

1. Both wallets must be registered on Hyperliquid
2. Main account must approve the API wallet as an agent
3. Use approve_agent action through Hyperliquid UI first

Security Best Practices

1. Never commit private keys - Always use environment variables
2. Use testnet first - Test strategies before going live
3. Set up stop losses - Use bracket orders for risk management
4. Monitor positions - Regularly check your account
5. Use agent mode - For production, keep main account key offline
6. Start small - Test with minimum order sizes first

Troubleshooting

Server won't start

# Check Python version
python --version  # Should be 3.10+

# Check dependencies
uv sync

# Check environment variables
cat .env

# Run with debug logging
HYPERLIQUID_LOG_LEVEL=DEBUG uvx --from mcp-hyperliquid hyperliquid-mcp

Orders not placing

1. Check wallet is registered (see error handling)
2. Verify order size meets $10 minimum
3. Check you have sufficient balance
4. Ensure asset index is correct (use get_meta)

Can't find asset

Use the hyperliquid_get_meta tool to get all asset indices

The AI will show you the complete list of tradeable assets with their indices.

Development

Local Development

# Clone the repository
git clone https://github.com/Dakkshin/hyperliquid-mcp.git
cd hyperliquid-mcp

# Install dependencies
uv sync

# Run locally
uv run python -m hyperliquid_mcp.server

# Run tests (when available)
uv run pytest

Code Structure

hyperliquid-mcp/
├── src/
│   └── hyperliquid_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml             # Project configuration
├── README.md                  # This file
└── .env.example              # Environment template

Join Our Community

• Telegram Group - Get help, share strategies, and connect with other traders

Contributing

Contributions are welcome! Please:

1. Fork the repository

2

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dakkshin
• Source: Dakkshin/hyperliquid-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.