用途
Liquidiction MCP Server 为 MCP 兼容的 AI 智能体提供对 Hyperliquid HIP-4 预测市场的只读访问。服务器直接连接 Hyperliquid 的公共 API，无需 API 密钥、钱包连接或签名权限。
主要能力
该服务器提供 10 个工具（资料中未逐一列出具体名称，除 get_user_positions 外）。可查询的内容包括：实时赔率、订单簿、K线、成交记录和持仓。
get_user_positions 返回 JSON 文本，包含 address、fetchedAt、source、快照说明和 positions 数组。每条记录包含：
coin、rawCoin、outcomeId、side、venue以及 deployer 地址。- 在合约元数据可用时解析出的市场与选项标签。
shares（原始总数字符串）、heldShares和unheldShares。markPrice和markedValue；没有有效标记价格时为null。- 可用的合约时间、结果来源、计入比赛字段以及原始描述。
使用方式
环境要求：Node.js 20 或更新版本以及 npm。
这是 stdio MCP 服务器，因此 npm start 会等待 MCP 客户端连接，而不是打开网站。默认使用主网。仅当需要测试网数据时设置 HL_API_URL=https://api.hyperliquid-testnet.xyz。
已有安装更新：运行 git pull --ff-only、npm ci，然后重启 MCP 客户端。
安装依赖后，使用绝对路径配置客户端。这样使用已安装的运行时，即使客户端工作目录在别处也能工作。在 Windows 上，使用诸如 C:/Users/you/liquidiction-mcp/mcp-server.ts 的路径以及对应的 node_modules/tsx/dist/cli.mjs 路径。修改配置后重启客户端。
对于 Claude Code：资料中提供了相应配置方式但未给出完整配置代码。对于从仓库目录启动的客户端，npx tsx mcp-server.ts 也可行。
结果类 API 请求使用 #N。显式 coin 输入也接受 +N、旧式 @N 和纯数字别名，并将其规范化为 #N。以 +N 返回的钱包余额保留其原始 coin，同时暴露规范化的 #N 标识符。普通现货 @N 行不会被归类为结果持仓或成交。
跨部署方的持仓查询示例：让智能体“显示此钱包的 HIP-4 持仓，包括场所、团队、总份额和持有份额。比较同一赛事上的持仓，但不合并其合约。”
适用场景
- 让 AI 智能体查询 Hyperliquid HIP-4 预测市场的实时数据。
- 查看某一钱包的预测市场持仓与余额。
- 比较同一赛事在不同场所（outcome 与 trade.xyz）上的持仓。
限制
- 不要假设
side 0在不同场所代表同一团队。outcome 和 trade.xyz 可能以相反的参与方顺序列出同一赛事。工具保留不同合约及其规则，不认证等价性，也不自动合并持仓。 unheldShares是总份额减去持有份额，并不保证订单能够执行。- 读取不是原子快照。标记价格是估算值，不是可执行的卖出报价。
- 缺失的活跃市场元数据保持为
null；此服务器不为每个已结算合约提供历史元数据。 - 需要提供已知的钱包地址。此服务器不会搜索索引以找出持有特定市场组合的钱包。
开发与验证
回归测试套件离线运行，覆盖当前余额格式、跨部署方方向反转、持有份额、分数余额、缺失标记价格、输入验证和 API 错误。
可选的只读冒烟检查会启动真实的 MCP stdio 客户端，并针对配置的 Hyperliquid 网络调用全部 10 个工具。示例使用真实钱包，因此持仓可能变化。如果它不再有持仓，请选择另一个钱包和活跃的 outcome ID。该检查将 MCP 持仓与单独的余额读取进行比较，如果钱包在两次读取之间发生交易，则可能失败。适用正常的 Hyperliquid 速率限制。
许可证
MIT 许可。此服务器从不提交交易。
