Hyperliquid Info MCP Server

1# Hyperliquid Info MCP Server
2 
3An MCP server that provides real-time data and insights from the Hyperliquid perp DEX for use in bots, dashboards, and analytics.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/hyperliquid-info-mcp)
6![Python Version](https://img.shields.io/badge/python-3.10+-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **User Data Queries**:
12  - `get_user_state`: Fetch user positions, margin, and withdrawable balance for perpetuals or spot markets.
13  - `get_user_open_orders`: Retrieve all open orders for a user account.
14  - `get_user_trade_history`: Get trade fill history with details like symbol, size, and price.
15  - `get_user_funding_history`: Query funding payment history with customizable time ranges.
16  - `get_user_fees`: Fetch user-specific fee structures (maker/taker rates).
17  - `get_user_staking_summary` & `get_user_staking_rewards`: Access staking details and rewards.
18  - `get_user_order_by_oid` & `get_user_order_by_cloid`: Retrieve specific order details by order ID or client order ID.
19  - `get_user_sub_accounts`: List sub-accounts associated with a main account.
20 
21- **Market Data Tools**:
22  - `get_all_mids`: Get mid prices for all trading pairs.
23  - `get_l2_snapshot`: Fetch Level 2 order book snapshots for a specific coin.
24  - `get_candles_snapshot`: Retrieve candlestick data with customizable intervals and time ranges.
25  - `get_coin_funding_history`: Query funding rate history for a specific coin.
26  - `get_perp_dexs`: Fetch metadata about perpetual markets (using `meta`).
27  - `get_perp_metadata` & `get_spot_metadata`: Get detailed metadata for perpetual and spot markets, with optional asset contexts.
28 
29- **Analysis Prompt**:
30  - `analyze_positions`: A guided prompt to analyze user trading activity using relevant tools.
31 
32- **ISO 8601 Support**: Time-based queries (`get_candles_snapshot`, `get_coin_funding_history`, `get_user_funding_history`) accept ISO 8601 time strings for precise data filtering.
33 
34## Installation
35 
36### Prerequisites
37- **Python 3.10**: Required by the Hyperliquid Python SDK.
38- A valid Hyperliquid account address for user-specific queries.
39- [uv](https://github.com/astral-sh/uv) or [pip](https://pip.pypa.io/en/stable/) for package management.
40 
41### Steps
421. **Clone the Repository**:
43   ```bash
44   git clone https://github.com/kukapay/hyperliquid-info-mcp.git
45   cd hyperliquid-info-mcp
46   ```
47 
482. **Install Dependencies**:
49   Using `uv`:
50   ```bash
51   uv sync
52   ```
53 
54## Usage
55 
56### Running the Server
57Run the server in development mode with MCP Inspector:
58```bash
59mcp dev main.py
60```
61Or install it for use in Claude Desktop:
62```bash
63mcp install main.py --name "Hyperliquid Info"
64```
65 
66### Example Usage
67 
68Using the MCP Inspector or Claude Desktop, you can interact with the server using natural language prompts. Below are examples of how to trigger the `analyze_positions` prompt and individual tools conversationally.
69 
701. **Analyze Trading Positions**:
71   - **Prompt**:  
72     "Please analyze the trading activity for my Hyperliquid account with address 0xYourAddress. Provide insights on my positions, open orders, and recent trades."
73   - **Behavior**:  
74     This triggers the `analyze_positions` prompt, which uses `get_user_state`, `get_user_open_orders`, `get_user_trade_history`, `get_user_funding_history`, and `get_user_fees` to fetch data and generate a risk/performance analysis.
75   - **Example Output**:  
76     ```
77     For account 0xYourAddress:
78     - Current Positions: 0.1 BTC long at $50,000, unrealized PNL +$500.
79     - Open Orders: 1 limit order to sell 0.05 BTC at $52,000.
80     - Recent Trades: Bought 0.1 BTC at $50,000 on 2025-05-30.
81     - Funding Payments: Paid $10 in funding fees last week.
82     - Fees: Maker fee 0.02%, taker fee 0.05%.
83     Recommendation: Monitor BTC price closely due to high leverage.
84     ```
85 
862. **Fetch User State**:
87   - **Prompt**:  
88     "Show me the current state of my Hyperliquid account 0xYourAddress, including my positions and margin details for perpetuals."
89   - **Behavior**:  
90     Invokes `get_user_state(account_address="0xYourAddress", check_spot=False)`.
91   - **Example Output**:  
92     ```
93     {
94       "assetPositions": [
95         {
96           "position": {
97             "coin": "BTC",
98             "szi": "0.1",
99             "entryPx": "50000.0",
100             "markPx": "50500.0",
101             "unrealizedPnl": "500.0"
102           }
103         }
104       ],
105       "marginSummary": {
106         "accountValue": "10000.0",
107         "totalMarginUsed": "2000.0"
108       },
109       "withdrawable": "8000.0"
110     }
111     ```
112 
1133. **Get Candlestick Data**:
114   - **Prompt**:  
115     "Can you get the 1-minute candlestick data for ETH on Hyperliquid from January 1, 2025, to January 2, 2025?"
116   - **Behavior**:  
117     Invokes `get_candles_snapshot(coin_name="ETH", interval="1m", start_time="2025-01-01T00:00:00Z", end_time="2025-01-02T00:00:00Z")`.
118   - **Example Output**:  
119     ```
120     [
121       {
122         "t": 1672531200000,
123         "o": "3000.0",
124         "h": "3010.0",
125         "l": "2995.0",
126         "c": "3005.0",
127         "v": "1000.0"
128       },
129       ...
130     ]
131     ```
132 
1334. **Check Trade History**:
134   - **Prompt**:  
135     "What are the recent trades for my account 0xYourAddress on Hyperliquid?"
136   - **Behavior**:  
137     Invokes `get_user_trade_history(account_address="0xYourAddress")`.
138   - **Example Output**:  
139     ```
140     [
141       {
142         "coin": "ETH",
143         "px": "3000.0",
144         "sz": "0.5",
145         "time": 1672531200000,
146         "tid": "123456"
147       },
148       ...
149     ]
150     ```
151 
1525. **Fetch Market Metadata**:
153   - **Prompt**:  
154     "Tell me about the perpetual markets available on Hyperliquid, including trading pairs."
155   - **Behavior**:  
156     Invokes `get_perp_metadata(include_asset_ctxs=False)`.
157   - **Example Output**:  
158     ```
159     {
160       "universe": [
161         {
162           "name": "BTC-PERP",
163           "maxLeverage": 50,
164           "szDecimals": 4,
165           "tickSz": "0.1"
166         },
167         ...
168       ]
169     }
170     ```
171 
172 
173## License
174This project is licensed under the [MIT License](LICENSE).
175 
176