第三讲：Hyperliquid API 基础——REST 与 WebSocket 的抉择
说实话，刚接触 Hyperliquid 的时候，我第一反应就是翻 API 文档。毕竟做量化嘛，数据就是命。但很多新手上来就踩坑——分不清什么时候该用 REST，什么时候该上 WebSocket。今天咱们就把这事彻底聊透。
REST API 与 WebSocket API：到底有啥区别？
先给个最直白的结论：REST 适合查一次性的数据，WebSocket 适合盯持续变化的数据。
我刚开始做交易系统时，犯过一个低级错误——用 REST 去轮询订单簿。每 200 毫秒拉一次，结果被限流不说，数据还总是滞后。后来换成 WebSocket，问题迎刃而解。你想想看，订单簿这种每秒变几十次的东西，用 REST 去轮询，不是自找麻烦吗？
| 特性 | REST API | WebSocket API |
|---|---|---|
| 连接方式 | 请求-响应，每次独立 | 长连接，全双工 |
| 数据时效性 | 有延迟（取决于轮询频率） | 实时推送，毫秒级 |
| 适用场景 | 查询账户余额、历史K线、下单 | 订阅订单簿、交易对价格、成交记录 |
| 资源消耗 | 低（但频繁请求会高） | 中等（需维持心跳） |
| 限流风险 | 高（尤其高频轮询） | 低（订阅后持续推送） |
核心原则：需要「当前快照」用 REST，需要「持续流」用 WebSocket。别混着用，更别用 REST 模拟 WebSocket 的功能。
API 文档速览：别被吓到，其实就这几块
Hyperliquid 的 API 文档，说实话，第一眼看上去有点乱。但拆开来看，核心就三块：
- 公开市场数据：不需要 API Key，谁都能调。包括订单簿、K线、交易对信息、最近成交等。
- 账户与交易：需要签名认证。查余额、下订单、撤单、查持仓。
- WebSocket 订阅：实时数据流。订单簿快照、增量更新、成交推送。
我个人习惯，先看公开数据接口。因为不需要认证，调试起来最快。等跑通了数据流，再搞交易接口。
小技巧：文档里有个「Try it out」按钮，可以直接在浏览器里测试接口。我经常用它来验证参数格式，比写代码快多了。
获取公开市场数据：动手实操
好，咱们直接上代码。先拿公开数据练练手。
1. 获取所有交易对信息
import requests
BASE_URL = "https://api.hyperliquid.xyz"
def get_all_markets():
"""获取所有交易对信息"""
url = f"{BASE_URL}/info"
payload = {"type": "allMids"}
resp = requests.post(url, json=payload)
return resp.json()
markets = get_all_markets()
print(markets)
嗯，这里要注意。Hyperliquid 的 REST 接口用的是 POST 方法，不是常见的 GET。我第一次调的时候也愣了一下，后来发现文档里写得很清楚——所有查询都用 POST，请求体里放 type 参数。
2. 获取订单簿数据
def get_orderbook(coin: str):
"""获取指定币种的订单簿"""
url = f"{BASE_URL}/info"
payload = {
"type": "l2Book",
"coin": coin
}
resp = requests.post(url, json=payload)
return resp.json()
btc_book = get_orderbook("BTC")
print(btc_book)
返回的数据结构是这样的：
{
"coin": "BTC",
"levels": [
[{"px": "50000.0", "sz": "1.5", "n": 2}, ...], // 卖单
[{"px": "49980.0", "sz": "2.3", "n": 3}, ...] // 买单
]
}
levels[0] 是卖单（asks），levels[1] 是买单（bids）。每个 level 包含价格（px）、数量（sz）和订单数（n）。
我曾经踩过的坑：订单簿的深度是有限的，默认只返回前 50 档。如果你需要全量深度，得用 WebSocket 订阅。用 REST 拉全量？别想了，数据量太大，接口会直接拒绝。
3. 获取历史K线
def get_candles(coin: str, interval: str = "1h", limit: int = 100):
"""获取K线数据"""
url = f"{BASE_URL}/info"
payload = {
"type": "candleSnapshot",
"coin": coin,
"interval": interval,
"limit": limit
}
resp = requests.post(url, json=payload)
return resp.json()
btc_candles = get_candles("BTC", "15m", 50)
print(btc_candles)
支持的 interval 参数：1m、5m、15m、1h、4h、1d。limit 最大 500。
知识体系总览
下面这张图，是我自己梳理的 Hyperliquid API 知识结构。你看一眼，心里就有谱了。
实战建议：先跑通，再优化
我个人建议，刚开始别想太复杂。先拿 REST 把公开数据拉下来，打印到控制台看看。确认数据格式、字段含义都搞明白了，再上 WebSocket。
我曾经见过一个团队，上来就搞 WebSocket 全量订单簿，结果数据量太大，程序直接 OOM 了。你想想看，全量订单簿每秒推送几十次，每次几千条数据，内存不爆才怪。
正确的做法是：先用 REST 拉一次快照，然后用 WebSocket 订阅增量更新。这样既保证了数据完整，又控制了内存消耗。
我的调试习惯：先用 curl 或 Postman 调一次接口，确认返回数据没问题，再写 Python 代码。这样能快速定位是网络问题还是代码问题。
好了，这一讲的内容就到这。REST 和 WebSocket 的区别、文档结构、公开数据获取，咱们都过了一遍。下一讲，咱们会深入 WebSocket 的订阅机制，包括如何维护心跳、如何处理断线重连——这些可都是实战中的硬骨头。