@rabby-wallet/hyperliquid-sdk

Hyperliquid Perpetuals SDK

一个简化的 Hyperliquid 永续合约交易 SDK，专为前端应用设计。

特性

• ✅ 仅核心API：最重要的交易与查询能力
• ✅ 永续合约专用：不包含现货功能
• ✅ TypeScript：完善的类型定义
• ✅ WebSocket：实时数据订阅
• ✅ 前端友好：基于 fetch API 的轻量实现

安装

yarn add @debank/hyperliquid-perp-sdk
# or
npm i @debank/hyperliquid-perp-sdk

快速开始

仅查询（无需私钥）

import { HyperliquidSDK } from '@debank/hyperliquid-perp-sdk';

const sdk = new HyperliquidSDK({
  masterAddress: '0xYourEOA',
  isTestnet: true,
});

// 获取所有中间价
const prices = await sdk.info.getAllMids();

// 获取市场元数据与资产上下文 
const canUseCache = true; //默认使用缓存，多次请求并发去重 ，需要刷新传false
const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs(canUseCache);


// 获取账户综合状态
const account = await sdk.info.getClearingHouseState();

交易（需要提供代理私钥、公钥、名称）

const sdk = new HyperliquidSDK({
  masterAddress: '0xYourEOA',
  agentPrivateKey: '0xYourAgentPrivKey',
  agentPublicKey: '0xYourAgentPubKey',
  agentName: 'MyAgent',
  isTestnet: true,
});

// 限价下单
await sdk.exchange!.placeOrder({
  coin: 'BTC',
  isBuy: true,
  sz: '0.1',
  limitPx: '45000',
  orderType: { limit: { tif: 'Gtc' } },
});

// 批量下单
await sdk.exchange!.multiOrder({
  orders: [
    { coin: 'ETH', isBuy: true,  sz: '1',   limitPx: '3000', orderType: { limit: { tif: 'Ioc' } } },
    { coin: 'SOL', isBuy: false, sz: '10',  limitPx: '150',  orderType: { limit: { tif: 'Ioc' } } },
  ],
});

// 市价开仓（带可选的 TP/SL 触发单）
await sdk.exchange!.marketOrderOpen({
  coin: 'BTC',
  isBuy: true,
  size: '0.05',
  midPx: '45200',
  tpTriggerPx: '47000',
  slTriggerPx: '44000',
  // slippage 默认 0.08
});

// 市价平仓
await sdk.exchange!.marketOrderClose({
  coin: 'BTC',
  isBuy: false,
  size: '0.05',
  midPx: '45000',
});

// 绑定 TP/SL 到已有持仓（按位置绑定）
await sdk.exchange!.bindTpslByOrderId({
  coin: 'BTC',
  isBuy: true, // 持仓方向
  tpTriggerPx: '47000',
  slTriggerPx: '44000',
});

// 更新杠杆
await sdk.exchange!.updateLeverage({
  coin: 'BTC',
  leverage: 5,
  isCross: true,
});

// 撤单（可批量）
await sdk.exchange!.cancelOrder([
  { coin: 'BTC', oid: 12345 },
  { coin: 'ETH', oid: 67890 },
]);

授权持久化代理（主钱包签名）

// 准备主钱包签名的 EIP-712 数据（Approve Agent）
const approve = sdk.exchange!.prepareApproveAgent();
// 业务方使用主钱包签名（示例）
const signature = await mainWallet.signTypedData(approve.domain, approve.types, approve.message);
// 发送请求
await sdk.exchange!.sendApproveAgent({ action: approve.message, nonce: approve.nonce, signature });

// 准备并签名 Builder 费用
const builderFee = sdk.exchange!.prepareApproveBuilderFee({ builder: '0xBuilder', maxFee: '0.1%' });
const sig2 = await mainWallet.signTypedData(builderFee.domain, builderFee.types, builderFee.message);
await sdk.exchange!.sendApproveBuilderFee({ action: builderFee.message, nonce: builderFee.nonce, signature: sig2 });

WebSocket 实时数据

await sdk.connectWebSocket();

// 订阅价格
sdk.ws.subscribeToAllMids((prices) => {
  console.log('价格更新:', prices);
});

// 订阅用户综合数据
sdk.ws.subscribeToWebData2('0xYourEOA', (webData2) => {
  console.log('用户数据:', webData2);
});