Hyperliquid API 入門：2026 年新手指南

2026年5月6日

如果你曾經想用程式化方式參與鏈上永續合約交易，Hyperliquid API 是目前鏈上 DEX 當中較接近中心化交易所體驗的選擇之一。它提供行情查詢、帳戶管理、落盤與撤單等接口，再配合 WebSocket 即時推送，足以支援由簡單量化策略到較複雜做市程式的不同需要。

本文面向第一次接觸 Hyperliquid API 的開發者，會介紹接口分類、認證方式、入門示例、常見錯誤與風險控制。若你只是想更方便地交易加密貨幣永續合約，而不是自行維護策略和簽名流程，較實際的做法是先使用 OneKey App 內的 OneKey Perps 完成交易、風險管理與錢包操作；API 則更適合有開發能力、並能承擔自動化交易風險的用戶。

Hyperliquid API 可以做甚麼

根據 Hyperliquid 官方文件，API 主要分為三大類：

  • 資訊查詢端點（Info Endpoints）：取得市場數據，包括目前訂單簿快照、近期成交紀錄、資金費率歷史、帳戶持倉和歷史訂單。這類接口毋須簽名，公開可用。
  • 交易端點（Exchange Endpoints）：執行落盤、撤單、修改持倉槓桿、調整保證金等寫入操作。這類接口需要對請求內容進行錢包簽名，安全要求較高。
  • WebSocket 即時推送：訂閱訂單簿變動、成交流、帳戶事件等即時數據流，適合需要低延遲反應的策略。

對一般交易者而言，API 並不是必需品。若你的目標是安全地管理錢包、查看倉位並參與永續合約交易，可以先由 OneKey Perps 開始；若之後需要自動化策略、數據分析或風控系統，再考慮接入 Hyperliquid API。

基礎 URL 與接口結構

Hyperliquid 的 REST API 基礎 URL 為：

https://api.hyperliquid.xyz

所有請求均使用 POST 方法，請求內容為 JSON 格式。Info 類接口發送至 /info，Exchange 類接口發送至 /exchange。

具體字段定義請以 Hyperliquid 官方文件為準。以下示例只作入門演示，實際使用前務必核對最新文件，特別是交易、簽名與訂單類型相關部分。

認證方式

Hyperliquid 的交易接口採用 EIP-712 結構化數據簽名，而不是傳統的 API Key + Secret 模式。這代表：

  • 你需要一個以太坊兼容錢包地址作為身份識別
  • 每筆交易請求都需要用對應私鑰簽名
  • 簽名直接證明請求來自該地址的授權持有人，毋須中間 API Key

這種設計減少了 API Key 被盜用的風險，但同時大幅提高了私鑰管理的重要性。一旦私鑰外洩，攻擊者可以構造合法簽名，直接操控你的帳戶。

這正是 OneKey 錢包適合發揮作用的地方。OneKey 硬件錢包會將私鑰隔離在安全芯片內，簽名在設備內完成，私鑰不會暴露予電腦、手機或網絡。對需要使用交易 API 的開發者，可以考慮使用專用地址或子帳戶處理 API 交易，並將主要資產與策略資金分隔。

如果你未準備好自行處理簽名、風控和自動化交易邏輯，建議先使用 OneKey Perps 進行實際交易操作。它更適合作為一般用戶的日常永續合約交易入口，而 API 則適合進一步開發及自動化場景。

資訊查詢示例：Python + curl

以下是一個查詢目前所有可交易資產元數據的簡單示例。

使用 curl：

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "meta"}'

使用 Python（requests 庫）：

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

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

print(json.dumps(data, indent=2))

返回結果包含所有可交易合約的基本資料，例如資產名稱、最大槓桿、最小落盤數量等字段。這類查詢完全公開，毋須任何認證，是學習 Hyperliquid API 的理想起點。

查詢帳戶持倉

查詢指定地址的持倉狀態同樣屬於 Info 類接口，需要提供錢包地址：

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

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

返回數據通常包含保證金餘額、各合約持倉量、未實現盈虧等資料。需要留意的是，這是公開可查的鏈上相關數據，任何人都可以查詢任意地址的持倉狀態。

WebSocket 即時訂閱

WebSocket 端點為：

wss://api.hyperliquid.xyz/ws

建立連線後，發送訂閱訊息即可開始接收即時推送：

import asyncio
import websockets
import json

async def subscribe_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(sub_msg))

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

asyncio.run(subscribe_orderbook())

可訂閱的數據類型包括 L2 訂單簿（l2Book）、近期成交（trades）、帳戶事件（userEvents，需要相關地址）、全局資金費率等。

常見錯誤與注意事項

請求格式錯誤是最常見問題。Hyperliquid API 對 JSON 字段的類型和命名相當嚴格，例如將整數寫成字串，或字段名稱大小階不一致，都可能導致請求被拒絕。錯誤訊息有時未必直觀，需要對照官方文件逐項排查。

簽名構造是另一個難點。EIP-712 簽名涉及類型定義、domain separator 等細節，手動實作容易出錯。建議優先使用官方或社群維護的 Hyperliquid SDK，例如 Python 或 JavaScript 版本，以減少重複造輪子和簽名錯誤。

時間戳同步亦需要留意。交易請求通常需要附帶目前時間戳，並有一定有效期。如果本地時鐘與網絡時間偏差過大，請求可能因過期而被拒絕。

網絡異常處理是生產環境必須考慮的部分。WebSocket 連線可能因網絡波動中斷，REST 請求亦可能遇到暫時性錯誤。策略程式需要具備自動重連、重試、錯誤記錄和告警機制。

速率限制概覽

Hyperliquid 對不同類型接口設有不同速率限制，實際數值請以官方文件最新版本為準。一般而言，Info 類查詢接口限制相對寬鬆，Exchange 類交易接口則較嚴格。

如果你的策略需要頻繁落盤和撤單，必須特別處理速率限制。遇到 429 錯誤時，應暫停請求並採用指數退避策略，而不是立即不斷重試，否則可能令問題惡化。

開發環境建議

在正式部署策略前，建議先做好以下準備：

  1. 先用小倉位實盤測試
    據報 Hyperliquid 目前未必提供獨立的永續合約測試網環境，因此首次測試應嚴格控制倉位規模，避免因程式錯誤造成不可承受損失。

  2. 將簽名密鑰與主要資產分隔
    可以建立專用子帳戶或獨立地址作 API 交易用途，將風險敞口控制在可接受範圍內。配合 OneKey 錢包的多帳戶管理功能，可以更方便地分隔長期持有資產、日常交易資金和 API 策略資金。

  3. 先用 OneKey Perps 熟習交易流程
    對新手來說，直接寫 API 交易程式之前，應先理解永續合約、保證金、資金費率、強平風險和槓桿影響。OneKey Perps 可作為較實際的起點，讓你在錢包環境內管理交易，而不是一開始就承擔自動化策略的額外技術風險。

  4. 參考開源實作
    OneKey GitHub 展示了錢包簽名與應用層集成方式，對開發者有一定參考價值。實際接入 Hyperliquid API 時，仍應以 Hyperliquid 官方文件和最新 SDK 為準。

FAQ

Q1：Hyperliquid API 需要註冊帳戶嗎？

不需要傳統意義上的註冊。你只需要一個以太坊兼容錢包地址，該地址在 Hyperliquid 完成首次操作，例如充值後，即可使用 API。整個過程毋須電郵註冊或 KYC。

Q2：用 Python 調用 Hyperliquid API 有現成 SDK 嗎？

有。官方和社群均有 Python SDK 可用，建議到 Hyperliquid 官方 GitHub 或官方文件查找最新維護版本。使用 SDK 可以大幅簡化簽名構造、請求格式和錯誤處理。

Q3：WebSocket 斷線後應如何自動重連？

建議在 WebSocket 客戶端加入心跳檢測，例如定期發送 ping，並實作自動重連邏輯。連線中斷後，可在短暫等待後重新建立連線並重新訂閱所需頻道。實際等待時間可採用指數退避，避免在服務端故障期間造成大量重連請求。

Q4：API 交易的資金安全如何保障？

API 交易安全本質上取決於私鑰保管方式。使用 OneKey 硬件錢包進行簽名，可以令私鑰不暴露於聯網設備。除此之外，亦建議使用 API 專用帳戶、設定合理倉位上限、定期檢查未完成訂單和持倉狀態，並為策略加入風控停機條件。

Q5：Hyperliquid API 支援條件單和止蝕單嗎？

Hyperliquid 支援觸發單（Trigger Order）類型，包括止蝕和止賺邏輯。具體參數和觸發條件請參考官方文件中 Order Type 的詳細說明。若需要更複雜的條件邏輯，也可以在策略層面透過監控價格和持倉狀態自行實作。

Q6：新手應該先用 API 還是 OneKey Perps？

如果你主要目標是參與加密貨幣永續合約交易，而不是開發自動化策略，建議先使用 OneKey Perps。它較適合日常交易流程，亦能幫助你理解持倉、槓桿、保證金和風險控制。當你清楚了解交易機制並有能力處理程式、簽名和風控後，再接入 Hyperliquid API 會較穩妥。

總結

Hyperliquid API 為開發者提供一套功能完整、文件相對清晰的鏈上 DEX 接口。Info 類接口適合建立行情監控和數據分析工具；Exchange 類接口配合 WebSocket，則可支援由簡單跟單到較複雜做市的自動化策略。

不過，API 交易不是低風險捷徑。EIP-712 簽名機制要求開發者嚴肅處理私鑰安全，而永續合約本身亦涉及槓桿、強平和市場波動風險。對大部分用戶而言，較實際的路徑是先下載並使用 OneKey，透過 OneKey Perps 熟習交易和錢包管理；如有明確開發需要，再以專用帳戶、小倉位和嚴格風控方式接入 Hyperliquid API。

你可以前往 OneKey 官方渠道下載 OneKey App，並在支援的環境中體驗 OneKey Perps。請先了解產品功能、交易規則和相關風險，再決定是否參與。

免責聲明

本文內容僅供技術參考，不構成投資、法律或財務建議。API 交易涉及自動化風險，程式錯誤、簽名管理不當或策略缺陷都可能導致非預期的大額虧損。永續合約交易具有高槓桿特性，風險極高。請在充分理解相關技術和市場風險後，審慎評估是否參與。過往策略表現不代表未來收益。

使用 OneKey 保護您的加密之旅

View details for 選購 OneKey選購 OneKey

選購 OneKey

全球最先進嘅硬件錢包。

View details for 下載應用程式下載應用程式

下載應用程式

詐騙預警。支援所有幣種。

View details for OneKey SifuOneKey Sifu

OneKey Sifu

即刻諮詢，掃除疑慮。