Hyperliquid

@pipeworx/hyperliquid

Hyperliquid 的只读数据。它是最大的链上永续合约交易所（也运营现货市场），可获取中间价、订单簿、蜡烛图、资金费率及历史数据、实时未平仓合约，以及任意钱包地址的公开账户状态（永续合约保证金和持仓、现货余额、账户价值历史记录）。每次请求都会通过代理实时访问 Hyperliquid 自己的公开信息 API。无需密钥、无需签名、不能交易：签名交易端点特意不在支持范围内。

这是 Pipeworx 的一部分 — 一个将 AI Agent 连接到 1881+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联、未获其认可，也不是由其发布。

工具

• hyperliquid_perp_meta(coin?) — 永续合约市场列表（交易代码、数量小数位数、最大杠杆、是否已下架）。传入 coin 可查询单个交易代码；省略则返回完整列表。

• hyperliquid_spot_meta() — Hyperliquid 列出的所有现货交易对，每项包含交易对名称、交易对索引及其组成代币的 ID。

• hyperliquid_mids(coin?) — 一次调用即可获取所有永续合约／现货交易代码的当前中间价，也可只查询单个交易代码的中间价。

• hyperliquid_asset_context(coin) — 某个永续合约的实时资金费率、未平仓合约、标记价／预言机价格／中间价、溢价和 24 小时交易量。

• hyperliquid_l2_book(coin, depth?) — 实时买卖订单簿（价格、合计数量、每个价位的订单数）。

• hyperliquid_candles(coin, interval?, lookback_hours?, start_time?, end_time?) — Hyperliquid 保留范围内任意时间段的 OHLCV 蜡烛图。

• hyperliquid_funding_history(coin, lookback_hours?, start_time?, end_time?) — 已结算资金费率序列（Hyperliquid 每小时结算一次资金费率）。

• hyperliquid_account_state(address) — 单个钱包的永续合约账户：账户价值、名义价值、已用保证金、可提取金额，以及所有未平仓仓位（带正负号的数量、入场价、盈亏、杠杆、清算价、累计资金费）。

• hyperliquid_spot_balances(address, limit?) — 单个钱包的现货代币：总额、订单冻结金额、可用金额和成本基础名义价值。

• hyperliquid_account_history(address, period?, scope?) — 按日／周／月／全部时间查看账户价值和盈亏，并优先提供起始／结束价值及交易量。

账户工具读取的是公开账本：地址是化名化的链上标识符，Hyperliquid 无需凭据即可向任何人提供其状态；此处的任何信息都不会将地址与个人关联。未知地址会明确返回“无活动”，而不是直接返回零。

hyperliquid_account_state 通过两个标志回答两个不同的问题，调用方无需根据一个标志推断另一个：account_has_balance（永续合约账户价值非零，包括闲置的零碎余额）和 account_has_open_perp_positions（有未平仓仓位，或名义价值、已用保证金非零）。持有少量资金但没有未平仓仓位的地址，其结果为 true / false。

身份验证

无需密钥。对于此工具包中的任何读取操作，Hyperliquid 的信息端点（POST api.hyperliquid.xyz/info）均不需要 API 密钥、账户或签名。

数据源

• https://api.hyperliquid.xyz/info — Hyperliquid 的公共信息端点。 上述每个工具都会在 POST 请求体中发送不同的 type（meta、 spotMeta、allMids、metaAndAssetCtxs、l2Book、candleSnapshot、 fundingHistory）——这里只有一个 URL，而不是每种资源各有一个 URL。

以下事项可以避免后续调用者费力摸索：

• 测试中未观察到单次请求触发速率限制错误——Hyperliquid 的 公共文档说明，info 端点有基于 IP 的权重限制，但此工具包不会针对 429 错误做特殊处理；调用者若遇到此错误，会原样收到 Hyperliquid 自己的错误正文（通过 httpError），而不是 Pipeworx 专属消息。
• Perp 与 spot 的币种 ID 属于不同的命名空间，但 coin 参数的 形式相同。 Perp 使用其裸符号（"BTC"、"ETH"）进行寻址。Spot 交易对使用 "@<index>"（例如 "@0"）进行寻址，但每种代币各有一个 canonical 交易对，同时也有一个易读名称（"PURR/USDC"）。请从 hyperliquid_spot_meta 的 index 字段获取正确的 ID——根据其他位置的排列顺序 猜测 spot 交易对的 @N ID 会出错，因为索引并不会按上市日期连续排列。
• allMids 的键混合了 perp 符号和 spot @N ID——响应中没有 type 字段用于区分；你必须事先知道某个符号属于哪个命名空间（perp 列表来自 hyperliquid_perp_meta，spot 列表来自 hyperliquid_spot_meta）。
• 如果 startTime/endTime 窗口内没有任何区间边界，candleSnapshot 会返回 []（而不是错误）——例如，粒度为 1h 时，窗口只有 100ms。这是合法的空 结果，不代表调用失败；请扩大窗口或使用更粗的间隔。
• 未平仓合约量以基础资产单位报告，而不是 USD（例如，BTC 的数值 "37751.7" 表示未平仓合约量为 37,751.7 BTC，而不是美元）——如需 USD 数值，请乘以 markPx。
• metaAndAssetCtxs 会返回一个两元素数组 [meta, assetCtxs]， 其中 assetCtxs[i] 对应 meta.universe[i]——它没有 每种资产对应的键；你必须先查出该币种在 universe 中的索引，再用 同一索引访问 assetCtxs。此工具包会在 hyperliquid_asset_context 中为你完成这项查找。
• 不会单独发布历史未平仓合约量——只能获取当前未平仓合约量（通过 metaAndAssetCtxs/ hyperliquid_asset_context）；没有类似 fundingHistory 的 openInterestHistory 端点。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "hyperliquid": {
      "url": "https://gateway.pipeworx.io/hyperliquid/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/hyperliquid/mcp 上的 tools/list 会返回上表中的工具 以及共享的 Pipeworx 元工具——ask_pipeworx、 discover_tools、search_within、remember/recall，以及网关全局工具集中的 其他工具。因此，你看到的工具数量会多于此表：目前，单工具包端点会在工具包自身的工具之外， 列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是当天情况的权威依据。

这是有意设计的，并非意外复用。这些元工具让范围受限的连接能够回答本工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录路由——无需你添加第二个 MCP 服务。目前无法挂载不含这些元工具的 工具包端点；如果额外的 schema 占用的上下文比路由带来的价值更大，请只连接一次完整网关， 而不要连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1881+ 个数据源。唯一的区别是哪些工具包的工具会被直接 列出；无论使用哪个 URL，ask_pipeworx 都可以访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/hyperliquid_perp_meta \
  -H 'Content-Type: application/json' \
  -d '{"coin":"BTC"}'

首次调用无需账号。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/hyperliquid_perp_meta。查找工具：POST https://gateway.pipeworx.io/v1/tools/search_packs，并使用 {"query":"..."}。

独立运行（无需网关账号）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账号，也无需经过网关：

{
  "mcpServers": {
    "hyperliquid": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-hyperliquid"]
    }
  }
}

或者直接运行它，确认可以启动：

npx -y @pipeworx/mcp-hyperliquid

它通过 stdin/stdout 使用 MCP，并响应 initialize/tools/list/tools/call，但仅支持此软件包的工具——不包含上述网关连接添加的任何共享元工具。相同的源代码，相同的工具，不会通过 ask_pipeworx 路由。

使用 ask_pipeworx

无需直接调用工具，你可以用通俗的英语提问——此方式既适用于上面的软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Hyperliquid data" })

网关会选择合适的工具并自动填充参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT