接入 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 私钥签名。官方推荐的做法是：

1. 生成 Ed25519 密钥对（只用于 Hyperliquid，不要用钱包主私钥）
2. 在 Hyperliquid 前端授权你的公钥（只需要授权一次）
3. 之后每次下单用私钥签名

具体来说，下单时构造的 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/ABC000https://link.zhihu.com/?target=https%3A//app.hyperliquid.xyz/join/ABC000