hyperliquid-info-mcp is an MCP (Model Context Protocol) server designed to provide real-time data and insights from the Hyperliquid perpetual contract decentralized exchange (perp DEX), for use by bots, dashboards, and analytics tools.

Main Capabilities

User Data Queries

get_user_state: Retrieves a user's positions, margin, and withdrawable balance in the perpetual or spot markets.
get_user_open_orders: Retrieves all open orders for a user account.
get_user_trade_history: Retrieves trade history, including details such as trading pair, quantity, and price.
get_user_funding_history: Queries funding payment history, with support for custom time ranges.
get_user_fees: Retrieves a user's specific fee structure (maker/taker fees).
get_user_staking_summary and get_user_staking_rewards: Access staking details and rewards.
get_user_order_by_oid and get_user_order_by_cloid: Retrieves specific order details by order ID or client order ID.
get_user_sub_accounts: Lists sub-accounts associated with the main account.

Market Data Tools

get_all_mids: Retrieves the mid prices of all trading pairs.
get_l2_snapshot: Retrieves a Level 2 order book snapshot for a specific coin.
get_candles_snapshot: Retrieves candlestick data with customizable intervals and time ranges.
get_coin_funding_history: Queries the funding rate history for a specific coin.
get_perp_dexs: Retrieves perpetual market metadata (using meta).
get_perp_metadata and get_spot_metadata: Retrieves detailed metadata for the perpetual and spot markets, with optional asset context.

Analytical Prompts

analyze_positions: A guided prompt that uses relevant tools to analyze a user's trading activity.

Other Features

ISO 8601 support: Time-based queriesies (get_candles_snapshot, get_coin_funding_history, get_user_funding_history) accept ISO 8601 time strings for precise data filtering.

Usage

Environment Requirements

Python 3.10 (required by the Hyperliquid Python SDK).
A valid Hyperliquid account address for user-specific queries.
uv or pip for package management.

Installation

Clone the repository: git clone https://github.com/kukapay/hyperliquid-info-mcp.git cd hyperliquid-info-mcp

Install dependencies: Using uv: uv sync

Running the Server

Run the server in development mode using MCP Inspector, or install it into Claude Desktop for use.

Interaction Examples

Using MCP Inspector or Claude Desktop, you can interact with the server through natural language prompts. The following examples show how to trigger the analyze_positions prompt and various tools conversationally.

Analyze trading positions: Prompt: "Please analyze the trading activity for my Hyperliquid account with address 0xYourAddress. Provide insights on my positions, open orders, and recent trades." Behavior: Triggers the analyze_positions prompt, using get_user_state, get_user_open_orders, get_user_trade_history, get_user_funding_history, and get_user_fees to retrieve data and generate risk/performance analysis. Example output: For account 0xYourAddress:

Current Positions: 0.1 BTC long at $50,000, unrealized PNL +$500.
Open Orders: 1 limit order to sell 0.05 BTC at $52,000.
Recent Trades: Bought 0.1 BTC at $50,000 on 2025-05-30.
Funding Payments: Paid $10 in funding fees last week.
Fees: Maker fee 0.02%, taker fee 0.05%. Recommendation: Monitor BTC price closely due to high leverage.

Get user state: Prompt: "Show me the current state of my Hyperliquid account 0xYourAddress, including my positions and margin details for perpetuals." Behavior: call get_user_state(account_address="0xYourAddress", check_spot=False). Example output: { "assetPositions": [ { "position": { "coin": "BTC", "szi": "0.1", "entryPx": "50000.0", "markPx": "50500.0", "unrealizedPnl": "500.0" } } ], "marginSummary": { "accountValue": "10000.0", "totalMarginUsed": "2000.0" }, "withdrawable": "8000.0" }

Get candlestick data: Prompt: "Can you get the 1-minute candlestick data for ETH on Hyperliquid from January 1, 2025, to January 2, 2025?" Behavior: call get_candles_snapshot(coin_name="ETH", interval="1m", start_time="2025-01-01T00:00:00Z", end_time="2025-01-02T00:00:00Z"). Example output: [ { "t": 1672531200000, "o": "3000.0", "h": "3010.0", "l": "2995.0", "c": "3005.0", "v": "1000.0" }, ... ]

View trade history: Prompt: "What are the recent trades for my account 0xYourAddress on Hyperliquid?" Behavior: call get_user_trade_history(account_address="0xYourAddress"). Example output: [ { "coin": "ETH", "px": "3000.0", "sz": "0.5", "time": 1672531200000, "tid": "123456" }, ... ]

Get market metadata: Prompt: "Tell me about the perpetual markets available on Hyperliquid, including trading pairs." Behavior: call get_perp_metadata(include_asset_ctxs=False). Example output: { "universe": [ { "name": "BTC-PERP", "maxLeverage": 50, "szDecimals": 4, "tickSz": "0.1" }, ... ] }

Applicable Scenarios

Trading bots: obtain real-time market data and user account status for automated trading strategies.
Dashboards: display data such as user positions, orders, trade history, and funding rates.
Analysis tools: use the analyze_positions prompt for risk and performance analysis.

Limitations

Requires a Python 3.10 environment.
User-specific queries require a valid Hyperliquid account address.
The project uses the MIT License.
Other features, fees, prices, platforms, or effects not mentioned in the materials are not currently provided.

hyperliquid-info-mcp

About this tool