Liquidiction Hip 4

Liquidiction MCP Server

面向兼容 MCP 的 Agent 提供 HIP-4 预测市场只读工具。该服务直接连接 Hyperliquid 的公共 API。无需 API 密钥、钱包连接或签名权限。

安装

需要 Node.js 20 或更高版本以及 npm。

git clone https://github.com/Liquidiction/liquidiction-mcp.git
cd liquidiction-mcp
npm ci
npm start

这是一个 stdio MCP 服务，因此 npm start 会等待 MCP 客户端，而不是打开网站。默认使用主网。只有需要测试网数据时，才设置 HL_API_URL=https://api.hyperliquid-testnet.xyz。

对于现有安装：运行 git pull --ff-only、npm ci，然后重启 MCP 客户端。

连接客户端

安装依赖后，使用绝对路径配置客户端：

{
  "mcpServers": {
    "liquidiction": {
      "command": "node",
      "args": [
        "/absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs",
        "/absolute/path/liquidiction-mcp/mcp-server.ts"
      ],
      "env": {
        "HL_API_URL": "https://api.hyperliquid.xyz"
      }
    }
  }
}

此配置使用已安装的运行时，即使客户端的工作目录位于其他位置也能正常工作。在 Windows 上，请使用类似 C:/Users/you/liquidiction-mcp/mcp-server.ts 的路径，以及对应的 node_modules/tsx/dist/cli.mjs 路径。更改配置后，请重启客户端。

对于 Claude Code：

claude mcp add liquidiction -- node /absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs /absolute/path/liquidiction-mcp/mcp-server.ts

对于从仓库目录启动的客户端，npx tsx mcp-server.ts 也可正常工作。

工具

工具	输入	结果
list_markets	无	活跃结果、选项、交易场所和价格
get_market_detail	outcome_id	元数据、交易场所、选项和各方价格
get_market_summary	无	市场概览和可用的结算元数据
get_orderbook	outcome_id，可选的 side	最优买价、卖价和价差
get_prices	无	当前结果的中间价
get_candles	coin，可选的 interval、可选的 hours	OHLCV 历史数据
get_recent_trades	coin	所选结果方的近期公开交易
get_user_fills	address，可选的 limit	某钱包近期公开的 HIP-4 成交记录
get_open_orders	address	公开的未成交 HIP-4 订单
get_user_positions	address	持仓、交易场所、选项、持有份额和标记价值

结果 API 请求使用 #N。显式的币种输入也接受 +N、旧版 @N 和纯数字别名，并将其规范化为 #N。以 +N 返回的钱包余额会保留其原始币种，同时提供规范的 #N 标识符。普通现货 @N 行不会被归类为结果持仓或成交记录。

跨部署方持仓

向你的 Agent 提问：

显示此钱包的 HIP-4 持仓，包括交易场所、队伍、总份额和持有份额。比较同一场比赛的持仓，但不要合并它们的合约。

get_user_positions 会返回 JSON 文本，其中包含 address、fetchedAt、source、快照说明以及一个 positions 数组。每行包括：

• coin、rawCoin、outcomeId、side、venue 和部署方地址。
• 可用时，根据合约元数据解析出的市场和选项标签。
• shares、原始 total 字符串、heldShares 和 unheldShares。
• markPrice 和 markedValue；如果没有可用的有效标记，则为 null。
• 可用的合约时间、结果来源和计入比赛的字段，以及原始描述。

不要假设 side 0 在不同交易场所都代表同一支队伍。Outcome 和 trade.xyz 可能会以相反顺序列出同一场比赛的参赛方。这些工具会保留不同的合约及其规则；它们不会验证合约是否等价，也不会自动合并持仓。

unheldShares 是总份额减去持有份额，并不保证订单可以成交。读取的数据并非原子快照。标记价格只是估值，并非可执行的卖出报价。缺失的活跃市场元数据仍会是 null；此服务不会提供每个已结算合约的历史元数据。

请提供已知的钱包地址。此服务不会搜索索引来查找持有特定市场组合的钱包。

开发与验证

npm ci
npm run typecheck
npm test

回归测试套件可离线运行，涵盖当前余额格式、跨部署方的方向反转、持仓份额、分数余额、缺失的标记价格、输入验证和 API 错误。

可选的只读冒烟测试会启动一个真实的 MCP stdio 客户端，并针对已配置的 Hyperliquid 网络调用全部 10 个工具：

npm run test:live -- 0xff16003f5bc3560daf4b9df62c191831af47387f 1866

示例使用的是一个真实钱包，因此持仓可能会变化。如果该钱包不再有持仓，请选择另一个钱包和活跃的结果 ID。该测试会将 MCP 持仓与单独读取的余额进行比较；如果钱包在两次读取之间进行了交易，测试可能会失败。正常的 Hyperliquid 速率限制仍然适用。

链接

• Liquidiction
• MCP 文档
• X

采用 MIT 许可。此服务端不会提交交易。