hyperliquid_marketmicro_mcp

# hlmcp — Hyperliquid 微观结构与执行 MCP [](https://pypi.org/project/hyperliquid-microstructure-mcp/) [](https://pypi.org/project/hyperliquid-microstructure-mcp/) [](LICENSE) 一个开源的 [MCP](https://modelcontextprotocol.io) 服务器，暴露 **计算市场微观结构和执行分析信号** 在 [Hyperliquid](https://hyperliquid.xyz) — 原生 HL 永续合约 *和* HIP-3 部署 — 作为工具，可以被 LLM 代理和 AI 编码助手（Claude Desktop，Cursor，Claude Code，LangGraph，…）调用。 ## 为什么存在 大多数加密货币 MCP 是 **数据访问包装器**：中间价格，蜡烛图，原生 L2 订单簿。 `hlmcp` 故意 *不是* 那样。价值在于 **计算层** — 您需要自己编写的分析： - **深度加权订单簿不平衡** 跨基准点波段，报告 *实际实现的桶宽度*，以便您知道分辨率是真实的； - **鲸鱼位置监控** 与 **账户级** 清算风险作为头条新闻（不是通常毫无意义的每仓 `liquidationPx` — 参见 [数据和限制](#数据--限制)）； - **HIP-3 部署发现**，以便跨 DEX 查询正确路由。 只读，HL-first，研究和慢循环决策级别。 ## 安装 仅需 **Python ≥ 3.12** — `venv` 和 `pip` 随它一起提供，因此无需额外安装。 Hyperliquid 公共 API 需要 **无需身份验证 / 无 API 密钥**。 从 PyPI 在虚拟环境中安装： ```bash python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install hyperliquid-microstructure-mcp which hlmcp-server # -> /…/.venv/bin/hlmcp-server ``` 这为您提供了控制台命令 **`hlmcp-server`**，它在标准输入/输出上运行 MCP 服务器。 分发版为 `hyperliquid-microstructure-mcp`；**导入** 名称为简短的 `hlmcp`。 ```bash hlmcp-server # 启动标准输入/输出 MCP 服务器（MCP 客户端与之通信） ``` > **拥有 [`uv`](https://docs.astral.sh/uv/)？** 它是一个更快的一体化替代品，替代虚拟环境和 pip：`uv add hyperliquid-microstructure-mcp`，或直接运行而无需安装：`uvx --from hyperliquid-microstructure-mcp hlmcp-server`。 不需要 — 选择 pip *或* uv。 <details> <summary>从源代码安装（用于开发）</summary> ```bash git clone git@github.com:Eugene2710/crypto_hl_marketmicro.git cd crypto_hl_marketmicro uv sync # 安装软件包 + 开发依赖到 .venv uv run hlmcp-server # 运行它 ``` 参见 [开发](#开发) 以获取测试/ lint / 类型检查门控。 </details> ## 在 Claude Desktop 中使用 编辑 `claude_desktop_config.json`（**设置 → 开发人员 → 编辑配置**），添加下面的 `hlmcp` 条目，然后 **完全退出并重新打开** Claude Desktop（⌘Q — 关闭窗口不够）以便它重新加载配置。 最简单的选项 — 无需单独安装 — 使用 [`uv`](https://docs.astral.sh/uv/) 从 PyPI 获取并在启动时运行它。 将 `command` 指向 `uv` 的**绝对路径**（Claude Desktop 使用最小的 PATH 启动，因此裸名称可能无法解析 — `which uv` 打印您的路径）： ```json { "mcpServers": { "hlmcp": { "command": "/opt/homebrew/bin/uv", "args": ["tool", "run", "--from", "hyperliquid-microstructure-mcp", "hlmcp-server"] } } } ``` 如果您已将它安装到虚拟环境中，请直接将 `command` 指向该虚拟环境的 `hlmcp-server` 二进制文件（绝对路径 `which hlmcp-server` 打印）： ```json { "mcpServers": { "hlmcp": { "command": "/绝对路径/to/.venv/bin/hlmcp-server" } } } ``` 然后询问，例如： *"BTC 的订单簿不平衡是多少？"* 或 *"显示 Hyperliquid 上的鲸鱼定位。"* 如果服务器无法启动，请检查 Claude Desktop 的日志（`~/Library/Logs/Claude/mcp-server-hlmcp.log` 在 macOS 上）。 ## 工具 三个只读工具。 每个响应都带有 `freshness` 对象（`server_time_ms`，`fetched_at_ms`，`staleness_ms`），以便模型可以推理数据年龄。 ### `order_book_imbalance` Hyperliquid 符号的深度加权订单簿不平衡。 - **输入：** `coin`（`"BTC"`，`"ETH"`，`"xyz:MSTR"` 用于 HIP-3 市场，`"@150"` 用于现货指数）；`bands_bps` — 可选的基点带半宽从中间（默认 `[10, 25, 50, 100]`）。 - **输出：** 每波段的买入/卖出规模 + 名义价值和名义加权不平衡比率（`+1` 全部买入侧 / 买入压力，`-1` 全部卖出侧，`0` 平衡）；`mid_price`；**实际达到的 `bucket_width_bps`**；水平计数；新鲜度。 - 聚合根据硬币的实际价格确定，因此低价硬币（XRP 〜$1）获得可用的分辨率。 如果 `bucket_width_bps` 超过您最严格的波段，则该波段的不平衡性不可靠 — 工具显示这一点而不是隐藏它。 ### `whale_position_monitor` 大型 Hyperliquid 交易者的仓位和 **账户级清算风险**。 - **输入：** `wallets` — 可选地址以任何常见形式；省略时，使用已知的大型交易者的 **精选集**（有文档证明，随软件包提供 — 不是推荐）；`include_hip3` — 如果 `true`，还查询每个 HIP-3 部署（较慢，完成跨 DEX 视图）；默认为 `false`。 - **输出：** 按总名义价值排序的每个钱包报告，每个报告以 **账户级缓冲**（`accountValue − crossMaintenanceMarginUsed`，有意义的跨保证金触发器）为标题，加上方向暴露聚合（多头/空头拆分，净偏差）和单个仓位。 每个钱包的 API 错误放在 `failures` 中，而不是使整个调用失败。 - 每仓的 `liquidation_px` 包括在内，但对于跨保证金账户通常是无意义的 — 仅将其视为补充。 ### `list_hip3_dexes` 列出 Hyperliquid 上的 HIP-3 永续合约部署。 - **输入：** 无。 - **输出：** 每个名为 HIP-3 部署的条目 — 路由键 `name`（可用作其他地方的 `dex` 参数），人类元数据（全名，部署者，预言机更新者，费用受益人）和市场宇宙（`n_assets`，`assets`）。 原生 HL 被排除；本目录仅包含您可以路由到的 HIP-3 部署。 - `perpDexs` 不携带服务器时间戳，因此 `freshness` 仅反映本地获取时间。 ## 良好使用 您不直接调用这些工具 — 您用普通语言询问 Claude（或其他 MCP 客户端），它选择工具并推理结构化结果。 价值在于您 **将三个工具链接到一个决策** 中，并让新鲜度和桶宽度元数据限定每个读取。 思维模型： - **`whale_position_monitor`** → 定位 *偏差* 和 *清算级联风险*。 - **`order_book_imbalance`** → 近期的 *买卖压力* 和 *执行时机*。 - **`list_hip3_dexes`** → *扩大视野* 到非原生市场，然后将 `dex` 馈送回其他两个。 示例提示： - *"BTC 在 10、25 和 50 bps 中点处的不平衡是多少 — 以及桶宽度是否足够紧密以信任 10 bps 读取？"* - *"显示精选的鲸鱼的净偏差，并标记任何账户缓冲相对于总名义价值较薄的鲸鱼。"* - *"列出 HIP-3 部署，然后在所有部署中监控精选的鲸鱼。"* （设置 `include_hip3: true`） 一个工作流程 — *"我现在应该增加对 BTC 多头吗？"* 1. **背景** — *"精选的鲸鱼是净多头还是净空头，是否有任何接近清算的风险可能触发清算级联？"* → `whale_position_monitor`。 2. **压力** — *"现在检查 BTC 订单簿在 10/25/50 bps 处的不平衡 — 触及附近是否有真正的买入支持？"* → `order_book_imbalance`。 3. **合成** — *"鉴于鲸鱼净多头但其中两个接近清算，顶部报价是买入沉重但 10 bps 桶是粗糙的，你会如何评估在此增加风险的框架？* 4. **重新检查** — *"重新运行不平衡并告诉我过时情况。"* 快照大约为 500ms+ 过时，因此在决定之前刷新并读取 `staleness_ms`。 使用提示： - **让 Claude 读取元数据。** 不平衡数字仅在 `bucket_width_bps` ≤ 您的最严格波段且 `staleness_ms` 低时才有意义。 - **将波段与意图匹配** — 严格（5–25 bps）用于执行时机，广泛（50–100 bps）用于情绪。 一次询问多个。 - **以账户缓冲为风险锚点**，而不是每仓的 `liquidation_px`（通常无意义）。 - **引入您自己的钱包** — 精选集是一个小型启动列表。 - **仅在需要完整性时使用 `include_hip3: true`** — 它会扩展到所有部署并且较慢。 ### 不适合使用的情况 - **亚秒级执行或高频交易。** 数据大约为 500ms+ 过时 REST，研究/慢循环级别 — 参见 [数据和限制](#数据--限制)。 查询并检查 `staleness_ms` 而不是信任一个快照作为实时 tick。 - **单一快照的真实来源。** 它是研究辅助工具； 在采取行动之前请予以核实。 - **订单放置或任何签名/交易。** 仅限读取设计 — 参见 [这不是什么](#这不是什么)。 ## 数据和限制 **研究 / 慢循环级别，不是高频交易。** 读取新鲜度元数据并相应地调整循环： - **REST 快照大约为 500ms 过时（中位数）** 在网络延迟之前 — HL 从刷新缓存中提供 REST，刷新频率约为两次/秒。 测量（时钟同步）：过时 p50 491ms / p90 670ms / p99 737ms；端到端数据年龄 p50 585ms / p99 988ms。 适用于分析和慢循环决策（10s+ 窗口）；**不适用于亚秒级循环或高频交易。** 亚秒级新鲜度的 WebSocket 适配器是一个路线图项目，不是 v0。 - **内置速率限制：** 场馆限制可持续 7 req/sec，突发 15，限制在 20 个并发飞行中 — 远低于 HL 的文档上限。 通过 env 变量可调（如下）；默认是安全的。 - **账户级风险，不是每仓的 `liquidationPx`。** 对于交叉保证金仓位，HL 的每仓清算价格是从整个账户快照中得出的，通常是无意义的（例如 $172 清算价格在 $2 空头仓位上），这就是为什么鲸鱼工具以账户级缓冲为标题。 ### 可选配置 无需任何配置。 所有旋钮都是可选的环境变量（也可以从 `.env` 加载 — 参见 `.env.example`），默认为 spike 导出的默认值： | 环境变量 | 默认值 | 含义 | | --- | --- | --- | | `HL_BASE_URL` | `https://api.hyperliquid.xyz/info` | HL 信息端点（只读） | | `HL_MAX_CONCURRENCY` | `20` | 最大并发请求 | | `HL_SUSTAINED_RATE_PER_SEC` | `7.0` | token-bucket 充值率（req/s） | | `HL_BURST_CAPACITY` | `15.0` | token-bucket 突发大小 | | `HL_REQUEST_TIMEOUT_S` | `4.0` | 每请求超时（s） | | `HL_DEX_CACHE_TTL_S` | `300.0` | HIP-3 发现缓存 TTL（s） | | `HL_SAMPLE_WALLETS` | *(未设置)* | 用于集成测试的逗号分隔地址 | ## 这不是什么 v0 的范围故意狭窄： - **只读。** 无订单放置，无签名，无交换端点 — 那是一个单独的适配器，具有自己的身份验证表面和威胁模型，不在此范围内。 - **不是实时馈送。** 〜500ms REST 过时；v0 中没有 WebSocket。 - **不是高频交易基础设施。** 研究和慢循环决策级别。 - **不是原始数据包装器。** 其他 MCP 已经提供原始中间价格和蜡烛图；此版本提供**计算**信号。 ## 项目布局 ``` src/hlmcp/ config.py # 环境驱动的 HLConfig + load_config（速率/并发/超时旋钮） server.py # FastMCP 应用程序：3 个 @mcp.tool 包装器 + 共享场地生命周期；main() = hlmcp-server schemas/ hl_api.py # 原始 HL API 形状（HL*-prefixed；字符串保持字符串，无计算） responses.py # 用户面向的响应模型（FreshnessMeta，*Response） venues/ hyperliquid.py # 只读 REST 适配器：token bucket + semaphore + retry，HIP-3 发现/缓存 errors.py # HLAPIError analytics/ # PURE 函数 — 无 I/O，无异步 aggregation.py # choose_aggregation：价格感知 l2Book 桶大小 imbalance.py # 计算 bp 波段之间的不平衡 positions.py # 仓位聚合 + 账户级清算缓冲 utils.py # 规范化钱包，十进制/解析辅助函数 tools/ # 每个文件一个 MCP 工具（薄：场地 -> 分析 -> 响应） order_book_imbalance.py # 深度加权订单簿不平衡 whale_position_monitor.py # 鲸鱼仓位 + 账户风险（加载精选集） list_hip3_dexes.py # HIP-3 部署目录 data/ curated_whales.json # 默认鲸鱼集（有文档证明）；随软件包提供 evals/ # 评估框架：datasets/*.jsonl + run_evals.py（验证格式；评级发布后 v0） tests/ # unit/（纯，模拟）· venue/（respx-模拟 HTTP）· integration/（实时 HL）· fixtures/（记录的响应） docs/ # architecture.md · api_spike_findings.md data_exploration/ # 预构建 API 峰值脚本（仅供参考，不导入） ``` 严格分层，依赖关系单向流动：`schemas/` → `venues/` → `analytics/` → `tools/` → `server.py`。 参见 [`docs/architecture.md`](docs/architecture.md) 获取设计，[`docs/api_spike_findings.md`](docs/api_spike_findings.md) 获取经验 API 约束。 ## 开发 ```bash uv sync # 安装开发依赖 uv run ruff check . # lint（必须干净） uv run mypy --strict src/ # 类型检查（必须干净） uv run pytest -m "not integration" # 单元 + 模拟测试 uv run pytest -m integration # 可选：击中实时 HL API uv run python evals/run_evals.py # 验证评估数据集 ``` ## 许可证 [MIT](LICENSE) © eugeneleejunping。