用 Hyperliquid SDK 做程序化交易

• hyperliquid sdk

• hyperliquid programmatic trade

• hyperliquid python sdk

• hyperliquid api 程序化交易

• 链上永续合约机器人

locale: zh-CN

程序化交易已经从机构专属工具演变为每个有编程基础的散户都能触及的领域。Hyperliquid 作为链上永续合约交易所，提供了完整的 REST 与 WebSocket 接口，官方和社区也维护了多语言 SDK，让开发者可以用几十行代码就完成下单、查仓位、处理错误等核心操作。本文将从环境搭建开始，逐步介绍如何用 Python 或 JavaScript SDK 构建一套可靠的程序化交易流程，并说明为何在生产环境中引入 OneKey 硬件钱包 作为签名层是保护资金安全的关键一步。

为什么选择 Hyperliquid 做程序化交易

与中心化交易所相比，Hyperliquid 的优势在于：交易结算在链上完成，资金无需托管给第三方；订单簿采用链下撮合、链上结算的混合架构，兼顾速度与透明度；API 接口设计简洁，官方文档持续更新，社区活跃度高。对于量化交易者而言，这意味着可以在保留自托管主权的同时享受接近中心化交易所的交易体验。

环境准备与 SDK 安装

Python 环境

截至本文，社区维护的 Python SDK 可通过 pip 安装。建议在虚拟环境中操作，避免依赖冲突：

python -m venv hl_env

source hl_env/bin/activate

pip install hyperliquid-python-sdk

SDK 源码托管在 OneKey GitHub 的生态合作仓库以及 Hyperliquid 官方组织下，参考官方文档获取最新仓库地址。

JavaScript/TypeScript 环境

对于偏好 Node.js 的开发者：

npm install @nktkas/hyperliquid

或使用官方维护包，以 npm registry 最新版本为准

TypeScript 用户可以直接导入类型定义，IDE 补全体验更佳。

连接 API 与初始化客户端

认证方式

Hyperliquid 使用私钥签名来认证交易请求。每笔订单都需要用钱包私钥对消息进行 EIP-712 结构化签名，确保请求不可伪造。

Python 示例（伪代码）：

from hyperliquid.exchange import Exchange

from hyperliquid.info import Info

from eth_account import Account

从环境变量读取私钥，切勿硬编码

private_key = os.environ["HL_PRIVATE_KEY"]

account = Account.from_key(private_key)

info = Info(base_url="https://api.hyperliquid.xyz")

exchange = Exchange(account, base_url="https://api.hyperliquid.xyz")

生产环境强烈建议使用 OneKey 硬件钱包 替代软件私钥，私钥永不离开硬件安全芯片，即使服务器被攻陷也无法导出密钥，详见后文。

查询市场数据与账户状态

获取行情快照

获取所有永续合约的元信息与当前价格

meta_and_asset_ctx = info.meta_and_asset_ctxs()

返回包含 markPx（标记价格）、funding（资金费率）等字段的列表

查询持仓与余额

user_state = info.user_state(account.address)

user_state 包含 marginSummary（保证金汇总）和 assetPositions（各币对持仓）

for pos in user_state["assetPositions"]:

print(pos["position"]["coin"], pos["position"]["szi"])  # 币对与持仓量

下单操作

市价单

order_result = exchange.market_open(

coin="BTC",

is_buy=True,

sz=0.001,   # 下单数量

slippage=0.01  # 最大允许滑点 1%

)

print(order_result)

限价单

order_result = exchange.order(

coin="ETH",

is_buy=False,

sz=0.1,

limit_px=3200.0,  # 限价

order_type={"limit": {"tif": "Gtc"}}  # Good Till Cancel

)

tif 字段支持 Gtc（一直有效）、Ioc（立即成交或取消）、Alo（仅挂单）等选项，根据策略需求选择。

批量下单

做市或网格策略通常需要一次提交多笔订单，SDK 支持批量接口以减少网络往返：

orders = [

{"coin": "BTC", "is_buy": True,  "sz": 0.001, "limit_px": 60000, "order_type": {"limit": {"tif": "Gtc"}}},

{"coin": "BTC", "is_buy": False, "sz": 0.001, "limit_px": 61000, "order_type": {"limit": {"tif": "Gtc"}}},

]

result = exchange.bulk_orders(orders)

撤单与修改订单

撤单需要提供 coin 和 oid（订单 ID）

cancel_result = exchange.cancel(coin="BTC", oid=123456789)

修改订单（cancel + replace）

modify_result = exchange.modify_order(

oid=123456789,

coin="BTC",

is_buy=True,

sz=0.002,

limit_px=59500,

order_type={"limit": {"tif": "Gtc"}}

)

错误处理最佳实践

程序化交易中，健壮的错误处理与普通业务逻辑同等重要。常见错误类型包括：

import time

def place_with_retry(exchange, max_retries=3, kwargs):

for attempt in range(max_retries):

try:

return exchange.order(kwargs)

except Exception as e:

if attempt == max_retries - 1:

raise

wait = 2  attempt  # 指数退避：1s, 2s, 4s

time.sleep(wait)

使用 WebSocket 实时监听成交

REST 轮询适合低频策略，高频场景需要 WebSocket 推送：

from hyperliquid.websocket_manager import WebsocketManager

def on_fill(data):

print("成交回调:", data)

ws = WebsocketManager(base_url="wss://api.hyperliquid.xyz")

ws.subscribe(

{"type": "userFills", "user": account.address},

callback=on_fill

)

ws.start()

完整的 WebSocket 订阅格式请参考 Hyperliquid 官方文档。

用 OneKey 硬件钱包保护生产机器人

软件钱包（热钱包）的私钥存储在内存或磁盘中，服务器一旦被攻击，资金可能瞬间清空。对于管理真实资金的生产机器人，推荐的架构是：

将 OneKey 硬件钱包 连接到签名服务器

机器人逻辑生成待签名的交易消息

消息发送至 OneKey，在硬件安全元件中完成签名

签名结果返回机器人，提交到 Hyperliquid

这种架构下，私钥始终在硬件中，无法通过软件层面导出。EIP-712 结构化签名协议确保 OneKey 屏幕可以显示待签名内容，用户可以人工审核每笔交易。

另外，建议为机器人账户设置专用的 API Agent 钱包（Hyperliquid 支持授权子账户），限制其只能在指定账户下操作，进一步控制风险敞口。

常用辅助工具与资源

Hyperliquid 官方文档：接口规范、字段说明

OneKey 官网：硬件钱包产品介绍

WalletConnect 文档：如需通过 WalletConnect 协议桥接签名

常见问题

Q1：SDK 和直接调用 REST API 有什么区别？

答：SDK 封装了签名逻辑、请求格式化和常见错误处理，减少了样板代码。直接调用 REST API 灵活性更高，但需要自行实现 EIP-712 签名。初学者推荐使用 SDK，熟悉后可按需降级到原生 HTTP 调用。

Q2：程序化交易是否需要 KYC？

答：Hyperliquid 是去中心化协议，截至本文无需 KYC，通过钱包地址即可交易。但请关注所在地区的监管政策，合规风险由用户自行承担。

Q3：如何防止机器人在极端行情下亏损过大？

答：建议在策略层面实现以下保护：设置最大亏损阈值（达到后暂停下单）、监控未实现亏损与账户净值比例、使用止损单（Sl 订单类型）、以及定时检查持仓是否与预期一致。

Q4：OneKey 硬件钱包如何与自动化脚本集成？

答：可通过 OneKey 官方 SDK 调用硬件签名接口，也可以通过 USB/Bluetooth 连接结合 eth_sign 接口完成签名。生产部署时，通常将签名服务单独部署，与交易逻辑解耦，降低攻击面。

Q5：批量下单接口有频率限制吗？

答：参考官方文档了解最新限速策略。一般建议在每次请求之间加入适当延迟，并实现令牌桶或滑动窗口算法控制请求频率，避免触发限速导致订单失败。

结语：从脚本到生产系统

Hyperliquid SDK 让程序化交易的门槛大幅降低，但从"能跑的脚本"到"可信赖的生产系统"，还需要在签名安全、错误处理、风控逻辑上做足功课。如果你希望在不写代码的情况下体验链上永续合约交易，OneKey Perps 提供了流畅的界面化交易入口，结合硬件钱包的安全保障，是散户用户的理想起点。对于有开发能力的团队，将 OneKey 作为签名后端纳入机器人架构，是目前链上交易中最稳健的密钥管理方案之一。

立即访问 OneKey 官网 了解更多，或前往 Hyperliquid App 开始你的程序化交易之旅。

风险提示：程序化交易涉及高度复杂的技术与市场风险，永续合约交易具有杠杆属性，可能导致超过初始投入的亏损。本文仅供技术参考，不构成任何投资建议。请在充分了解相关风险的前提下，根据自身风险承受能力谨慎决策。加密资产市场波动剧烈，过往表现不代表未来收益。