Hyperliquid MCP Server

使用官方Python SDK的Hyperliquid永续交易Model Context Protocol (MCP)服务器。此服务器为AI助手提供了安全可靠的访问Hyperliquid交易平台的方式。

功能

✅ 官方SDK - 基于官方Hyperliquid Python SDK并进行适当签名
✅ 全面覆盖 - 所有交易端点：订单、仓位、市场数据、金库
✅ 安全 - 正确的EIP-712签名，并支持代理模式
✅ 套单 - 原子下单+止盈+止损
✅ 市场数据 - 实时价格、订单簿、资金费率、蜡烛图
✅ 账户管理 - 仓位、余额、成交记录、资金历史
✅ 测试网支持 - 在上线前安全地测试策略

预备条件

• Python 3.10或更高版本
• uv 或 uvx 用于包管理
• 已存入资金的Hyperliquid账户

安装

使用uvx（推荐）

# 直接从PyPI安装并运行
uvx --from mcp-hyperliquid hyperliquid-mcp

使用pip

# 使用pip安装
pip install mcp-hyperliquid

# 运行
mcp-hyperliquid

本地开发

# 克隆并从源代码安装
git clone https://github.com/edkdev/hyperliquid-mcp.git
cd hyperliquid-mcp
uv sync

# 本地运行
uv run python -m hyperliquid_mcp.server

本地开发配置

如果你是从源代码本地运行，请使用以下配置：

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

请将/path/to/hyperliquid-mcp替换为你克隆的仓库的实际路径。

配置

1. 在Hyperliquid上注册你的钱包

重要提示： 在交易之前，必须在Hyperliquid上注册你的钱包。

主网：

1. 访问 https://app.hyperliquid.xyz
2. 连接你的钱包
3. 从Arbitrum One存入资金（任何金额都可以注册你的钱包）

测试网：

1. 访问 https://app.hyperliquid-testnet.xyz
2. 连接你的钱包
3. 从水龙头或桥接获取测试网资金

2. 配置你的MCP客户端

环境变量现在可以直接配置在你的MCP客户端设置中（不需要.env文件）。

Claude Desktop / Kiro

添加到你的mcp.json配置文件中：

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

必需的环境变量：

• HYPERLIQUID_PRIVATE_KEY - 用于签名交易的钱包私钥

可选的环境变量：

• HYPERLIQUID_ACCOUNT_ADDRESS - 对于代理/API钱包模式（高级）
• HYPERLIQUID_TESTNET - 设置为“true”以使用测试网，“false”或省略以使用主网
• HYPERLIQUID_VAULT_ADDRESS - 用于金库交易

完整配置示例

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

其他MCP客户端

根据你的客户端文档进行配置，使用：

• 命令： uvx 或 python
• 参数： ["--from", "mcp-hyperliquid", "hyperliquid-mcp"] 或 ["-m", "hyperliquid_mcp.server"]
• 环境： 在你的客户端环境配置中添加所需的环境变量

可用工具

账户与仓位管理

• hyperliquid_get_account_info - 获取完整的账户概要
• hyperliquid_get_positions - 获取所有开放仓位
• hyperliquid_get_balance - 获取账户余额及可提金额

订单管理

• hyperliquid_place_order - 下单
• hyperliquid_place_bracket_order - 原子下单+止盈+止损
• hyperliquid_cancel_order - 取消特定订单
• hyperliquid_cancel_all_orders - 取消所有开放订单
• hyperliquid_modify_order - 修改现有订单
• hyperliquid_place_twap_order - 下TWAP订单（即将推出）
• hyperliquid_cancel_twap_order - 取消TWAP订单（即将推出）

订单查询

• hyperliquid_get_open_orders - 获取所有开放订单
• hyperliquid_get_order_status - 获取特定订单状态
• hyperliquid_get_user_fills - 获取成交历史
• hyperliquid_get_user_funding - 获取资金支付历史

市场数据

• hyperliquid_get_meta - 获取交易所元数据（资产、杠杆等）
• hyperliquid_get_all_mids - 获取所有资产的当前中间价
• hyperliquid_get_order_book - 获取订单簿深度
• hyperliquid_get_recent_trades - 获取最近的交易
• hyperliquid_get_historical_funding - 获取资金费率历史
• hyperliquid_get_candles - 获取OHLCV蜡烛图数据

金库管理

• hyperliquid_vault_details - 获取金库详情
• hyperliquid_vault_performance - 获取金库表现指标

实用工具

• hyperliquid_get_server_time - 获取服务器时间戳

使用示例

示例1：检查账户余额

显示我的Hyperliquid账户余额

AI将调用hyperliquid_get_balance并展示：

• 账户价值
• 已用保证金
• 可提金额
• 可用余额

示例2：获取市场数据

Hyperliquid上的SOL当前价格是多少？也显示订单簿。

AI将：

1. 调用hyperliquid_get_meta找到SOL的索引
2. 调用hyperliquid_get_all_mids获取当前价格
3. 调用hyperliquid_get_order_book获取深度

示例3：下套单

在Hyperliquid上下套单：
- 交易对：SOL-USD
- 方向：买入（多头）
- 数量：4.12 SOL（约900美元）
- 入市价：218.00美元
- 止盈价：219.50美元（+0.7%）
- 止损价：216.80美元（-0.8%）

AI将：

1. 调用hyperliquid_get_meta获取SOL的资产索引（5）
2. 调用hyperliquid_place_bracket_order：
   • 资产：5
   • 是否买入：true
   • 数量：“4.12”
   • 入市价：“218.00”
   • 止盈价：“219.50”
   • 止损价：“216.80”

这将原子性地下三个订单：

• 入市订单在218.00美元
• 止盈触发在219.50美元（减少型）
• 止损触发在216.80美元（减少型）

示例4：查看仓位并平仓

显示我所有的开放仓位。如果有SOL仓位，按市场价格平仓。

AI将：

1. 调用hyperliquid_get_positions
2. 如果存在SOL仓位，调用hyperliquid_place_order：
   • 反方向（如果是多头则卖出，如果是空头则买入）
   • 市场订单（价格 = “0”）
   • 启用减少型

示例5：查看最近的交易活动

显示过去24小时内最后50笔交易

AI将：

1. 计算时间戳（现在 - 24小时到现在）
2. 调用hyperliquid_get_user_fills带时间范围
3. 格式化并显示结果

资产索引参考

使用hyperliquid_get_meta获取完整列表。常见资产：

索引	资产	索引	资产	索引	资产
0	BTC	1	ETH	5	SOL
10	LTC	11	ARB	14	SUI
18	LINK	25	XRP	27	APT

订单类型

限价订单（有效至取消）

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

市场订单（立即或取消）

price = "0"  # 将价格设为0表示市场订单
order_type = {"limit": {"tif": "Ioc"}}

触发订单（止损/止盈）

order_type = {
    "trigger": {
        "triggerPx": "100.5",  # 触发价格
        "isMarket": False,      # false表示限价，true表示市价
        "tpsl": "tp"            # "tp"表示止盈，"sl"表示止损
    }
}

错误处理

"用户或API钱包不存在"

问题： 你的钱包未在Hyperliquid上注册。

解决方案：

1. 访问app.hyperliquid.xyz（或测试网URL）
2. 连接你的钱包
3. 从Arbitrum存入任意金额
4. 这将注册你的钱包

"订单价值必须至少10美元"

问题： 你的订单数量太小。

解决方案： 确保数量 * 价格 >= 10美元

示例：

• SOL在200美元时：需要至少0.05 SOL
• BTC在50,000美元时：需要至少0.0002 BTC

"无效签名"

问题： 私钥不匹配或签名错误。

解决方案：

1. 检查你的HYPERLIQUID_PRIVATE_KEY是否正确
2. 确保它与你注册的钱包地址匹配
3. 如果使用代理模式，验证HYPERLIQUID_ACCOUNT_ADDRESS

代理模式（高级）

代理模式允许一个API钱包为不同的交易账户签署交易。

应用场景： 保持主账户安全，同时允许API钱包进行交易。

设置：

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

要求：

1. 两个钱包都必须在Hyperliquid上注册
2. 主账户必须批准API钱包作为代理
3. 首先通过Hyperliquid UI执行approve_agent操作

安全最佳实践

1. 永远不要提交私钥 - 总是使用环境变量
2. 先使用测试网 - 在上线前测试策略
3. 设置止损 - 使用套单进行风险管理
4. 监控仓位 - 定期检查你的账户
5. 使用代理模式 - 生产环境中，将主账户密钥离线保存
6. 从小开始 - 首先测试最小订单规模

故障排除

服务器无法启动

# 检查Python版本
python --version  # 应该是3.10+

# 检查依赖项
uv sync

# 检查环境变量
cat .env

# 使用调试日志运行
HYPERLIQUID_LOG_LEVEL=DEBUG uvx --from mcp-hyperliquid hyperliquid-mcp

订单无法下单

1. 检查钱包是否已注册（参见错误处理）
2. 确认订单数量满足10美元最低要求
3. 确认你有足够的余额
4. 确保资产索引正确（使用get_meta）

无法找到资产

使用hyperliquid_get_meta工具获取所有资产索引

AI将展示所有可交易资产及其索引的完整列表。

开发

本地开发

# 克隆仓库
git clone https://github.com/edkdev/hyperliquid-mcp.git
cd hyperliquid-mcp

# 安装依赖项
uv sync

# 本地运行
uv run python -m hyperliquid_mcp.server

# 运行测试（当可用时）
uv run pytest

代码结构

hyperliquid-mcp/
├── src/
│   └── hyperliquid_mcp/
│       ├── __init__.py
│       └── server.py          # 主MCP服务器实现
├── pyproject.toml             # 项目配置
├── README.md                  # 本文件
└── .env.example              # 环境模板

加入我们的社区

• Telegram群组 - 获取帮助，分享策略，与其他交易者连接

贡献

欢迎贡献！请：

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

许可证

MIT许可证 - 详见LICENSE文件

资源

• Hyperliquid官方文档
• Hyperliquid Python SDK
• 模型上下文协议
• MCP服务器仓库

支持

• 问题： 在GitHub上打开一个问题
• Hyperliquid支持： https://hyperliquid.gitbook.io/hyperliquid-docs/help/support
• MCP文档： https://modelcontextprotocol.io/

免责声明

本软件按原样提供，不附带任何担保。加密货币交易具有重大风险。仅应使用你能承受损失的资金进行交易。作者不对任何交易损失负责。

---

愉快交易！🚀