hyperliquid-info-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hyperliquid-info-mcp show my current positions and margin for account 0xabc123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hyperliquid Info MCP Server
An MCP server that provides real-time data and insights from the Hyperliquid perp DEX for use in bots, dashboards, and analytics.
Features
User Data Queries:
get_user_state: Fetch user positions, margin, and withdrawable balance for perpetuals or spot markets.get_user_open_orders: Retrieve all open orders for a user account.get_user_trade_history: Get trade fill history with details like symbol, size, and price.get_user_funding_history: Query funding payment history with customizable time ranges.get_user_fees: Fetch user-specific fee structures (maker/taker rates).get_user_staking_summary&get_user_staking_rewards: Access staking details and rewards.get_user_order_by_oid&get_user_order_by_cloid: Retrieve specific order details by order ID or client order ID.get_user_sub_accounts: List sub-accounts associated with a main account.
Market Data Tools:
get_all_mids: Get mid prices for all trading pairs.get_l2_snapshot: Fetch Level 2 order book snapshots for a specific coin.get_candles_snapshot: Retrieve candlestick data with customizable intervals and time ranges.get_coin_funding_history: Query funding rate history for a specific coin.get_perp_dexs: Fetch metadata about perpetual markets (usingmeta).get_perp_metadata&get_spot_metadata: Get detailed metadata for perpetual and spot markets, with optional asset contexts.
Analysis Prompt:
analyze_positions: A guided prompt to analyze user trading activity using relevant tools.
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.
Related MCP server: hyperliquid-whalealert-mcp
Installation
Prerequisites
Python 3.10: Required by the Hyperliquid Python SDK.
A valid Hyperliquid account address for user-specific queries.
Steps
Clone the Repository:
git clone https://github.com/kukapay/hyperliquid-info-mcp.git cd hyperliquid-info-mcpInstall Dependencies: Using
uv:uv sync
Usage
Running the Server
Run the server in development mode with MCP Inspector:
mcp dev main.pyOr install it for use in Claude Desktop:
mcp install main.py --name "Hyperliquid Info"Example Usage
Using 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.
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:
This triggers theanalyze_positionsprompt, which usesget_user_state,get_user_open_orders,get_user_trade_history,get_user_funding_history, andget_user_feesto fetch data and generate a 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.
Fetch User State:
Prompt:
"Show me the current state of my Hyperliquid account 0xYourAddress, including my positions and margin details for perpetuals."Behavior:
Invokesget_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:
Invokesget_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" }, ... ]
Check Trade History:
Prompt:
"What are the recent trades for my account 0xYourAddress on Hyperliquid?"Behavior:
Invokesget_user_trade_history(account_address="0xYourAddress").Example Output:
[ { "coin": "ETH", "px": "3000.0", "sz": "0.5", "time": 1672531200000, "tid": "123456" }, ... ]
Fetch Market Metadata:
Prompt:
"Tell me about the perpetual markets available on Hyperliquid, including trading pairs."Behavior:
Invokesget_perp_metadata(include_asset_ctxs=False).Example Output:
{ "universe": [ { "name": "BTC-PERP", "maxLeverage": 50, "szDecimals": 4, "tickSz": "0.1" }, ... ] }
License
This project is licensed under the MIT License.
Available Tools
17 toolsget_all_midsA
Retrieve the mid prices for all trading pairs available on the exchange.
Parameters:
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a dictionary of trading pairs and their mid prices.
Returns a JSON string with an error message if the query fails.
Inputs: no named parameters.
get_candles_snapshotB
Fetch the candlestick data snapshot for a specific coin.
Parameters:
coin_name (str): The trading symbol (e.g., 'BTC', 'ETH').
interval (str): The candlestick interval (e.g., '1m', '5m', '1h').
start_time (str): The start time for the candles in ISO 8601 format (e.g., '2025-01-01T00:00:00Z').
end_time (str): The end time for the candles in ISO 8601 format (e.g., '2025-12-31T23:59:59Z').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of candlestick data, each with open, high, low, close, volume, and timestamp.
Returns a JSON string with an error message if the query fails.
Inputs: coin_name (required), interval (required), start_time (required), end_time (required).
get_coin_funding_historyA
Fetch the funding rate history for a specific coin.
Parameters:
coin_name (str): The trading symbol (e.g., 'BTC', 'ETH').
start_time (str): The start time for the funding history in ISO 8601 format (e.g., '2025-01-01T00:00:00Z').
end_time (str): The end time for the funding history in ISO 8601 format (e.g., '2025-12-31T23:59:59Z').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of funding rate records, each with details such as funding rate and timestamp.
Returns a JSON string with an error message if the query fails.
Inputs: coin_name (required), start_time (required), end_time (required).
get_l2_snapshotA
Fetch the Level 2 order book snapshot for a specific coin.
Parameters:
coin_name (str): The trading symbol (e.g., 'BTC', 'ETH').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the Level 2 order book snapshot, including bids and asks with prices and sizes.
Returns a JSON string with an error message if the query fails.
Inputs: coin_name (required).
get_perp_dexsA
Retrieve metadata about perpetual markets available on the Hyperliquid decentralized exchange.
Parameters:
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing metadata about perpetual markets, including a list of trading pairs and their
contract details (e.g., symbol, tick size, contract type). Returns a JSON string with an error message if
the query fails.
Inputs: no named parameters.
get_perp_metadataA
Fetch metadata about perpetual markets on the Hyperliquid exchange.
Parameters:
include_asset_ctxs (bool, optional): If True, includes asset contexts with metadata. Defaults to False.
ctx (Context, optional): The MCP context object for accessing server state.
Returns:
str: A JSON string containing metadata about perpetual markets, including trading pairs and contract details
(e.g., symbol, tick size). Returns a JSON string with an error message if the query fails.
Inputs: include_asset_ctxs.
get_spot_metadataB
Fetch metadata about spot markets on the Hyperliquid exchange.
Parameters:
include_asset_ctxs (bool, optional): If True, includes asset contexts with metadata. Defaults to False.
ctx (Context, optional): The MCP context object for accessing server state.
Returns:
str: A JSON string containing metadata about spot markets, including trading pairs and contract details
(e.g., symbol, tick size). Returns a JSON string with an error message if the query fails.
Inputs: include_asset_ctxs.
get_user_feesA
Fetch the fee structure and rates for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the user's fee structure, including maker and taker fees.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
get_user_funding_historyA
Fetch the funding payment history for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
start_time (str): The start time for the funding history in ISO 8601 format (e.g., '2025-01-01T00:00:00Z').
end_time (str): The end time for the funding history in ISO 8601 format (e.g., '2025-12-31T23:59:59Z').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of funding payment records, each with details such as amount and timestamp.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required), start_time (required), end_time (required).
get_user_open_ordersA
Fetch all open orders for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of open orders, each with details such as order ID, symbol, size, price,
and status. Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
get_user_order_by_cloidA
Fetch details of a specific order by its client order ID for a user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
cloid (str): The client order ID to query.
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the order details, including symbol, size, price, and status.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required), cloid (required).
get_user_order_by_oidA
Fetch details of a specific order by its order ID for a user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
oid (int): The order ID to query.
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the order details, including symbol, size, price, and status.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required), oid (required).
get_user_staking_rewardsA
Fetch the staking rewards history for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of staking reward records, each with amount and timestamp.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
get_user_staking_summaryB
Fetch the staking summary for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the staking summary, including staked amounts and status.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
get_user_stateA
Query user state including trading positions, margin, and withdrawable balance.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
check_spot (bool, optional): If True, queries spot user state; otherwise, queries perpetuals state. Defaults to False.
ctx (Context, optional): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the user state, including a list of positions (with symbol, size, entry_price,
current_price, unrealized_pnl), margin_summary, and withdrawable balance. Returns a JSON string with an
error message if the query fails.
Inputs: account_address (required), check_spot.
get_user_sub_accountsB
Fetch the sub-accounts associated with a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of sub-accounts and their details.
Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
get_user_trade_historyA
Fetch the trade fill history for a specific user account.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
ctx (Context): The MCP context object for accessing server state.
Returns:
str: A JSON string containing a list of trade fills, each with details such as symbol, size, price, timestamp,
and trade ID. Returns a JSON string with an error message if the query fails.
Inputs: account_address (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have clearly distinct purposes targeting specific data types (market data, user data, metadata), but there is some overlap between get_perp_dexs and get_perp_metadata which both retrieve perpetual market metadata. The descriptions help differentiate them slightly (one mentions 'decentralized exchange' context), but an agent might still be confused about which to use for general perpetual metadata queries.
All 17 tools follow a consistent 'get_' prefix with snake_case naming, creating a predictable verb_noun pattern (e.g., get_user_state, get_l2_snapshot). The naming convention is uniform throughout, making it easy to understand the tool's purpose at a glance.
With 17 tools, the count is slightly high but reasonable for a comprehensive cryptocurrency exchange data server. The tools cover market data, user data, and metadata across multiple domains (spot, perpetuals, staking), so most tools earn their place, though some consolidation might improve efficiency.
The toolset provides excellent read-only coverage for market data (prices, candles, order books, funding) and user account information (orders, trades, state, staking, fees). The main gap is the lack of write/action tools (e.g., place_order, cancel_order), but as an 'info' server this is understandable and agents can work around it by knowing this is a query-only interface.
Related MCP Connectors
Hyperliquid MCP — read-only market data from Hyperliquid's public info API.
Unlock the power of real-time cryptocurrency data with our Crypto Price Insights MCP server.
23-in-1 MCP server: EVM tx simulator, funding rate arb, macro radar, swap calldata & security.
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server implementation that integrates with Hyperliquid exchange, providing access to crypto market data including mid prices, historical candles, and L2 order books.344MIT
- AlicenseBqualityDmaintenanceAn MCP server that provides real-time whale alerts on Hyperliquid.113MIT
- AlicenseBqualityBmaintenanceMCP server for querying historical and real-time crypto market data across Hyperliquid, Hyperliquid HIP-3, and Lighter.xyz - orderbooks, trades, candles, funding, open interest, liquidations, and data quality metrics.10064 npm13MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for Hyperliquid perpetual DEX with 48 tools for trading, monitoring, risk management, and security. Enables real-time market data, order management, risk validation, and automated trading strategies.-