Hyperliquid Agent Gateway

hyperliquid-agent-gateway

Hyperliquid 为你提供约 233 个永续合约、326 个现货交易对，以及一整条 EVM 链，所有数据都可通过公共端点读取。这个 MCP 服务负责为你的 Agent 获取这些数据：市场和资金费率数据、账户风险、交易者活动、HyperEVM（链 999）代币转账。无需密钥、无需签名、不会写入；所有请求都通过 api.hyperliquid.xyz/info 和 rpc.hyperliquid.xyz/evm 发送，并经过缓存和速率限制，避免过于热情的 Agent 向上游发起过多请求。

使用场景

清算工具是大家最常用的功能。输入任意地址，即可获得保证金摘要、各持仓杠杆，以及距离清算的幅度；如果平台公布了 liquidationPx，就会返回真实数值并明确标注；如果没有公布，则会返回估算值并注明是估算结果。我们曾在一个名义价值 2.09 亿美元、杠杆 25 倍的空头仓位上测试，当时该仓位距离清算仅有 17.6%。

资金费率：funding_carry_screener 通过一次调用为全部 233 个永续合约排名，然后只为排名靠前的少数合约获取 168 小时的历史数据，因为 API 的权重额度（每分钟 1200）会惩罚不加节制的请求。你可以据此判断某个费率是短暂飙升还是长期趋势。

HyperEVM 转账可将链上资金流与永续合约市场联系起来；quote 返回基于订单簿计算、始终位于 [bid, ask] 之间的中间价；trader_activity 则会分析任意地址的成交、费用、胜率、资金费率拖累和未平仓头寸。

完整操作指南：examples/use-cases.md。

快速开始

Claude Code：

claude mcp add hyperliquid -- uvx hyperliquid-agent-gateway

stdio（默认，用于本地 Agent）：

uvx hyperliquid-agent-gateway

或者从代码库检出版本运行：

git clone https://github.com/alekskram/hyperliquid-agent-gateway
cd hyperliquid-agent-gateway
uv sync
uv run hyperliquid-agent-gateway

Claude Desktop / Cursor 配置：

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["hyperliquid-agent-gateway"]
    }
  }
}

托管模式，使用端口 8903 上的可流式 HTTP：

uvx hyperliquid-agent-gateway --http             # 127.0.0.1:8903
curl http://127.0.0.1:8903/health   # -> {"ok": true, "service": "hyperliquid-agent-gateway", ...}

[mcp_servers.hyperliquid]
command = "uvx"
args = ["hyperliquid-agent-gateway"]

# 1) start the gateway (keep it running)
uvx hyperliquid-agent-gateway --http --port 8903 &

# 2) register it (merges into ~/.zcode/cli/config.json)
python3 - <<'PY'
import json, os
p = os.path.expanduser("~/.zcode/cli/config.json")
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault("mcp", {}).setdefault("servers", {})["hyperliquid"] = {
    "type": "http", "url": "http://127.0.0.1:8903/mcp"}
json.dump(cfg, open(p, "w"), indent=2)
print("hyperliquid-agent-gateway registered:", p)
PY

所有 12 个工具均为只读（标注为 readOnlyHint: true, destructiveHint: false, openWorldHint: true）。

为什么使用网关，而不是原始 API？

api.hyperliquid.xyz/info 是开放的，只需一次 POST 即可访问。真正的陷阱在后面：

速率限制

两个相互独立、在本地执行的预算用于保护上游：

/info - 每滚动 60s 1200 权重（Hyperliquid 记录的权重定价），按请求类型跟踪：

当下一个请求将超出预算时，客户端会等待一次（<=5s），让时间窗口滚动，然后抛出明确指出限制的错误——绝不会无限期阻塞休眠。

HyperEVM RPC - 每滚动 60s 100 个请求（每个请求固定计为 1），独立于 /info 执行限制。超出预算的调用会立即报错（rpc-limit）——工具会返回如实的错误字典，而 wallet_balance 会在达到上限时停止扫描 ERC-20。

TTL 缓存还会按数据类型去重重复调用：allMids 15s、recentTrades 15s、l2Book 5s、metaAndAssetCtxs 60s、spotMeta 3600s、spotMetaAndAssetCtxs 60s、candleSnapshot 300s、fundingHistory 300s、按地址区分的账户类型 60s。

数据说明

• API 返回的所有数值在上游均为字符串；网关使用不会抛出异常的辅助函数解析——null 始终表示“不可用”，绝不表示零。
• 所有上游故障都会返回错误字典 {"error": ..., "source": ..., "reason": ...}，绝不返回回溯信息；部分数据会按字段降级，并附带 warnings[]。
• liquidation_risk 绝不会凭空编造清算价格：当平台未提供清算价格时，liq_px 会保持为 null，距离则是明确标记的估算值（公式见工具说明）。同样不会凭空编造标记价格：实时持仓不包含 markPx，因此会从 metaAndAssetCtxs（回退至 allMids）解析，且行中的 mark_px_source 会注明来源；没有来源时为 null。
• funding_drag / funding_net：平台的 userFunding 仅返回非零资金费事件，因此对于新地址或近期无活动的地址，实时返回 null / 空值属于预期行为，并非错误。
• ERC-20 数量使用适用于标准 HyperEVM 代币的静态小数位映射（USDC/USDT 类为 6，PURR/HYPE 为 18）；未知代币默认按 18 位处理，且每行都会注明 decimals_source: "assumed_18"——对于未映射的代币，不要相信 6 位小数精度。
• 缓存的响应会携带 age_seconds / fetched_at 新鲜度字段。

套件中的其他项目

四个同系列的只读 MCP 网关：无需密钥、带缓存、如实降级。

这四个项目都已上架 glama.ai 和 PyPI；任何一个都可通过 uvx <name> 安装。

许可证

MIT。