接入 Hyperliquid API：从入门到下单
说起链上合约交易所，Hyperliquid 是近一年来被谈论最多的名字。纯链上的订单簿、毫秒级的撮合速度、还有自带争议的社区文化——它确实和主流 DEX 不太一样。
如果你想给自己的交易系统接入 Hyperliquid，这篇不走跳蚤市场风格，讲点实际踩坑经验。
为什么是 Hyperliquid
Hyperliquid 是一个运行在自己 L1 链上的去中心化交易所，最核心的特点是订单簿完全上链，不像有些”链上”交易所实际上是打包到中心化服务器处理的。它的永续合约交易深度和体验已经能和 Binance、Bybit 这些主流平台正面竞争。
对程序员来说，Hyperliquid 提供了一套相对干净的 REST + WebSocket API，覆盖了行情查询、下单、撤单、账户信息等核心操作。
基础信息
- API 基础地址：https://api.hyperliquid.xyz/info
- 交易类型：永续合约（Perpetual Futures）
- 认证方式：Ed25519 签名（大部分端点不需要认证，下单需要）
- 支持币种：BTC、ETH、SOL、XRP、LTC 等 40+ 个交易对
先跑通行情接口
行情接口不需要签名，直接调就行。先验证一下连通性：
curl -s -X POST https://api.hyperliquid.xyz/info \\
-H "Content-Type: application/json" \\
-d '{"type":"meta"}'
返回结果大概是这个样子：
{
"universe": [
{"name": "BTC", "szDecimals": 5, "maxLeverage": 40},
{"name": "ETH", "szDecimals": 4, "maxLeverage": 25},
{"name": "SOL", "szDecimals": 2, "maxLeverage": 20},
…
]
}
这里 szDecimals 是下单数量的小数精度，下单时要按这个来。
实时价格
获取所有币种当前中间价：
curl -s -X POST https://api.hyperliquid.xyz/info \\
-H "Content-Type: application/json" \\
-d '{"type":"allMids"}'
返回每个交易对的价格字典，{"BTC":"64250.5","ETH":"3521.34",…}。
订单簿深度
curl -s -X POST https://api.hyperliquid.xyz/info \\
-H "Content-Type: application/json" \\
-d '{"type":"orderbook","coin":"BTC"}'
返回订单簿的 bids 和 asks，各 10 档。
下单：需要签名
这是 Hyperliquid 和大多数去中心化交易所最麻烦的部分——下单需要 Ed25519 签名。
签名流程
签名的内容是对一段 JSON 做 SHA256 hash，然后用你的 Ed25519 私钥签名。官方推荐的做法是：
具体来说，下单时构造的 payload 结构大概这样：
{
"type": "order",
"asset": 1, // BTC = 1, ETH = 2 … 查 meta 里的 marginTableId
"cloid": "0x…", // 客户端订单ID，可选
"side": "B", // B = 买入, S = 卖出
"sz": "0.01", // 数量，注意精度
"px": "64000", // 价格
"ordType": "Limit", // Limit / Market / …
"reduceOnly": false,
"timeInForce": "Gtc"
}
然后对这个结构做 SHA256，再签名。
Python 实现
用 nacl 库来做签名：
import hashlib
import json
import base64
from nacl.signing import SigningKey
SIGNING_KEY = SigningKey(bytes) # 你的 Ed25519 私钥（32字节）
def sign_order(order_payload: dict) -> str:
# 1. 序列化并 hash
msg = json.dumps(order_payload, separators=(",", ":"), ensure_ascii=False)
h = hashlib.sha256(msg.encode()).digest()
# 2. Ed25519 签名
signed = SIGNING_KEY.sign(h)
# signed.message == h + signature (64字节)
signature_b64 = base64.b64encode(signed.message[32:]).decode()
return signature_b64
然后把签名附到请求里发出去：
import requests
def place_order(order_payload: dict, signature: str, vault_address: str = None):
payload = {
"type": "order",
"payload": order_payload,
"signature": signature,
}
if vault_address:
payload["vaultAddress"] = vault_address
resp = requests.post(
"https://api.hyperliquid.xyz/exchange",
headers={"Content-Type": "application/json"},
json=payload
)
return resp.json()
注意：签名私钥不要硬编码在代码里，也不要传上网。建议用环境变量或者专门的密钥管理工具。
查持仓和账户余额
curl -s -X POST https://api.hyperliquid.xyz/info \\
-H "Content-Type: application/json" \\
-d '{
"type": "positions",
"account": "你的钱包地址"
}'
返回你的当前持仓列表，每个持仓包含币种、方向、数量、 entry 价格、未实现盈亏等。
WebSocket 实时行情
REST 接口适合查询，但做交易系统肯定需要 WebSocket 实时推送。Hyperliquid 的 WebSocket 地址：
wss://api.hyperliquid.xyz/ws
订阅订单簿更新：
import json
import websocket
def on_message(ws, message):
data = json.loads(message)
print(data)
def on_open(ws):
# 订阅 BTC 订单簿
ws.send(json.dumps({
"type": "subscribe",
"channel": "orderbook",
"subscription": {"coin": "BTC", "depth": 10}
}))
ws = websocket.WebSocketApp(
"wss://api.hyperliquid.xyz/ws",
on_message=on_message,
on_open=on_open
)
ws.run_forever()
几个实际踩过的坑
1. 精度问题
szDecimals 每个币种不一样，比如 BTC 是 5 位小数，SOL 是 2 位。下单数量必须严格按这个精度来，否则会报 insufficient precision 之类的错。建议用 Python 的 Decimal 类型处理。
2. 签名内容要一模一样
JSON 序列化时 key 的顺序、是否有空格都会导致 hash 结果不同。官方要求用 json.dumps(obj, separators=(",", ":")) 这种紧凑格式，顺序也要按字母排序。
3. px 参数的学问
价格也是带精度的，不是随便填整数就行。要先查一下当前币种的 szDecimals 和价格范围。
4. 测试网
Hyperliquid 有测试网（testnet），在接入真实资金之前强烈建议先用测试网跑通完整流程，包括充值模拟资金、下单、撤单。测试网 API 地址通常是分开的，注意区分。
5. 网络波动
链上交易所的响应会比纯中心化服务慢一些，而且网络波动时可能超时。建议下单时做好重试逻辑，但同一个 cloid 只下一次单，防止重复。
结语
Hyperliquid的 API 设计整体算是清晰的，坑主要在签名这一块。一旦跑通，下单、撤单、查持仓这些操作都很直接。如果你有量化交易或者跟单机器人的开发需求，这套 API 基本够用。
接入前确保熟悉测试网操作，第一次真金白银之前，测试网的每一类订单都跑一遍。
hyperliquidapp.hyperliquid.xyz/join/ABC000
https://link.zhihu.com/?target=https%3A//app.hyperliquid.xyz/join/ABC000
