HyperSignal MCP

HyperSignal MCP

面向 Hyperliquid 分析与信号的收费 MCP 服务。 为 AI Agent（Claude、Cursor、ChatGPT、自主交易 Agent）提供免费开源 MCP 服务所不具备的 Hyperliquid 分析功能——巨鲸群体信号、清算地图、资金费率筛选、HIP-3 分析和现成的风险报告——还提供可选的本地交易层，可为订单附加 builder code。

⚠️ 仅供分析，不构成投资建议。 交易工具会下达真实订单，且不可撤销。

---

套餐与工具

免费版（与开源版功能相当——引导入口）

工具	返回内容
hl_get_markets	永续合约市场：标记价／预言机价格、每小时及年化资金费率、OI、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	超过美元阈值的近期大型群体持仓变动
hl_liquidation_map	清算集群（按距离标记价统计风险名义金额）、最近的连锁清算
hl_funding_screener	筛选所有永续合约的年化资金费率及跨平台价差
hl_hip3_analytics	HIP-3（builder 部署／RWA／股票）永续合约指标及外部基差
hl_portfolio_risk	清算距离、有效杠杆、集中度、压力情景、PnL 夏普比率
hl_vault_screener	按 APR、最大回撤、夏普／索提诺比率、存续时间、TVL、领投者占比筛选金库
hl_trader_report	钱包分析：胜率、平均 R 值、PnL 曲线、剥头皮／波段风格、主要交易币种

Agent 原生（v0.3）——差异化功能

工具	层级	功能
hl_create_alert / hl_list_alerts / hl_delete_alert	高级	注册/管理持续性警报（资金费率阈值、价格变动、巨鲸净头寸反转）。服务会按计划评估警报——它会替你的 Agent 监控市场。
hl_poll_alerts	高级	获取自上次轮询以来触发的警报事件（至少投递一次），每条事件都附带已签名的信号载荷。
hl_signal_track_record	高级	透明、可验证的表现数据，展示已发出信号的命中率，以及按信号类型统计的平均/中位数方向调整后前向收益。
hl_request_free_key	免费	自助申请 API 密钥——调用一次，无需注册，即可获得每月 100 次高级工具调用。通过 X-API-Key 发送。对于任何新 Agent，这都是推荐的首次调用：高级工具需要密钥时，会按名称提示使用它。
hl_buy_pro	付费（$29，x402）	通过 x402（Base 上的 USDC）购买 30 天 Pro：获取新密钥，或续订 X-API-Key 中的密钥（免费密钥会直接升级）。仅限远程服务。
hl_signal_pubkey	免费	Ed25519 公钥，可独立验证任何信号的真实性和时间戳。
hl_admin_stats	免费（独立门控）	仅供运营者使用——需要提供与 HYPERSIGNAL_ADMIN_SECRET 匹配的 adminSecret。查看本计费周期内各密钥的用量、热门工具、活跃警报、信号记录和 x402 支付次数。
hl_smart_money_score	高级	按聪明钱筛选评分（经风险调整的表现 + 胜率 + 奖励/风险比 + 仓位规模 + 活跃度）为一组钱包排名，并提供行为标签（巨鲸、高手、剥头皮交易者、类似做市商、高确信度等）。这是基于过往结果的描述性筛选器——将其视为预测之前，请先查看 hl_score_calibration。
hl_score_calibration	免费	聪明钱评分的样本外证据：评分与每个钱包后来实现的前向收益之间的 Spearman 秩相关性（采样时以账户价值为基准的前向 PnL）、p 值，以及各评分四分位的平均前向收益。特意免费提供——在为预测能力付费之前，你应该能够核查相关声明。服务每天会为自己的钱包组评分，因此无论是否有人调用付费工具，这些数据都会不断补充。
hl_coordination_scan	高级	查找持有近乎相同敞口的钱包（余弦相似度）——它们可能属于同一实体/跟单机器人/协同行动群体；返回聚类结果和相似度最高的钱包对。
hl_polymarket_divergence	高级	对比 Polymarket 的价格阈值赔率与 Hyperliquid 价格和已实现波动率所隐含的概率——这是一种其他 MCP 均未提供的跨市场错误定价优势。此外，它还会审计市场自身的价格阶梯，查找逻辑上不可能的排序（更远的阈值定价高于更近的阈值），合并重复的合约列表，报告各项估算的波动率敏感性范围，并标记扩散模型无法捕捉跳跃风险的极端尾部。

每条发出的信号都经过加密签名，并根据前向价格进行评分——其记录无法通过选择性展示来粉饰。持久化数据（警报、仓位快照、信号）由 SQLite 支持，服务重启后仍会保留。

**公开证明，无需密钥：**托管服务会运行自己的持续性警报（按未平仓量排名前 10 的永续合约中的极端资金费率，以及 BTC/ETH 巨鲸群体的仓位反转），并在 /track-record 上发布这些警报的记录、评分校准数据和签名密钥（JSON）。MCP 客户端也可以通过资源（hypersignal://about、://track-record、://calibration、://signal-pubkey）获取相同数据，此外还有三个提示词：whale_briefing、wallet_risk_check、funding_carry_scan。

交易（可选，仅限本地 stdio，使用 builder code，警告最多）

工具	功能
hl_place_order	通过你的 Agent 钱包下限价单/市价单，并附加 builder code
hl_cancel_order	按币种 + 订单 ID 取消订单
hl_close_position	以仅减仓市价单平仓
hl_approve_builder_fee_guide	只读 — 为你的主钱包生成 approveBuilderFee 载荷/说明
hl_twap_order	将仓位拆分为间隔均匀的子订单（TWAP）以尽量减小冲击，每个子订单都附加 builder code
hl_copy_wallet	按你的资产比例跟随目标钱包的仓位（跟单交易），并附加 builder code
hl_execution_status	查看正在运行的 TWAP/执行计划的进度
hl_cancel_execution	停止正在运行的计划；尚未执行的切片将被丢弃。连续 3 个切片失败后，计划也会自动停止

交易默认采用模拟运行模式（预览将要签名的确切操作，但不发送）。提交操作需要设置 HL_ENABLE_TRADING=true + HL_AGENT_PRIVATE_KEY（仅限环境变量）+ confirm=true + dryRun=false。 每笔非仅减仓订单（包括每个 TWAP 切片和跟单交易分单）的上限为 HL_MAX_ORDER_NOTIONAL_USD（默认 $10,000），且只有运营者可以提高此上限。 HIP-3 币种（xyz:XYZ100）在其 builder dex 上交易，该交易所使用独立的抵押品（启用统一账户或向其转入抵押品），且可能收取更高手续费。实时 HIP-3 订单还需要 HL_ENABLE_HIP3_TRADING=true：请在 testnet 上运行测试后再启用。 跟单交易仅跟随主 dex 的仓位。 远程 HTTP 服务绝不会开放交易工具。

---

在托管服务上试用

无需安装。免费工具无需密钥即可使用。对于高级工具，只需调用一次 hl_request_free_key：它会返回一个每月可调用 100 次高级工具的密钥，无需注册。

Claude Code：

claude mcp add --transport http hypersignal https://hypersmash.fly.dev/mcp --header "X-API-Key: <your key>"

Cursor（.cursor/mcp.json）：

{ "mcpServers": { "hypersignal": { "url": "https://hypersmash.fly.dev/mcp", "headers": { "X-API-Key": "<your key>" } } } }

没有密钥时，免费工具仍可使用；hl_request_free_key 发放密钥后，再添加该密钥。

---

安装

要求

Node 20 或 22 LTS（Node 24 没有预编译的 better-sqlite3 二进制文件，且需要 C++ 工具链 — 请使用 LTS）。 npm install && npm run build。

本地（stdio）— 免费 + 交易，适用于 Claude Desktop / Claude Code / Cursor

Claude Desktop（claude_desktop_config.json），使用 npm：

{
  "mcpServers": {
    "hypersignal": {
      "command": "npx",
      "args": ["-y", "hypersignal-mcp"],
      "env": {
        "HL_NETWORK": "mainnet",
        "HL_BUILDER_ADDRESS": "0xYourBuilderAddress",
        "HL_ENABLE_TRADING": "false"
      }
    }
  }
}

也可以从克隆的仓库运行："command": "node"，"args": ["/absolute/path/to/HyperliquidMCP/dist/server-stdio.js"]。 Cursor（.cursor/mcp.json）使用相同的 command/args/env 格式。

本地检查：

npm run build && npm run inspect     # @modelcontextprotocol/inspector

远程（Streamable HTTP）— 免费 + 高级工具，可变现

cp .env.example .env      # fill in keys / builder / x402
docker compose up -d      # serves POST /mcp on :8080, 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
Pro 密钥	高级调用不限次数	每 30 天 $29
x402 按次付费	每次高级调用	$0.01 USDC（Base）

如何获取

• 免费密钥： 调用 hl_request_free_key。即时获取，无需注册。
• x402 按次付费： 在托管服务上，不带密钥调用高级工具时，响应会返回 x402 付款要求 （0.01 USDC（Base），精确金额）；支持 x402 的客户端会签署付款，然后使用 X-PAYMENT 标头重试，工具调用随即执行。只有工具成功交付结果后才会结算付款， 因此调用失败不会产生费用。
• Pro： 调用 hl_buy_pro。它会返回 x402 付款要求（29 美元，以 USDC 在 Base 上支付）；支持 x402 的客户端完成付款并使用 X-PAYMENT 标头重试，响应会附上你的 Pro 密钥， 有效期为 30 天（仅显示一次：请妥善保存）。使用 X-API-Key 标头携带密钥再次调用该工具， 即可将密钥有效期延长 30 天；免费密钥会原地升级，并保留其提醒。密钥会在付款结算前激活， 续订则只会在付款结算后生效，因此付款失败不会产生费用。付款一经完成即为最终付款， 不会自动退款：如果出现问题，请提交 issue， 并注明付款时间。如果你没有支持 x402 的客户端，请改为提交标题为“Pro key request”的 issue， 并说明如何联系你；切勿在 issue 中发布密钥。 Pro 密钥到期后，其行为与不带密钥相同（可使用免费工具，按次通过 x402 付费），错误信息会说明如何 续订；目前该密钥的提醒仍会继续运行。

面向运营者

• API 密钥： 通过 HYPERSIGNAL_PRO_KEYS / HYPERSIGNAL_FREE_KEYS 配置（以逗号分隔的原始 密钥，在存入 SQLite 前会进行哈希处理；密钥永不过期）。购买的密钥也存储在同一张表中，并带有 到期日期；每笔购买都会记录在 pro_purchases 中。使用量计数器按密钥和月份分别统计。只要列表中 至少保留一个密钥，从这些列表中移除的密钥就会在下次启动时撤销：两个列表都为空会被视为密钥丢失， 不会撤销任何密钥。
• x402： 当请求没有密钥或可用额度，且 X402_ENABLED=true 时，高级工具会返回带有付款要求的 x402 付款必需响应；在验证与结算完成后，工具调用随即执行。没有支付协调器时会安全失败（绝不会伪造付款）。
• Apify： apify-actor/ 将畅销的高级工具重新导出为按事件付费的 Actor。 目前为私有。

---

🔌 Builder 代码（连接我们的终端配置）

通过 HyperSignal 的 builder 代码路由你的 Hyperliquid 订单，以支持本项目： 设置 HL_BUILDER_ADDRESS 和（可选）HL_BUILDER_FEE_TENTHS_BPS（以基点的十分之一为单位；默认值为 5 = 0.5 基点， Hyperliquid 永续合约上限为 10 基点）。需要从你的主钱包进行一次性授权：

hl_approve_builder_fee_guide   →  gives you the exact approveBuilderFee payload + steps

服务器永远不会看到你的主密钥；授权由你自行签署。

---

架构

src/
  core/       Hyperliquid Info client, WS mids feed (+REST fallback), LRU+TTL cache, rate limiter, retries
  hl/         typed endpoints, market/account/whale normalization, cohort resolution
  tools/      one file per tool (Zod input + outputSchema + annotations); free / premium / trading
  billing/    SQLite keys + monthly counters, tiers, x402 (fail-closed)
  trading/    L1 action signing (viem + msgpack), dry-run-first exchange service
  server-core.ts   builds an McpServer for a tier set + billing gate
  server-stdio.ts  local entrypoint  (free + trading)
  server-http.ts   remote entrypoint (free + premium, stateless JSON)
apify-actor/  thin pay-per-event wrapper
evals/        10 read-only, time-stable eval questions
docs/         PHASE0 research report, GTM checklist

强制执行的设计规则：.env 之外不得存放机密；交易绝不通过远程方式执行；每次外部调用都设有超时、 最多进行 3 次指数退避重试，并支持优雅降级；响应会进行聚合、分页和截断；高级工具和交易工具均附带财务免责声明；仅使用在 Phase 0 中验证过的 Hyperliquid 端点。

---

开发

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

许可证

MIT。与 Hyperliquid 无关联。使用风险自负。