把 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 域和类型定义见官方文档
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 等。
安全设计要点
钱包集成衍生品协议时，安全是首要考量：
私钥隔离：交易签名必须在安全飞地（Secure Enclave）或硬件设备中完成，绝不将私钥暴露给应用层代码。硬件钱包方案参考 OneKey 开源架构。
金额二次确认：下单前必须向用户展示清晰的人类可读确认界面，包含币种、方向、数量、杠杆、预估强平价。
限制 Agent 权限：若使用 Agent 模式，应允许用户随时撤销 Agent 授权，并在 UI 中清晰展示当前已授权的 Agent 地址。
防重放保护：利用 Hyperliquid 的 nonce 机制，确保每笔订单的 nonce 单调递增，防止重放攻击。
推荐架构：嵌入 OneKey
OneKey 硬件钱包 原生支持以太坊 EIP-712 签名，其开源 SDK 提供了完整的结构化签名 API，适合深度集成 Hyperliquid 等 EVM 衍生品协议。
对于希望向用户提供永续合约功能的钱包团队，可以参考 OneKey Perps 的设计理念：在硬件安全的基础上，提供流畅的衍生品交易体验，而非牺牲安全换速度。
下载 OneKey 或访问 OneKey GitHub 获取开源代码参考。
常见问题
Q1：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/，可用于开发阶段的功能测试，不涉及真实资金。
风险提示：本文为技术集成参考，不构成投资建议。永续合约交易存在高杠杆风险，开发者应充分了解协议规则后再进行生产集成。
