用 Hyperliquid SDK 做程式化交易

2026年5月6日

hyperliquid sdk
hyperliquid programmatic trade
hyperliquid python sdk
hyperliquid api 程式化交易
鏈上永續合約機械人

程式化交易已經唔再只係機構專用工具。對有基本編程能力嘅散戶同開發者嚟講，透過 SDK 同 API 自動落盤、查倉、做風控，已經變得相當可行。Hyperliquid 作為鏈上永續合約交易所，提供 REST API 同 WebSocket 介面，官方及社群亦有維護多語言 SDK，令開發者可以用相對少量嘅代碼完成下單、查倉位、處理錯誤等核心流程。

本文會由環境準備開始，介紹點樣用 Python 或 JavaScript SDK 建立一套較可靠嘅程式化交易流程，並說明點解喺生產環境入面，將 OneKey 硬件錢包作為簽名層，係保護資金安全嘅重要一步。對唔想自己寫代碼、但想體驗鏈上永續合約交易嘅用戶，OneKey Perps 亦係更直接、實用嘅入口。

點解揀 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 示例（偽代碼）：

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

實務上，撤單同改單要處理「訂單已成交」、「訂單不存在」、「網絡延遲導致狀態未同步」等情況，唔應該假設每次 API 回應都會即時反映最終狀態。

錯誤處理最佳實踐

程式化交易入面，穩健嘅錯誤處理同交易邏輯一樣重要。常見問題包括：

網絡超時或 API 暫時不可用；
請求頻率過高觸發限速；
保證金不足；
訂單價格或數量唔符合規則；
本地策略狀態同實際持倉出現偏差。

一個簡單嘅重試框架可以咁寫：

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 錢包或授權子帳戶，限制其只可以喺指定帳戶下操作，從而降低單一服務被攻擊時嘅風險敞口。

OneKey Perps：唔寫代碼都可以交易鏈上永續合約

如果你主要目標係體驗 Hyperliquid 類型嘅鏈上永續合約交易，而唔係自行開發機械人，OneKey Perps 會係更實際嘅起點。你可以透過 OneKey App 連接錢包、管理資產，並使用 OneKey Perps 進行永續合約交易，減少自行處理 SDK、簽名、API 錯誤同節點連接嘅複雜度。

對開發者而言，OneKey Perps 亦可以作為人工監控同備援操作入口：當自動化策略暫停、需要檢查倉位或手動調整風險時，一個可靠嘅圖形化介面會比純命令行更直觀。

你可以下載或打開 OneKey App，了解 OneKey Perps 嘅交易流程，先用小額資金熟悉保證金、槓桿、資金費率同強平機制，再決定是否進一步建立自動化策略。

常用輔助工具與資源

Hyperliquid 官方文檔：查看接口規格、欄位說明、限速策略同最新 SDK 資訊；
OneKey 官方資源：了解硬件錢包、OneKey App 同 OneKey Perps；
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 官方文檔了解最新限速策略。一般建議喺每次請求之間加入適當延遲，並實作令牌桶或滑動窗口等限速控制，避免因請求過密而導致訂單失敗。

結語：由腳本到生產系統

Hyperliquid SDK 降低咗程式化交易門檻，但由「可以運行嘅腳本」變成「可信賴嘅生產系統」，仍然需要喺簽名安全、錯誤處理、風控邏輯、監控告警同人工介入流程上做好準備。

如果你唔想由零開始寫代碼，但想體驗鏈上永續合約交易，可以先下載或打開 OneKey App，使用 OneKey Perps 熟悉交易流程同風險管理。對有開發能力嘅團隊，將 OneKey 硬件錢包作為簽名後端納入交易機械人架構，亦係鏈上交易入面較穩健嘅密鑰管理方案之一。

風險提示：程式化交易涉及高度複雜嘅技術與市場風險，永續合約交易具有槓桿屬性，可能導致超過初始投入嘅虧損。本文只供技術參考，不構成投資、法律或財務建議。請喺充分了解相關風險後，按自身風險承受能力審慎決策。加密貨幣市場波動劇烈，過往表現不代表未來收益。