Hyperliquid Python SDK 中文文档：安装、配置与完整示例

官方的 hyperliquid-python-sdk 把签名、请求封装、WebSocket 连接全帮你处理好了，是写 Hyperliquid 交易脚本和机器人最省事的方式。手动拼 REST 请求容易在签名那一步翻车，能用 SDK 就别自己造轮子。

这篇是 Python SDK 的完整中文文档。想看全部端点和协议细节，配合 API 概览 一起看。

安装

pip install hyperliquid-python-sdk

SDK 依赖 eth-account 做钱包签名，安装时会自动带上。建议在虚拟环境里装，Python 3.9 以上。

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

主要模块

模块	用途
hyperliquid.info.Info	Info API 封装——查行情、账户、持仓、订单
hyperliquid.exchange.Exchange	Exchange API 封装——下单、撤单、转账（自动签名）
hyperliquid.websocket_manager.WebsocketManager	WebSocket 连接和订阅管理
hyperliquid.utils.signing	签名相关工具函数
hyperliquid.utils.constants	主网/测试网 URL、链 ID 等常量

记住一个原则：查数据用 Info，下单交易用 Exchange。Info 不需要私钥，Exchange 必须用钱包初始化。

快速上手模板

下面这段可以直接跑通，覆盖最常用的几个操作。私钥务必从环境变量读，别硬编码进代码。

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)}")

常用操作

查行情和账户

# 实时行情（标记价、资金费率、24h 成交量）
ctx = info.meta_and_asset_ctxs()

# L2 订单簿
book = info.l2_snapshot("ETH")

# 历史 K 线
candles = info.candles_snapshot("ETH", "1h", start_time, end_time)

# 用户成交历史
fills = info.user_fills(wallet.address)

下市价单

# 市价买入 0.1 ETH（is_buy=True）
order_result = exchange.market_open("ETH", True, 0.1)
print(order_result)

下限价单

# 在 3000 挂限价买单，0.1 ETH，GTC 长期有效
order_result = exchange.order(
    "ETH", True, 0.1, 3000,
    {"limit": {"tif": "Gtc"}}
)

tif（time in force）可选 Gtc（长期有效）、Ioc（立即成交否则撤销）、Alo（只做 Maker）。

撤单

# 撤指定订单（需要 oid）
exchange.cancel("ETH", oid)

# 撤掉某交易对的所有挂单
for o in info.open_orders(wallet.address):
    exchange.cancel(o["coin"], o["oid"])

WebSocket 实时推送

要做实时策略，用 WebSocket 订阅比轮询 REST 高效得多，延迟低一个量级。

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

info = Info(constants.MAINNET_API_URL)

# 订阅 ETH 订单簿
info.subscribe(
    {"type": "l2Book", "coin": "ETH"},
    lambda msg: print(msg)
)

订单状态、用户成交这类需要授权的订阅，SDK 会用初始化时的钱包自动处理签名。

测试网先跑通

上主网前强烈建议先在测试网验证逻辑，测试网 USDC 通过水龙头免费领。只需把 URL 常量换掉：

# 主网
info = Info(constants.MAINNET_API_URL)
exchange = Exchange(wallet, constants.MAINNET_API_URL)

# 测试网
info = Info(constants.TESTNET_API_URL)
exchange = Exchange(wallet, constants.TESTNET_API_URL)

常见报错排查

报错 / 现象	原因和解决
ModuleNotFoundError: No module named 'hyperliquid'	包名装错了，应该 pip install hyperliquid-python-sdk
下单返回 Insufficient margin	保证金不够，或杠杆设置和仓位不匹配
价格被拒 / Invalid price	价格精度不对，要按交易对的 tick size 四舍五入再下单
签名相关报错	私钥格式不对，或用了主钱包但该地址没授权 Agent
WebSocket 频繁断开	加心跳和断线重连，别假设连接永远在

其它语言的 SDK

语言	仓库
Python（官方）	hyperliquid-dex/hyperliquid-python-sdk
Rust（官方）	hyperliquid-dex/hyperliquid-rust-sdk
TypeScript（社区）	nktkas/hyperliquid

相关页面

• API 概览 — REST、WebSocket 全部端点和协议细节
• API 端点速查 — 每个端点的参数和返回字段
• 交易机器人 — 用 SDK 搭自动化交易系统
• 资金费率 — 用 API 拉费率数据做套利监控
• HLP 金库 — 程序化做市和金库策略