Hyperliquid API 指南：Python、WebSocket 与钱包追踪（2026）

快速回答： Hyperliquid API 是一个免费、公开的接口，由三个部分组成：Info 端点（POST https://api.hyperliquid.xyz/info）用于读取市场和账户数据，Exchange 端点用于下单，以及 WebSocket（wss://api.hyperliquid.xyz/ws）用于实时数据流。使用官方 Python SDK，你可以在几分钟内获取任意钱包的成交、持仓和盈亏——或者完全跳过代码，通过 Hyperfolio（免费的 Hyperliquid 钱包追踪器） 即时查看任意钱包的盈亏、手续费和资金费率。

Hyperliquid 上的每一笔仓位、成交和清算都上链存储，任何人都可以通过 API 公开读取。这在加密领域非常罕见：大多数交易所都把订单簿和账户数据藏在私有端点后面。Hyperliquid 向所有人开放这些数据，因此开发者、量化交易者和 Hyperfolio 这样的分析工具都在读取同一份原始数据。

问题在于，官方文档是参考手册，不是教程。你不得不在 GitBook、Python SDK 仓库和旧的 GitHub issue 之间来回跳跃，才能拼凑出真正的用法。本指南给你可直接运行的版本：端点、代码、限流规则和那些浪费开发者时间的坑——然后告诉你什么值得自己构建，什么直接用现成的追踪器就能解决。

什么是 Hyperliquid API？

API 分为三个部分，各自承担不同的职责：

• Info 端点（REST，只读）：市场数据、订单簿状态、用户的成交记录、持仓、账户价值、资金费率、清算和排行榜数据。
• Exchange 端点（REST，需认证）：下单、撤单、改单，以及提现——使用 agent wallet 签名。
• WebSocket：实时推送成交、订单簿更新、allMids、用户成交、资金费率等，无需轮询。

官方文档中的所有示例都使用主网基础 URL https://api.hyperliquid.xyz；测试网对应地址为 https://api.hyperliquid-testnet.xyz。

接口	URL	认证	用途
Info（REST）	POST api.hyperliquid.xyz/info	无	读取任意钱包、市场数据、排行榜
Exchange（REST）	POST api.hyperliquid.xyz/exchange	agent wallet 签名	下单/撤单、提现
WebSocket	wss://api.hyperliquid.xyz/ws	无（读取），动作需签名	实时成交、订单簿、用户成交

快速上手：5 分钟用上 Python SDK

Hyperliquid 维护着官方 Python SDK（github.com/hyperliquid-dex/hyperliquid-python-sdk），社区还提供了 Rust 和 TypeScript SDK。安装后即可查询任意币种的中间价：

pip install hyperliquid-python-sdk

from hyperliquid.info import Info

info = Info("https://api.hyperliquid.xyz")
mids = info.all_mids()
print(mids["BTC"])   # 例如 "98452.3"

Info 类把所有只读端点封装成了带类型的方法，你几乎不需要直接处理原始 HTTP。如果 SDK 没有覆盖某个功能，你也可以直接向 Info 端点 POST JSON——它本质上就是一个 HTTP API。

用 Info 端点读取任意钱包

这是大多数教程跳过、但对追踪最重要的部分：如何读取任意钱包的状态，而不只是你自己的。由于 Hyperliquid 的订单簿和账户状态都在链上，所有钱包都是公开的。关键的请求类型包括：

• clearinghouseState — 用户的未平仓仓位、保证金概览和账户价值。
• userFills — 最近 2,000 笔成交，每笔包含 px、sz、side、time、fee、feeToken、dir、startPosition 和 closedPnl。
• userFillsByTime — 按时间范围查询成交，支持分页；每次响应最多 2,000 笔，且仅保留最近 10,000 笔。
• allMids — 所有永续合约的中间价。
• userRateLimit — 钱包的 API 配额和当前使用量。

import requests

r = requests.post("https://api.hyperliquid.xyz/info", json={
    "type": "userFills",
    "user": "0x你的地址或任意地址"   # 任意 42 字符地址
})
fills = r.json()
for f in fills[:3]:
    print(f["coin"], f["dir"], f["px"], "fee:", f["fee"], "closedPnl:", f["closedPnl"])

两个几乎人人都会踩的坑：

• 使用真实的账户地址。 如果查询 agent wallet 的地址，你会得到空结果——必须传入 master 账户或子账户的地址。
• 分页有上限。 时间范围查询每次最多返回 500 个元素或区块；用最后返回的时间戳作为下一次 startTime 继续翻页。成交记录最多只能查到最近 10,000 笔。

用 WebSocket 获取实时数据

对于小型应用，轮询 Info 端点没问题，但实时追踪的正确工具是 WebSocket。连接到 wss://api.hyperliquid.xyz/ws（主网）或 wss://api.hyperliquid-testnet.xyz/ws（测试网）并订阅：

from hyperliquid.info import Info
from hyperliquid.utils import constants

info = Info(constants.MAINNET_API_URL, skip_ws=False)
info.subscribe({"type": "trades", "coin": "BTC"}, callback=print)

或者用 websockets 库直接操作：

import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws:
        await ws.send(json.dumps({"method": "subscribe",
                                  "subscription": {"type": "trades", "coin": "BTC"}}))
        async for msg in ws:
            print(msg)

asyncio.run(main())

订阅类型包括 trades、allMids、l2Book、userFills、userEvents（资金费率、清算、订单）、activeAssetCtx 和 candle 等。

一定要处理重连。 官方文档明确说明：服务器会不定期断开连接，且不会提前通知。自动化程序必须检测断线并优雅重连——重连后的 snapshot ack 会包含断线期间的数据，缺失部分可以通过对应的 Info 请求补拉。

Exchange API 与 agent wallet

如果你想程序化交易，Exchange 端点接收已签名的动作负载（order、cancel、withdraw……）。你绝不能用自己的主钱包签名：应该创建 agent wallet，它可以交易但不能提现——即使 API 密钥泄露，损失也有限。

from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account

account = Account.from_key("0x你的AGENT私钥")
exchange = Exchange(account, constants.MAINNET_API_URL)
result = exchange.order("BTC", True, 1.0, 99000.0, {"limit": {"tif": "Gtc"}})
print(result)

下单的完整说明在 GitBook 的 Exchange endpoint 章节，包含精确的动作负载格式。如果要做的不只是个人机器人，先读完下面的限流规则再写第一个循环。

限流规则和浪费时间的坑

公开 REST API 的限制大约是每个 IP 每分钟 1,200 请求权重，大多数 Info 请求消耗约 20 点权重，再加上按条目计算的附加费用——所以一个朴素的轮询循环很快就会撞上天花板。另外，时间范围查询每页最多返回 500 个元素，超过最近 10,000 笔的成交记录就无法通过 API 获取了。

对追踪器而言，实际后果是：

• 同时监控大量钱包需要精心分批和退避，否则会收到 429 响应。
• 长期盈亏历史需要持续归档——你无法回溯拉取一整年的成交记录。
• 资金费率支付和清算事件与成交记录是分开的事件类型，必须合并后才能计算真实盈亏。
• 手续费以成交记录中的 feeToken 收取，且包含 builder fee，盈亏计算必须正确扣减。

结论：读取 Hyperliquid 数据很容易。但要正确地读取——完整历史、手续费、资金费率、清算、分页、重连——就是一个小型工程项目了。

自己搭建追踪器 vs. Hyperfolio

如果你的目标是交易机器人或自定义回测引擎，API 是正确的根基。但如果你的目标是追踪——自己的盈亏、跟单的钱包或聪明钱——自己搭建就意味着要处理上面所有问题。这是诚实的对比：

能力	用 Hyperliquid API 自己搭	Hyperfolio
搭建时间	数天到数周	< 1 分钟，无需注册
需要写的代码	300–800+ 行（分页、合并、存储）	0 行
限流	每个 IP 每分钟 1,200 权重，需自行管理	无感知——随时读取任意钱包
成交历史	API 只能查最近 10,000 笔	持续追踪，完整盈亏拆分
含手续费和资金费率的盈亏	自己实现计算逻辑	内置，按平台和钱包拆分
多平台（AsterDEX、Lighter、Robinhood Chain）	每个平台单独对接	开箱即用的统一投资组合
成交/清算推送提醒	自己搭建通知管道	内置推送提醒
价格	你的开发时间	免费

Hyperfolio 基于同样的公开数据构建，但它替你解决了追踪层：连接你的钱包或 搜索任意 Hyperliquid 地址，即可查看按手续费和资金费率拆分的盈亏、未平仓仓位、聪明钱雷达和推送提醒——无需注册，无需任何基础设施。

原始 API 仍然占优的场景

说实话：当你的目标是交易机器人、自定义回测引擎或大规模研究数据集时，API 是更好的选择。Hyperfolio 不是代码的替代品——它是你原本要自己搭建的追踪面板的替代品。如果你需要下单执行、自定义指标或机器可读的存档，请使用 SDK 和 Exchange 端点。如果你需要知道一个钱包做了什么、赚了多少、付了多少手续费，Hyperfolio 立刻给你答案。

常见问题

Hyperliquid API 免费吗？

是的。Info 和 WebSocket 端点公开且免费，但有限流（每个 IP 每分钟约 1,200 请求权重）。只有通过 Exchange 端点下单时才需要支付交易手续费。

Hyperliquid WebSocket 的 URL 是什么？

主网是 wss://api.hyperliquid.xyz/ws，测试网是 wss://api.hyperliquid-testnet.xyz/ws。发送 subscribe 消息并指定订阅类型（如 trades、allMids、userFills），同时处理重连。

能用 Hyperliquid API 追踪其他钱包的盈亏吗？

可以——Hyperliquid 上的所有钱包都是公开的。用钱包地址查询 userFills 和 clearinghouseState，然后用 closedPnl 减去手续费和资金费率即可计算盈亏。或者直接在 Hyperfolio 中搜索该地址，无需代码即可获得完整拆分。

Hyperliquid 的 agent wallet 是什么？

agent wallet 是你授权代表主账户交易的一把独立密钥。它可以下单和撤单，但永远不能提现，即使密钥泄露，你的余额也是安全的。

API 会分别返回手续费和资金费率吗？

成交记录包含 fee 字段（以及 builderFee），而资金费率支付以独立事件返回。把两者与 closedPnl 合并计算，正是 Hyperfolio 自动为你展示真实盈亏的方式。

不写一行代码，开始追踪

Hyperliquid API 是给开发者的礼物，但不是每个问题都需要一套代码。如果你想查看自己的真实盈亏——扣除手续费和资金费率之后——无论是自己的钱包还是正在关注的任意地址，打开 Hyperfolio，连接钱包或粘贴任意 Hyperliquid 地址，免费查看完整盈亏拆分。无需注册，无需 API 密钥，没有 429。

如果你正在开发，可以结合我们关于如何计算含手续费和资金费率的真实盈亏的深入分析，确保你的计算结果与交易所实际结算一致。