將 Hyperliquid 整合到錢包：開發者完整指南
隨着去中心化衍生品市場逐漸成熟，愈來愈多錢包開發團隊希望將 Hyperliquid 的永續合約交易功能直接嵌入錢包介面，為用戶提供更完整的一站式 DeFi 體驗。本文面向錢包開發者，系統整理 Hyperliquid 整合的技術路線：由帳戶模型、簽名方案，到前端 SDK 調用及安全設計重點，協助團隊減少試錯成本。
Hyperliquid 的帳戶模型
Hyperliquid 採用 EVM 兼容地址體系（以太坊格式），用戶使用標準 ECDSA 私鑰簽名。根據官方文檔，帳戶可分為兩類：
- Vault Address：協議層面的主地址，持有資產所有權
- Agent Address：可被授權的子簽名地址，用於減低每次交易的操作摩擦
對錢包整合而言，最常見做法是讓用戶以主錢包地址作為 Vault Address，同時可選擇授權一個熱錢包 Agent 進行高頻交易操作。
連接方式：WalletConnect vs 直接 RPC
方案一：WalletConnect 2.0
WalletConnect 是目前主流的錢包連接協議，Hyperliquid 的 Web 應用原生支援 WalletConnect 2.0。整合步驟一般包括：
- 在錢包 App 內實作 WalletConnect 2.0 Session Proposal 處理
- 用戶透過掃碼或 Deep Link 授權
- 錢包監聽
eth_sendTransaction及personal_sign請求，並回傳簽名
這個方案的好處是低侵入：錢包毋須深入理解 Hyperliquid 內部協議，只要提供標準以太坊簽名介面即可。
方案二：直接整合 Hyperliquid Python/JS SDK
如果希望在錢包內提供更深入功能，例如查看持倉、直接下單、管理訂單等，可以使用官方或社群 SDK：
pip install hyperliquid-python-sdk
# 或
npm install @nktkas/hyperliquid
Hyperliquid Python SDK 已封裝完整簽名及請求邏輯，適合後端服務、內部工具或進階錢包功能整合。
簽名方案：EIP-712 結構化簽名
Hyperliquid 的所有寫入操作，包括下單、撤單、存款及提款，均使用 EIP-712 結構化簽名，而不是簡單的 eth_sign。這對用戶體驗及安全性非常重要：
- 支援 EIP-712 的錢包，可以向用戶展示可讀的簽名內容，例如「開多 BTC 永續 0.01 張，限價 65000 USDC」
- 不支援 EIP-712 的錢包，往往只能顯示十六進制資料，用戶難以判斷自己正在授權甚麼，亦會增加安全風險
建議在錢包整合時優先實作 EIP-712 解析及展示邏輯，可參考 EIP-712 規範中的 signTypedData_v4 標準。
核心 API 整合：下單流程
以下以 JavaScript 為例，示範透過直接 API 調用建立限價買單：
import { ethers } from "ethers";
const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";
async function placeOrder(wallet, coin, isBuy, price, size) {
const nonce = Date.now();
const orderPayload = {
type: "order",
orders: [{
a: 0, // asset index (0 = BTC)
b: isBuy,
p: price.toString(),
s: size.toString(),
r: false, // reduce-only
t: { limit: { tif: "Gtc" } }
}],
grouping: "na"
};
// EIP-712 Domain 及 Types 定義請參考官方文檔
const signature = await wallet._signTypedData(domain, types, orderPayload);
const body = {
action: orderPayload,
nonce,
signature,
};
const resp = await fetch(EXCHANGE_ENDPOINT, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
return resp.json();
}
完整的 Domain 及 Types 定義，應以 Hyperliquid 官方文檔中的 Exchange Endpoint 說明為準。
帳戶餘額及持倉查詢
帳戶狀態查詢屬於只讀操作，毋須簽名：
async function getAccountInfo(address) {
const resp = await fetch("https://api.hyperliquid.xyz/info", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
type: "clearinghouseState",
user: address,
}),
});
return resp.json();
}
回傳資料包括：
marginSummary：可用保證金、總帳戶價值等assetPositions：各項持倉詳情crossMaintenanceMarginUsed：全倉維持保證金使用情況等
這些資料可用於錢包內的倉位面板、PnL 顯示、風險提示及保證金狀態提醒。
安全設計重點
錢包整合衍生品協議時，安全應是首要考慮：
私鑰隔離
交易簽名必須在 Secure Enclave、安全晶片或硬件設備中完成，絕不應將私鑰暴露予應用層程式碼。硬件錢包方案可參考 OneKey 的開源架構。
金額二次確認
下單前必須向用戶展示清晰、可讀的確認介面，至少包括：
- 交易幣種
- 方向（開多／開空）
- 數量
- 價格
- 槓桿
- 是否 reduce-only
- 預估強平價或相關風險提示
永續合約涉及槓桿及強制平倉風險，錢包不應只顯示原始簽名資料。
限制 Agent 權限
如採用 Agent 模式，應容許用戶隨時撤銷 Agent 授權，並在 UI 中清楚顯示目前已授權的 Agent Address。若 Agent 只需下單權限，就不應獲得更高權限。
防重放保護
應妥善使用 Hyperliquid 的 nonce 機制，確保每筆訂單 nonce 單調遞增，避免重放攻擊。對於多裝置或多端同時交易的場景，亦應設計 nonce 管理策略。
推薦架構：嵌入 OneKey 與 OneKey Perps 工作流
OneKey 硬件錢包原生支援以太坊 EIP-712 簽名，其開源 SDK 提供完整的結構化簽名 API，適合深度整合 Hyperliquid 這類 EVM 衍生品協議。
對希望向用戶提供永續合約功能的錢包團隊，可以參考 OneKey Perps 的設計思路：在硬件級私鑰保護及清晰簽名確認的基礎上，提供相對流暢的加密貨幣衍生品交易體驗，而不是為了速度犧牲安全。
如果你是開發者，可以下載 OneKey App、體驗 OneKey Perps 的交易流程，並參考 OneKey GitHub 上的開源實作，評估如何在自己的產品中建立更安全的永續合約整合方案。
常見問題
Q1：Hyperliquid 支援哪些錢包連接方式？
答：Hyperliquid 原生支援 MetaMask、WalletConnect 2.0 兼容錢包，以及透過私鑰直接簽名的程式化存取。只要能進行 ECDSA 簽名的以太坊錢包，理論上都可以整合。
Q2：Agent Address 和主地址有甚麼分別？
答：Agent Address 是經主地址授權的子簽名地址，通常用於自動化交易或高頻操作。Agent 可執行特定操作，例如下單，但不能提款，從而降低私鑰外洩時的潛在損失範圍。具體權限及限制應以 Hyperliquid 文檔為準。
Q3：整合時是否需要向 Hyperliquid 團隊申請 API 許可？
答：Hyperliquid 是無許可協議，Info Endpoint 完全公開。Exchange Endpoint 的寫入操作只需要有效的 EIP-712 簽名，毋須申請許可或白名單。
Q4：如何在錢包 UI 顯示未實現盈虧（PnL）？
答：可從 clearinghouseState 介面回傳的 assetPositions 中讀取。每個持倉包含 unrealizedPnl 字段，可直接用於顯示未實現盈虧。請注意該數值以 USDC 計價。
Q5：Testnet 地址是甚麼？
答：Hyperliquid 測試網介面為 https://api.hyperliquid-testnet.xyz/，可用於開發階段的功能測試，不涉及真實資金。
風險提示
本文僅作技術整合參考，不構成投資、法律或財務建議。永續合約交易涉及高槓桿風險，價格波動可能導致快速虧損甚至被強制平倉。開發者在正式上線前，應充分了解 Hyperliquid 的協議規則、簽名流程、風控機制及用戶提示責任。
