内容
# HyperSignal MCP
**Hyperliquid 分析与信号的商业化 MCP 服务器。**
为 AI 代理（Claude, Cursor, ChatGPT, 自动交易代理）提供 Hyperliquid 分析，
这些分析是免费开源 MCP 服务器所不具备的 —— 鲸鱼群体信号、清算地图、资金筛选、
HIP-3 分析和现成的风险报告 —— 以及可选的本地交易层，
该层将构建者代码附加到订单上。
> ⚠️ **分析，而不是投资建议。** 交易工具下达真实订单且不可逆转。
---
## 层级与工具
### 免费（开源对等 — 钩子）
| 工具 | 返回内容 |
|---|---|
| `hl_get_markets` | 永续合约市场：标记/预言机价格、每小时和年化资金、持仓量、24 小时交易量；过滤/排序 |
| `hl_get_orderbook` | L2 订单簿（顶部 N 级别）、买卖价差、中点 |
| `hl_get_candles` | 按时间间隔/范围或回溯的 OHLCV 烛线 |
| `hl_get_funding_history` | 资金历史 + 平均/累计 |
| `hl_get_account` | 仓位、权益、保证金、清算价格，适用于任何地址 |
| `hl_get_open_orders` | 任何地址的未成交订单 |
### 高级（差异化因素 — 计量）
| 工具 | 返回内容 |
|---|---|
| `hl_whale_positions` | 按币种聚合的鲸鱼群体仓位：净多/空头、加权平均入场价格、1 小时/24 小时变化 |
| `hl_whale_flow_alerts` | 超过 USD 门槛的近期大额群体仓位变动 |
| `hl_liquidation_map` | 清算集群（按距离标记的风险敞口）、最近的连锁清算 |
| `hl_funding_screener` | 按年化资金和跨市场价差筛选的永续合约 |
| `hl_hip3_analytics` | HIP-3（构建者部署 / RWA / 权益）永续合约指标 + 外部基差 |
| `hl_portfolio_risk` | 清算距离、有效杠杆、集中度、压力情景、PnL 夏普比率 |
| `hl_vault_screener` | 按 APR、最大回撤、夏普/索提诺比率、年龄、TVL、领导者份额筛选的金库 |
| `hl_trader_report` | 钱包明细：胜率、平均 R、PnL 曲线、剥头皮/摆动风格、顶部币种 |
### 交易（可选，**本地 stdio 仅限**，构建者代码，最大警告）
| 工具 | 执行操作 |
|---|---|
| `hl_place_order` | 通过您的代理钱包附带构建者代码下达限价/市价订单 |
| `hl_cancel_order` | 按币种 + 订单 ID 取消订单 |
| `hl_close_position` | 仅减少市价平仓 |
| `hl_approve_builder_fee_guide` | **只读** — 为您的主钱包生成 `approveBuilderFee` 有效载荷/说明 |
交易默认为 **dry-run**（预览确切的签名操作而不发送）。提交需要
`HL_ENABLE_TRADING=true` + `HL_AGENT_PRIVATE_KEY`（仅环境变量）+ `confirm=true` + `dryRun=false`。
**交易工具永远不会在远程 HTTP 服务器上暴露。**
---
## 安装
### 要求
Node ≥ 20。`npm install && npm run build`。
### 本地（stdio）— 免费 + 交易，适用于 Claude Desktop / Claude Code / Cursor
Claude Desktop (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"hypersignal": {
"command": "node",
"args": ["/absolute/path/to/hypersignal-mcp/dist/server-stdio.js"],
"env": {
"HL_NETWORK": "mainnet",
"HL_BUILDER_ADDRESS": "0xYourBuilderAddress",
"HL_ENABLE_TRADING": "false"
}
}
}
}
```
Cursor（`.cursor/mcp.json`）使用相同的 `command`/`args`/`env` 格式。
本地检查：
```bash
npm run build && npm run inspect # @modelcontextprotocol/inspector
```
### 远程（可流式 HTTP）— 免费 + 高级，商业化
```bash
cp .env.example .env # 填写密钥 / 构建者 / x402
docker compose up -d # 在 :8080 上提供 POST /mcp，GET /healthz
```
将 MCP HTTP 客户端指向 `https://your-host/mcp` 并发送 `X-API-Key: <key>`（或 `Authorization: Bearer <key>`）。
> Node 内置的 `fetch` 仅在 `NODE_USE_ENV_PROXY=1` 时才支持 `HTTPS_PROXY`（Node ≥ 22.21）。
> 在出口代理后面，设置环境变量。
---
## 商业化
| 层级 | 限制 | 价格 |
|---|---|---|
| 匿名（无密钥） | 仅免费工具 | — |
| 免费密钥 | 100 次高级调用/月 | $0 |
| 专业密钥 | 无限分析 | $19/月 |
| x402 按次付费 | 按次高级调用 | $0.005–0.02 USDC on Base |
- **API 密钥** — 通过 `HYPERSIGNAL_PRO_KEYS` / `HYPERSIGNAL_FREE_KEYS`（逗号分隔的原始密钥，
存储在 SQLite 中经过哈希处理）进行配置。用法计数器按密钥、每月计算。
- **x402** — 当请求没有密钥/配额且 `X402_ENABLED=true` 时，高级工具返回需要支付的 x402 响应，
具有要求；经促进者验证和结算后，调用运行。无促进者时关闭（从不伪造支付）。
- **Apify** — `apify-actor/` 以按事件付费的 Actor 重新导出最畅销的高级工具。
---
## 🔌 构建者代码（连接我们的终端配置）
通过 HyperSignal 的构建者代码路由您的 Hyperliquid 订单以支持项目：
设置 `HL_BUILDER_ADDRESS` 和（可选）`HL_BUILDER_FEE_TENTHS_BPS`（十分之一的 bp；默认值 `5` = 0.5 bp，
Hyperliquid 永续合约上限为 10 bp）。来自您的 **主** 钱包的一次性批准：
```
hl_approve_builder_fee_guide → 为您提供确切的 approveBuilderFee 有效载荷 + 步骤
```
服务器永远不会看到您的主密钥；您自己签名批准。
---
## 架构
```
src/
core/ Hyperliquid Info 客户端，WS 中间件馈送（+REST 回退），LRU+TTL 缓存，速率限制器，重试
hl/ 类型端点，市场/账户/鲸鱼标准化，群体解析
tools/ 每个工具一个文件（Zod 输入 + outputSchema + 注解）；免费 / 高级 / 交易
billing/ SQLite 密钥 + 每月计数器，层级，x402（关闭失败）
trading/ L1 操作签名（viem + msgpack），dry-run-first 交换服务
server-core.ts 为层级集 + 计费门控构建 McpServer
server-stdio.ts 本地入口点（免费 + 交易）
server-http.ts 远程入口点（免费 + 高级， stateless JSON）
apify-actor/ 薄按事件付费包装器
evals/ 10 个只读、时间稳定的评估问题
docs/ PHASE0 研究报告，GTM 检查清单
```
强制执行设计规则：`.env` 外无密钥；交易从不远程；每个外部调用都有超时 + 3 次指数重试 + 优雅降级；
响应聚合/分页/截断；高级/交易工具带有财务免责声明；仅在第 0 阶段验证 Hyperliquid 端点。
---
## 开发
```bash
npm run dev:stdio # tsx, no build
npm run dev:http
npm run typecheck # strict, no `any`
npm test # offline unit tests (signing, stats, aggregation, cache)
npm run build
```
## License
MIT。 不属于 Hyperliquid。 自担风险使用。
