hyperliquid-mcp-python copilot-instructions.md

HyperLiquid MCP Server - AI 编程指南

项目概述

这是一个模型上下文协议 (MCP) 服务器，为AI助手提供HyperLiquid交易功能。架构采用服务层模式，FastMCP处理MCP协议，专门的服务层负责HyperLiquid API交互。

核心架构：

• main.py: FastMCP服务器，包含工具定义和配置管理
• services/hyperliquid_services.py: 核心交易逻辑和HyperLiquid SDK集成
• 全局单例模式: 服务实例初始化一次，在所有工具调用中重复使用
• 异步优先: 所有工具都是异步的，尽管底层SDK是同步的

关键实现模式

配置管理

应用使用三模式配置系统：

1. 环境变量 (HYPERLIQUID_PRIVATE_KEY, HYPERLIQUID_TESTNET, HYPERLIQUID_ACCOUNT_ADDRESS)
2. .env 文件（相同变量名）
3. config.json 文件，使用snake_case键名 (private_key, testnet, account_address)

模式： 始终先检查环境变量，然后检查配置文件，最后抛出带有有用设置说明的错误。

订单大小 vs 美元价值

关键： 所有交易函数中的 size 参数代表代币数量，而非美元价值。

• ✅ 0.1 表示 0.1 个 SOL 代币
• ❌ 20.0 误认为是 $20

使用 calculate_token_amount_from_dollars() 进行转换。这是最常见的用户错误。

OCO（一取消其他）订单分组

不同场景使用不同的订单分组：

• 新仓位的止盈止损: place_bracket_order() 使用 normalTpSl 分组
• 现有仓位的止盈止损: set_position_tpsl() 使用 positionTpSl 分组
• 自定义批量订单: 重写 _bulk_orders_with_grouping() 方法设置适当分组

市场操作

• 开仓: 使用 market_open_position() → 调用 exchange.market_open()
• 平仓: 使用 market_close_position() → 激进的IOC订单，设置 reduce_only=True
• 常规交易: 使用 place_limit_order() 进行标准限价订单

服务层架构

服务初始化模式

global hyperliquid_service: Optional[HyperliquidServices] = None

def initialize_service():
    global hyperliquid_service
    if hyperliquid_service is None:
        config = get_config()
        hyperliquid_service = HyperliquidServices(
            private_key=config.private_key,
            testnet=config.testnet,
            account_address=config.account_address
        )

在工具函数中使用服务前，始终调用 initialize_service()。

自定义SDK扩展

HyperliquidServices 类扩展了官方SDK：

• 自定义批量订单: _bulk_orders_with_grouping() 正确设置OCO分组
• 仓位检测: 自动检测TP/SL订单的仓位大小和方向
• 滑点定价: _slippage_price() 用于激进市场订单
• 统一错误处理: 所有方法的一致返回格式

工具设计模式

返回格式标准化

所有工具返回：

{
    "success": bool,
    "data"/"order_result"/"bulk_result": Any,  # 成功数据
    "error": str,  # 失败时的错误描述
    # 其他上下文字段
}