Hyperliquid API 中文文档教程：REST、WebSocket、Python SDK 完整指南

Hyperliquid 有完整的链上 API，覆盖行情查询、订单管理、账户操作和实时推送。适合写交易机器人、做数据分析、接入自己的交易系统。这篇是 Hyperliquid API 的中文完整文档，包含端点表、代码示例和踩坑提醒。

API 三种类型一图看懂

类型	协议	用途	是否需签名	典型延迟
Info API	REST	查询行情、账户、订单	否	50-200ms
Exchange API	REST	下单、撤单、转账	是（钱包签名）	100-300ms
WebSocket	WS	实时行情、订单状态推送	部分订阅需签名	10-50ms

简单原则：查数据用 Info，做交易用 Exchange，要实时用 WebSocket。生产策略通常三个都用。

端点 URL

环境	REST 基地址	WebSocket 基地址
主网	https://api.hyperliquid.xyz	wss://api.hyperliquid.xyz/ws
测试网	https://api.hyperliquid-testnet.xyz	wss://api.hyperliquid-testnet.xyz/ws

强烈建议先在测试网跑通再上主网。测试网 USDC 通过水龙头免费领取。

Info API（查询类）

主要端点

所有 Info 端点都是 POST /info，通过 body 的 type 字段区分。每个 type 的详细请求参数和返回字段见 API 端点速查。

type 字段	返回内容
meta	所有交易对元数据（最大杠杆、最小单位等）
metaAndAssetCtxs	meta + 实时行情（标记价、24h 成交、资金费率）
allMids	所有交易对的中间价
l2Book	指定交易对的 L2 订单簿
candleSnapshot	K 线历史数据
userState	用户账户状态（余额、持仓）
openOrders	用户当前挂单
userFills	用户成交历史
userFunding	用户资金费率历史
userRateLimit	用户当前速率限制状态
historicalOrders	用户历史订单
subAccounts	子账户列表
vaultDetails	金库详情
delegations	质押委托情况

示例：查账户状态

import requests

url = "https://api.hyperliquid.xyz/info"
payload = {
    "type": "userState",
    "user": "0xYourAddress"
}

response = requests.post(url, json=payload)
data = response.json()

# 账户总价值
print(f"账户总价值: {data['marginSummary']['accountValue']}")
# 当前持仓
for position in data['assetPositions']:
    pos = position['position']
    print(f"{pos['coin']}: {pos['szi']} @ 均价 {pos['entryPx']}")

示例：查实时行情

payload = {"type": "metaAndAssetCtxs"}
data = requests.post(url, json=payload).json()

universe = data[0]['universe']  # 交易对元数据
ctxs = data[1]                   # 实时上下文

for asset, ctx in zip(universe, ctxs):
    print(f"{asset['name']}: 标记价 {ctx['markPx']}, "
          f"资金费率 {ctx['funding']}, "
          f"未平仓 {ctx['openInterest']}")

Exchange API（交易类）

主要端点

所有 Exchange 操作都通过 POST /exchange，body 包含 action、nonce、signature 三个字段。

action 类型	用途
order	下单（单笔或批量）
cancel	撤单（按订单 ID）
cancelByCloid	撤单（按客户端订单 ID）
modify	修改订单
batchModify	批量修改
updateLeverage	调整杠杆
updateIsolatedMargin	调整逐仓保证金
usdSend	转账 USDC
withdraw3	提现
spotSend	现货转账
vaultTransfer	金库存取
approveAgent	授权 agent wallet
approveBuilderFee	授权 builder code 抽成

认证机制：钱包签名

Exchange API 要求每个请求用钱包私钥签名。Hyperliquid 用 EIP-712 typed data 签名标准。

签名流程：

1. 构造 action 对象（如下单参数）
2. 用 msgpack 序列化为字节
3. 用 keccak256 哈希
4. 用钱包私钥签名哈希
5. 附 nonce（毫秒时间戳）和 signature 一起发送

手动实现签名容易出错，强烈建议直接用 Python SDK。

示例：下市价单

from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
from eth_account import Account

# 私钥加载（生产环境别硬编码！用环境变量）
wallet = Account.from_key("0xYourPrivateKey")
exchange = Exchange(wallet, constants.MAINNET_API_URL)

# 市价买入 0.1 ETH
result = exchange.market_open(
    name="ETH",       # 交易对
    is_buy=True,      # True=买，False=卖
    sz=0.1,           # 数量
    slippage=0.01     # 1% 滑点容忍
)
print(result)

示例：下限价单

result = exchange.order(
    name="BTC",
    is_buy=False,           # 卖
    sz=0.01,                # 数量
    limit_px=70000.0,       # 限价
    order_type={"limit": {"tif": "Gtc"}},  # Good-Till-Canceled
    reduce_only=False,
    cloid=None              # 可选客户端订单 ID
)
print(result)

订单类型（tif）参数

tif 值	含义	用途
Gtc	Good Till Canceled	一直挂着直到主动撤
Ioc	Immediate Or Cancel	能成多少成多少，剩下立即撤
Alo	Add Liquidity Only	只做 maker，不吃单

示例：批量下单

orders = [
    {
        "coin": "ETH",
        "is_buy": True,
        "sz": 0.1,
        "limit_px": 3000.0,
        "order_type": {"limit": {"tif": "Gtc"}},
        "reduce_only": False
    },
    {
        "coin": "ETH",
        "is_buy": False,
        "sz": 0.1,
        "limit_px": 3500.0,
        "order_type": {"limit": {"tif": "Gtc"}},
        "reduce_only": False
    }
]
result = exchange.bulk_orders(orders)

示例：撤单和改单

# 撤指定订单
exchange.cancel("ETH", oid=12345678)

# 批量撤
exchange.bulk_cancel([
    {"coin": "ETH", "oid": 12345678},
    {"coin": "BTC", "oid": 12345679}
])

# 改单
exchange.modify_order(
    oid=12345678,
    name="ETH",
    is_buy=True,
    sz=0.1,
    limit_px=3050.0,
    order_type={"limit": {"tif": "Gtc"}}
)

WebSocket（实时推送）

订阅类型

channel	内容	是否需登录
allMids	所有交易对中间价	否
l2Book	L2 订单簿增量更新	否
trades	公开成交流	否
candle	K 线增量	否
notification	系统通知	否
webData2	综合 web 数据	否
orderUpdates	用户订单状态变化	是
userEvents	用户事件（成交、强平等）	是
userFills	用户成交推送	是
userFundings	用户资金费推送	是

示例：订阅订单簿

import asyncio
import websockets
import json

async def subscribe_book():
    uri = "wss://api.hyperliquid.xyz/ws"
    async with websockets.connect(uri) as ws:
        # 订阅 ETH 订单簿
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "ETH"}
        }))

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_book())

示例：订阅用户成交

# 需要钱包签名授权（通过 SDK 自动处理）
from hyperliquid.websocket_manager import WebsocketManager

def on_user_fills(msg):
    for fill in msg["data"]:
        print(f"成交: {fill['coin']} {fill['side']} {fill['sz']} @ {fill['px']}")

ws = WebsocketManager(constants.MAINNET_API_URL)
ws.subscribe(
    {"type": "userFills", "user": "0xYourAddress"},
    on_user_fills
)
ws.start()

WebSocket 最佳实践

1. 单连接多订阅：一个 WS 连接订阅多个 channel，不要每个 channel 开一个连接
2. 心跳保活：服务器没明确 ping/pong，但建议每 30 秒发一次任意消息保持连接
3. 断线重连：网络不稳定时必备，建议指数退避（1s → 2s → 4s → 8s → 30s）
4. 去重和顺序处理：L2 订单簿是增量推送，需要按序号合并到本地状态

Python SDK 完整安装

只用 Python？看专门的 Python SDK 中文文档，安装、模块、下单撤单、报错排查都更详细。下面是速览版。

官方 SDK 在 GitHub: hyperliquid-dex/hyperliquid-python-sdk。

# 安装
pip install hyperliquid-python-sdk

# 验证
python -c "import hyperliquid; print(hyperliquid.__version__)"

SDK 主要模块

模块	用途
hyperliquid.info.Info	Info API 封装
hyperliquid.exchange.Exchange	Exchange API 封装（含签名）
hyperliquid.websocket_manager.WebsocketManager	WS 连接管理
hyperliquid.utils.signing	签名工具函数
hyperliquid.utils.constants	URL、链 ID 等常量

完整入门模板

import os
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants
from eth_account import Account

# 加载私钥（环境变量优先）
private_key = os.getenv("HYPERLIQUID_PRIVATE_KEY")
if not private_key:
    raise ValueError("请设置 HYPERLIQUID_PRIVATE_KEY")

wallet = Account.from_key(private_key)
print(f"钱包地址: {wallet.address}")

# 初始化 Info 和 Exchange
info = Info(constants.MAINNET_API_URL)
exchange = Exchange(wallet, constants.MAINNET_API_URL)

# 1. 查账户
user_state = info.user_state(wallet.address)
print(f"账户价值: {user_state['marginSummary']['accountValue']} USDC")

# 2. 查所有交易对
meta = info.meta()
print(f"共 {len(meta['universe'])} 个永续合约")

# 3. 查 ETH 行情
all_mids = info.all_mids()
print(f"ETH 中间价: {all_mids['ETH']}")

# 4. 查当前挂单
open_orders = info.open_orders(wallet.address)
print(f"当前挂单数: {len(open_orders)}")

速率限制

Hyperliquid 用权重制速率限制，不是简单的”每秒 N 次”。

操作类型	权重
Info 查询（轻）	1-20
Info 查询（重，如订单簿）	40-100
Exchange 操作（下单/撤单）	1
批量操作	按批量大小累加

每用户每分钟限额：约 1,200 权重。超出会返回 429 状态码。

查当前速率状态：

rate = info.user_rate_limit(wallet.address)
print(f"已用: {rate['nRequestsUsed']}, 上限: {rate['nRequestsCap']}")

速率优化建议

1. 缓存元数据：meta 每天调一次就够，别每次下单都查
2. 批量操作：能批量就批量，单次批量 100 个订单比 100 次单笔请求快得多
3. WebSocket 替代轮询：实时数据用 WS 推送，别用 REST 轮询
4. 本地维护订单簿：L2 增量推送 + 本地合并，避免反复全量拉取

认证最佳实践

Agent Wallet（强烈推荐）

不要直接用你的主钱包私钥跑机器人。建议用 Agent Wallet：

1. 在 Hyperliquid 界面创建一个 Agent Wallet（独立钱包，无资金）
2. 主钱包授权 Agent Wallet 代为下单（approveAgent action）
3. 机器人用 Agent Wallet 的私钥操作

好处：

• Agent Wallet 泄露不会丢资金（它无法提现，只能下单撤单）
• 可以随时在前端撤销授权
• 多策略可以用不同 Agent Wallet 隔离

私钥管理

# ❌ 错误：硬编码私钥
PRIVATE_KEY = "0xabcd1234..."

# ✅ 正确：环境变量
private_key = os.getenv("HYPERLIQUID_PRIVATE_KEY")

# ✅ 更好：密钥管理服务（AWS Secrets Manager、Vault）
from boto3 import client
secret = client('secretsmanager').get_secret_value(SecretId='hl-bot-key')
private_key = secret['SecretString']

常见错误码

错误	含义	处理
Insufficient margin	保证金不足	减小订单或加资金
Order would immediately match	Alo 订单会立即成交	调整限价
Tick size violation	价格不符合最小价格变动	用 meta 查 szDecimals 和 pxDecimals
Reduce-only order increased position	reduce-only 单实际会加仓	检查 sz 和持仓方向
Trigger price invalid	触发价无效（止盈止损）	多头止盈价 > 当前价，止损价 < 当前价
Order has invalid price	价格偏离过大	检查标记价
Rate limited	速率超限	退避重试
Bad signature	签名错误	检查 nonce 和私钥

价格精度处理

Hyperliquid 对价格小数位有严格限制。从 meta 获取每个币种的精度：

meta = info.meta()
for asset in meta['universe']:
    name = asset['name']
    sz_decimals = asset['szDecimals']  # 数量小数位
    # 价格精度规则：max(5 - sz_decimals, 0) 位小数
    px_decimals = max(5 - sz_decimals, 0)
    print(f"{name}: sz {sz_decimals} 位, px {px_decimals} 位")

# 实际下单前对价格做四舍五入
import decimal
def round_px(px, decimals):
    return float(decimal.Decimal(str(px)).quantize(
        decimal.Decimal(10) ** -decimals
    ))

price = round_px(3147.5891, 4)  # → 3147.5891 或截到合法精度

测试网接入

测试网完全独立的 USDC 和合约，可以无成本测试策略。

from hyperliquid.utils import constants

# 主网
info = Info(constants.MAINNET_API_URL)

# 测试网
info = Info(constants.TESTNET_API_URL)

测试网 USDC 水龙头：Hyperliquid 测试网前端，连钱包后可以一键领取 1,000 USDC。

进阶：Builder Code（推荐人抽成）

如果你做的是面向用户的产品（前端、Telegram bot 等），可以申请 Builder Code，从用户成交手续费中抽成 0-10%。

# 用户授权你的 builder code 抽 1%（10 bps）
exchange.approve_builder_fee(
    builder="0xYourBuilderAddress",
    max_fee_rate="0.1%"
)

# 之后用户下单可以附带 builder
exchange.order(
    name="ETH", is_buy=True, sz=0.1, limit_px=3000.0,
    order_type={"limit": {"tif": "Gtc"}},
    builder={"b": "0xYourBuilderAddress", "f": 10}  # 10 bps
)

性能调优建议

针对高频策略：

1. 就近部署：API 服务器在亚洲（推测在新加坡或东京），机器人部署在 AWS ap-northeast-1 / ap-southeast-1 延迟最低
2. 持久连接：requests 库改用 requests.Session() 复用 TCP 连接
3. 异步并发：用 aiohttp + asyncio 替代同步请求，单进程能跑几十 QPS
4. 本地订单簿：维护本地 L2 状态，下单决策不依赖 REST 查询
5. 预计算签名：批量订单可以预先签名好，触发条件时直接发送

常见问题

Q: API 调用要付 gas 吗？

A: 不需要。Hyperliquid 的 L1 状态变更由验证者签名共识，用户提交订单只需要钱包签名，不消耗任何链上 gas。

Q: 撤单失败怎么办？

A: 通常是订单已成交或已撤。先用 info.open_orders 查当前挂单状态，再决定是否重新下单。

Q: 如何处理资金费率结算？

A: 资金费每小时结算一次（每 8 小时 3 次）。结算金额从账户保证金里扣或加。可通过 info.user_funding 查历史。

Q: 主网和测试网的区别？

A: 完全隔离的环境。测试网用的是测试 USDC（无价值），主网价格、订单、账户都跟测试网无关。

Q: 单个账户能跑多少个策略？

A: 受速率限制和保证金限制约束。建议每个独立策略用单独子账户（subaccount），互不影响保证金、独立计算 PnL。

安全检查清单

• 私钥用环境变量或密钥管理服务，不硬编码
• 用 Agent Wallet 替代主钱包跑机器人
• 私钥文件不提交到 Git（加 .gitignore）
• 生产代码加 try-catch，避免崩溃留下未撤订单
• 关键操作（如撤所有单）做幂等处理
• 监控账户余额，触底告警
• 定期检查 Agent Wallet 授权列表，撤销不用的
• 测试网完整跑过策略再上主网
• 主网上线时小资金小仓位先试

官方资源

• Hyperliquid 官方 API 文档
• Python SDK GitHub
• Rust SDK GitHub
• TypeScript SDK（社区）

相关页面

• API 端点速查 — 每个端点的参数和返回字段
• Python SDK 文档 — 安装到下单的完整 Python 示例
• 交易机器人指南 — 用 API 跑自动化策略
• 风险管理 — API 交易也要做风控
• 订单类型详解 — 限价、止盈止损、Scale Orders
• 优先费机制 — 高频场景需要懂的优先级排序