@rabby-wallet/hyperliquid-sdk 1.0.0-beta.1

package/README.md

@@ -0,0 +1,138 @@
+# Hyperliquid Perpetuals SDK
+
+一个简化的 Hyperliquid 永续合约交易 SDK，专为前端应用设计。
+
+## 特性
+
+- ✅ 仅核心API：最重要的交易与查询能力
+- ✅ 永续合约专用：不包含现货功能
+- ✅ TypeScript：完善的类型定义
+- ✅ WebSocket：实时数据订阅
+- ✅ 前端友好：基于 fetch API 的轻量实现
+
+## 安装
+
+```bash
+yarn add @debank/hyperliquid-perp-sdk
+# or
+npm i @debank/hyperliquid-perp-sdk
+```
+
+## 快速开始
+
+### 仅查询（无需私钥）
+```ts
+import { HyperliquidSDK } from '@debank/hyperliquid-perp-sdk';
+
+const sdk = new HyperliquidSDK({
+  masterAddress: '0xYourEOA',
+  isTestnet: true,
+});
+
+// 获取所有中间价
+const prices = await sdk.info.getAllMids();
+
+// 获取市场元数据与资产上下文
+const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs();
+
+// 获取账户综合状态
+const account = await sdk.info.getClearingHouseState();
+```
+
+### 交易（需要提供代理私钥、公钥、名称）
+```ts
+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 },
+]);
+```
+
+### 授权持久化代理（主钱包签名）
+```ts
+// 准备主钱包签名的 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 实时数据
+```ts
+await sdk.connectWebSocket();
+
+// 订阅价格
+sdk.ws.subscribeToAllMids((prices) => {
+  console.log('价格更新:', prices);
+});
+
+// 订阅用户综合数据
+sdk.ws.subscribeToWebData2('0xYourEOA', (webData2) => {
+  console.log('用户数据:', webData2);
+});
+```

package/dist/client/exchange-client.d.ts

@@ -0,0 +1,89 @@
+import type { OrderResponse, CancelResponse, ExchangeClientConfig, PlaceOrderParams, MultiOrderParams, CancelOrderParams, ModifyOrderParams, WithdrawParams, ApproveBuilderFeeParams, PrepareApproveBuilderFeeResult, SendApproveParams, MarketOrderParams, UpdateLeverageParams, BindTpslByOrderIdParams } from '../types';
+/**
+ * Client for executing trades on Hyperliquid (perpetuals only)
+ * Only includes essential trading APIs as specified
+ */
+export declare class ExchangeClient {
+    private readonly httpClient;
+    private agentPrivateKey;
+    private agentPublicKey;
+    private agentName;
+    private readonly isTestnet;
+    private readonly masterAddress;
+    private builder?;
+    private readonly symbolConversion;
+    constructor(config: ExchangeClientConfig);
+    /**
+     * Get the wallet address
+     */
+    get address(): string;
+    updateBuilder(address: string, fee: number): Promise<any>;
+    updateLeverage(params: UpdateLeverageParams): Promise<any>;
+    /**
+     * Place a single order
+     */
+    placeOrder(params: PlaceOrderParams): Promise<OrderResponse>;
+    private getSlippagePx;
+    /**
+     * Place a market order
+     * default slippage is 0.08
+     * need to update leverage before place order
+     */
+    marketOrderOpen(params: MarketOrderParams): Promise<OrderResponse>;
+    marketOrderClose(params: MarketOrderParams): Promise<OrderResponse>;
+    /**
+     * Place multiple orders at once
+     */
+    multiOrder(params: MultiOrderParams): Promise<OrderResponse>;
+    bindTpslByOrderId(params: BindTpslByOrderIdParams): Promise<OrderResponse>;
+    /**
+     * Cancel order(s)
+     */
+    cancelOrder(params: CancelOrderParams[]): Promise<CancelResponse>;
+    /**
+     * Modify an existing order
+     */
+    modifyOrder(params: ModifyOrderParams): Promise<any>;
+    /**
+     * Set referrer for 10% fee
+     */
+    setReferrer(code: string): Promise<any>;
+    /**
+     * Prepare approve agent data for main wallet signing
+     * Returns typed data that needs to be signed by the main wallet
+     */
+    prepareApproveAgent(): {
+        domain: {
+            name?: string;
+            version?: string;
+            chainId?: number;
+            verifyingContract?: string;
+            salt?: ArrayBuffer;
+        };
+        types: import("@metamask/eth-sig-util").MessageTypes;
+        primaryType: keyof import("@metamask/eth-sig-util").MessageTypes;
+        message: Record<string, unknown>;
+        nonce: number;
+    };
+    /**
+     * Send approve agent request with main wallet signature
+     * nonce must be the same as the nonce in the prepareApproveAgent
+     */
+    sendApproveAgent(params: SendApproveParams): Promise<any>;
+    /**
+     * Prepare approve builder fee data for main wallet signing
+     * Returns typed data that needs to be signed by the main wallet
+     * maxFee :  max fee rate = '0.1%'
+     */
+    prepareApproveBuilderFee(params: ApproveBuilderFeeParams): PrepareApproveBuilderFeeResult;
+    /**
+     * Send approve builder fee request with main wallet signature
+     * nonce must be the same as the nonce in the prepareApproveBuilderFee
+     * signature is the signature of the main wallet by the prepareApproveBuilderFee action
+     */
+    sendApproveBuilderFee(params: SendApproveParams): Promise<any>;
+    /**
+     * Withdraw funds to L1 need use master wallet
+     */
+    prepareWithdraw(params: WithdrawParams): PrepareApproveBuilderFeeResult;
+}