Hyperliquid Info MCP Server

Hyperliquid Info MCP 服务

一个 MCP 服务，可提供 Hyperliquid 永续合约 DEX 的实时数据和洞察，供机器人、仪表板和分析使用。

功能

• 用户数据查询：

  • get_user_state：获取用户在永续合约或现货市场中的持仓、保证金和可提现余额。
  • get_user_open_orders：检索用户账户的所有未成交订单。
  • get_user_trade_history：获取成交记录，包括交易对、数量和价格等详细信息。
  • get_user_funding_history：查询资金费用支付历史，并可自定义时间范围。
  • get_user_fees：获取用户专属的费用结构（挂单方／吃单方费率）。
  • get_user_staking_summary 和 get_user_staking_rewards：查看质押详情和奖励。
  • get_user_order_by_oid 和 get_user_order_by_cloid：按订单 ID 或客户端订单 ID 检索特定订单详情。
  • get_user_sub_accounts：列出与主账户关联的子账户。

• 市场数据工具：

  • get_all_mids：获取所有交易对的中间价。
  • get_l2_snapshot：获取指定币种的 Level 2 订单簿快照。
  • get_candles_snapshot：检索 K 线数据，并可自定义时间间隔和范围。
  • get_coin_funding_history：查询指定币种的资金费率历史。
  • get_perp_dexs：获取永续合约市场的元数据（使用 meta）。
  • get_perp_metadata 和 get_spot_metadata：获取永续合约和现货市场的详细元数据，并可选择包含资产上下文。

• 分析提示词：

  • analyze_positions：引导式提示词，使用相关工具分析用户的交易活动。

• ISO 8601 支持：基于时间的查询（get_candles_snapshot、get_coin_funding_history、get_user_funding_history）接受 ISO 8601 时间字符串，以便精确筛选数据。

安装

前提条件

• Python 3.10：Hyperliquid Python SDK 所需。
• 用于用户专属查询的有效 Hyperliquid 账户地址。
• 用于包管理的 uv 或 pip。

步骤

1. 克隆仓库：

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

2. 安装依赖项： 使用 uv：

   uv sync
   

用法

运行服务

使用 MCP Inspector 以开发模式运行服务：

mcp dev main.py

或安装后在 Claude Desktop 中使用：

mcp install main.py --name "Hyperliquid Info"

示例用法

使用 MCP Inspector 或 Claude Desktop，你可以通过自然语言提示词与服务交互。下面列出了一些示例，展示如何以对话方式触发 analyze_positions 提示词和各个工具。

1. 分析交易仓位：

   • 提示词：
     "请分析我的 Hyperliquid 账户（地址为 0xYourAddress）的交易活动。请提供有关我的仓位、未成交订单和近期交易的见解。"
   • 行为：
     这会触发 analyze_positions 提示词，该提示词使用 get_user_state、get_user_open_orders、get_user_trade_history、get_user_funding_history 和 get_user_fees 获取数据，并生成风险／表现分析。
   • 输出示例：

     对于账户 0xYourAddress：
     - 当前仓位：以 $50,000 做多 0.1 BTC，未实现盈亏 +$500。
     - 未成交订单：1 个限价卖单，以 $52,000 卖出 0.05 BTC。
     - 近期交易：于 2025-05-30 以 $50,000 买入 0.1 BTC。
     - 资金费用：上周支付了 $10 资金费用。
     - 手续费：Maker 费率 0.02%，Taker 费率 0.05%。
     建议：由于杠杆较高，请密切关注 BTC 价格。
     

2. 获取用户状态：

   • 提示词：
     "显示我的 Hyperliquid 账户 0xYourAddress 的当前状态，包括我的永续合约仓位和保证金详情。"
   • 行为：
     调用 get_user_state(account_address="0xYourAddress", check_spot=False)。
   • 输出示例：

     {
       "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"
     }
     

3. 获取 K 线数据：

   • 提示词：
     "你能获取 Hyperliquid 上 ETH 从 2025 年 1 月 1 日到 2025 年 1 月 2 日的 1 分钟 K 线数据吗？"
   • 行为：
     调用 get_candles_snapshot(coin_name="ETH", interval="1m", start_time="2025-01-01T00:00:00Z", end_time="2025-01-02T00:00:00Z")。
   • 输出示例：

     [
       {
         "t": 1672531200000,
         "o": "3000.0",
         "h": "3010.0",
         "l": "2995.0",
         "c": "3005.0",
         "v": "1000.0"
       },
       ...
     ]
     

4. 查看交易历史：

   • 提示词：
     "我的账户 0xYourAddress 在 Hyperliquid 上最近有哪些交易？"
   • 行为：
     调用 get_user_trade_history(account_address="0xYourAddress")。
   • 输出示例：

     [
       {
         "coin": "ETH",
         "px": "3000.0",
         "sz": "0.5",
         "time": 1672531200000,
         "tid": "123456"
       },
       ...
     ]
     

5. 获取市场元数据：

   • 提示词：
     "请介绍 Hyperliquid 上可交易的永续合约市场，包括交易对。"
   • 行为：
     调用 get_perp_metadata(include_asset_ctxs=False)。
   • 输出示例：

     {
       "universe": [
         {
           "name": "BTC-PERP",
           "maxLeverage": 50,
           "szDecimals": 4,
           "tickSz": "0.1"
         },
         ...
       ]
     }
     

许可证

本项目基于 MIT License 授权。