@rabby-wallet/hyperliquid-sdk 1.0.10 → 1.1.0-beta.2

package/README.md

@@ -1,140 +1,140 @@
-# 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 canUseCache = true; //默认使用缓存，多次请求并发去重 ，需要刷新传false
-const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs(canUseCache);
-
-
-// 获取账户综合状态
-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);
-});
+# 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 canUseCache = true; //默认使用缓存，多次请求并发去重 ，需要刷新传false
+const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs(canUseCache);
+
+
+// 获取账户综合状态
+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

@@ -13,12 +13,16 @@ export declare class ExchangeClient {
     private builder?;
     private readonly symbolConversion;
     constructor(config: ExchangeClientConfig);
-    initAccount(masterAddress: string, agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
+    initAccount(masterAddress: string, agentPrivateKey?: string, agentPublicKey?: string, agentName?: string): void;
+    initOrUpdateAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
+    /**
+     * Check if agent is set
+     */
+    get isHaveAgent(): boolean;
     /**
      * Get the wallet address
      */
     get address(): string;
-    updateExchangeAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
     private getAgentPrivateKey;
     /**
      * @deprecated This method is deprecated. Use the new builder configuration in constructor instead.

package/dist/client/exchange-client.js

@@ -82,21 +82,34 @@ class ExchangeClient {
     }
     initAccount(masterAddress, agentPrivateKey, agentPublicKey, agentName) {
         this.masterAddress = masterAddress;
+        if (agentPrivateKey && agentPublicKey) {
+            this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
+            this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
+            this.agentName = agentName || '';
+        }
+        else {
+            this.agentPrivateKey = undefined;
+            this.agentPublicKey = undefined;
+            this.agentName = undefined;
+        }
+    }
+    initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName) {
         this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
         this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
         this.agentName = agentName || '';
     }
+    /**
+     * Check if agent is set
+     */
+    get isHaveAgent() {
+        return !!this.agentPrivateKey && !!this.agentPublicKey;
+    }
     /**
      * Get the wallet address
      */
     get address() {
         return this.masterAddress;
     }
-    updateExchangeAgent(agentPrivateKey, agentPublicKey, agentName) {
-        this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
-        this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
-        this.agentName = agentName || '';
-    }
     getAgentPrivateKey() {
         if (!this.agentPrivateKey) {
             throw new Error('Agent private key is not set');
@@ -484,6 +497,9 @@ class ExchangeClient {
      * Returns typed data that needs to be signed by the main wallet
      */
     prepareApproveAgent() {
+        if (!this.isHaveAgent) {
+            throw new Error('account not have agent, please set agent first.');
+        }
         const nonce = Date.now();
         const action = {
             type: constants_1.ExchangeType.APPROVE_AGENT,

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

@@ -1,4 +1,4 @@
-import type { AllMids, L2Book, Candle, WsOrder, WebData2, WsActiveAssetCtx, WsUserFills } from '../types';
+import type { AllMids, L2Book, Candle, WsOrder, WebData2, WsActiveAssetCtx, WsUserFills, WsClearinghouseState } from '../types';
 export interface WebSocketClientConfig {
     masterAddress?: string;
     isTestnet?: boolean;
@@ -43,6 +43,7 @@ export declare class WebSocketClient {
      * Disconnect from the WebSocket
      */
     disconnect(): void;
+    private getSubscriptionKey;
     /**
      * Subscribe to a channel
      */
@@ -84,6 +85,7 @@ export declare class WebSocketClient {
      * Includes positions, margin summary, open orders, and other user data
      */
     subscribeToWebData2(callback: SubscriptionCallback<WebData2>): Subscription;
+    subscribeToClearinghouseState(user: string | string[], callback: SubscriptionCallback<WsClearinghouseState>): Subscription;
     /**
      * Check if WebSocket is connected
      */

package/dist/client/websocket-client.js

@@ -77,8 +77,9 @@ class WebSocketClient {
                     this.pendingSubscriptions.forEach(({ message, callback }) => {
                         var _a;
                         if (((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
+                            const subKey = this.getSubscriptionKey(message.subscription);
                             this.subscriptions.set(message.subscription.type, callback);
-                            this.activeSubscriptions.set(message.subscription.type, { message, callback });
+                            this.activeSubscriptions.set(subKey, { message, callback });
                             this.ws.send(JSON.stringify(Object.assign(Object.assign({}, message), { method: 'subscribe' })));
                         }
                     });
@@ -87,6 +88,7 @@ class WebSocketClient {
                     resolve();
                 };
                 this.ws.onmessage = (event) => {
+                    var _a;
                     try {
                         const data = JSON.parse(event.data);
                         // Handle pong response
@@ -95,9 +97,40 @@ class WebSocketClient {
                             return;
                         }
                         const type = data.channel;
-                        const callback = this.subscriptions.get(type);
-                        if (callback) {
-                            callback(data.data);
+                        // Iterate through active subscriptions to find matching ones
+                        let hasDispatched = false;
+                        for (const { message, callback } of this.activeSubscriptions.values()) {
+                            const subParams = message.subscription;
+                            if (subParams.type === type) {
+                                let isMatch = true;
+                                // Filter based on subscription parameters
+                                if (type === 'l2Book' && data.data.coin !== subParams.coin)
+                                    isMatch = false;
+                                if (type === 'trades' && ((_a = data.data[0]) === null || _a === void 0 ? void 0 : _a.coin) !== subParams.coin)
+                                    isMatch = false;
+                                if (type === 'candle' && (data.data.s !== subParams.coin || data.data.i !== subParams.interval))
+                                    isMatch = false;
+                                if (type === 'activeAssetCtx' && data.data.coin !== subParams.coin)
+                                    isMatch = false;
+                                // For user-specific data
+                                if (subParams.user) {
+                                    // If response data contains user, verify it matches
+                                    if (data.data && data.data.user && data.data.user.toLowerCase() !== subParams.user.toLowerCase()) {
+                                        isMatch = false;
+                                    }
+                                }
+                                if (isMatch) {
+                                    callback(data.data);
+                                    hasDispatched = true;
+                                }
+                            }
+                        }
+                        // Fallback to simple type map if no active subscription matched (backward compatibility or if activeSubscriptions missing)
+                        if (!hasDispatched) {
+                            const callback = this.subscriptions.get(type);
+                            if (callback) {
+                                callback(data.data);
+                            }
                         }
                     }
                     catch (error) {
@@ -113,8 +146,9 @@ class WebSocketClient {
                     if (!this.isManualDisconnect && this.config.autoReconnect) {
                         // Save current active subscriptions to pending for reconnection
                         if (this.activeSubscriptions.size > 0) {
-                            this.activeSubscriptions.forEach((subscription, type) => {
-                                const existingPending = this.pendingSubscriptions.find(sub => sub.message.subscription.type === type);
+                            this.activeSubscriptions.forEach((subscription) => {
+                                const subKey = this.getSubscriptionKey(subscription.message.subscription);
+                                const existingPending = this.pendingSubscriptions.find(sub => this.getSubscriptionKey(sub.message.subscription) === subKey);
                                 if (!existingPending) {
                                     this.pendingSubscriptions.push(subscription);
                                 }
@@ -178,15 +212,20 @@ class WebSocketClient {
         this.pendingSubscriptions = [];
         this.reconnectAttempts = 0; // 重置重连计数
     }
+    getSubscriptionKey(subscription) {
+        return JSON.stringify(subscription);
+    }
     /**
      * Subscribe to a channel
      */
     subscribe(message, callback) {
         var _a;
         const subscriptionData = { message, callback };
+        const subKey = this.getSubscriptionKey(message.subscription);
+        const type = message.subscription.type;
         if (((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
-            this.subscriptions.set(message.subscription.type, callback);
-            this.activeSubscriptions.set(message.subscription.type, subscriptionData);
+            this.subscriptions.set(type, callback);
+            this.activeSubscriptions.set(subKey, subscriptionData);
             this.ws.send(JSON.stringify(Object.assign(Object.assign({}, message), { method: 'subscribe' })));
         }
         else {
@@ -200,14 +239,23 @@ class WebSocketClient {
         return {
             unsubscribe: () => {
                 var _a;
-                const type = message.subscription.type;
-                this.subscriptions.delete(type);
-                this.activeSubscriptions.delete(type);
+                this.activeSubscriptions.delete(subKey);
+                // Only remove the global callback if no other active subscriptions use this channel type
+                let hasOtherSubs = false;
+                for (const sub of this.activeSubscriptions.values()) {
+                    if (sub.message.subscription.type === type) {
+                        hasOtherSubs = true;
+                        break;
+                    }
+                }
+                if (!hasOtherSubs) {
+                    this.subscriptions.delete(type);
+                }
                 if (((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
                     this.ws.send(JSON.stringify(Object.assign(Object.assign({}, message), { method: 'unsubscribe' })));
                 }
                 // Remove from pending subscriptions
-                this.pendingSubscriptions = this.pendingSubscriptions.filter(sub => sub.message.subscription.type !== type);
+                this.pendingSubscriptions = this.pendingSubscriptions.filter(sub => this.getSubscriptionKey(sub.message.subscription) !== subKey);
             },
         };
     }
@@ -296,6 +344,20 @@ class WebSocketClient {
             subscription: { type: 'webData2', user: this.config.masterAddress },
         }, callback);
     }
+    subscribeToClearinghouseState(user, callback) {
+        const users = Array.isArray(user) ? user : [user];
+        if (users.length === 0) {
+            throw new Error('user address is empty');
+        }
+        const subscriptions = users.map(u => this.subscribe({
+            subscription: { type: 'clearinghouseState', user: u || this.config.masterAddress },
+        }, callback));
+        return {
+            unsubscribe: () => {
+                subscriptions.forEach(sub => sub.unsubscribe());
+            }
+        };
+    }
     /**
      * Check if WebSocket is connected
      */

package/dist/hyperliquid-sdk.d.ts

@@ -29,7 +29,12 @@ export declare class HyperliquidSDK {
      * Get wallet address (only available if private key was provided)
      */
     get address(): string;
-    initAccount(masterAddress: string, agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
+    initAccount(masterAddress: string, agentPrivateKey?: string, agentPublicKey?: string, agentName?: string): void;
+    /**
+     * Check if agent is set for trading
+     */
+    get isHaveAgent(): boolean;
+    initOrUpdateAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
     /**
      * Connect to WebSocket for real-time data
      */

package/dist/hyperliquid-sdk.js

@@ -71,6 +71,21 @@ class HyperliquidSDK {
             });
         }
     }
+    /**
+     * Check if agent is set for trading
+     */
+    get isHaveAgent() {
+        var _a;
+        return ((_a = this.exchange) === null || _a === void 0 ? void 0 : _a.isHaveAgent) || false;
+    }
+    initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName) {
+        if (!this.exchange) {
+            throw new Error('no exchange client, first initAccount');
+        }
+        if (this.exchange) {
+            this.exchange.initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName);
+        }
+    }
     /**
      * Connect to WebSocket for real-time data
      */

package/dist/types/index.d.ts

@@ -96,6 +96,11 @@ export type Meta = {
     universe: AssetInfo[];
     marginTables: [number, MarginTable][];
 };
+export interface WsClearinghouseState {
+    dex: any;
+    user: string;
+    clearinghouseState: ClearinghouseState;
+}
 export interface ClearinghouseState {
     assetPositions: AssetPosition[];
     crossMaintenanceMarginUsed: string;

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@rabby-wallet/hyperliquid-sdk",
-  "version": "1.0.10",
-  "description": "Simplified Hyperliquid Perpetuals Trading SDK for Frontend Applications",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "rimraf dist && tsc",
-    "preversion": "npm run build",
-    "prepublishOnly": "npm run build"
-  },
-  "author": "",
-  "license": "UNLICENSED",
-  "dependencies": {
-    "@ethereumjs/util": "9.0.0",
-    "@metamask/eth-sig-util": "5.1.0",
-    "@msgpack/msgpack": "3.1.2",
-    "@noble/hashes": "1.8.0",
-    "ethereum-cryptography": "2.2.1"
-  },
-  "devDependencies": {
-    "@types/node": "24.3.1",
-    "prettier": "2.7.1",
-    "rimraf": "6.0.0",
-    "typescript": "5.9.2"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "packageManager": "yarn@1.22.22"
-}
+{
+  "name": "@rabby-wallet/hyperliquid-sdk",
+  "version": "1.1.0-beta.2",
+  "description": "Simplified Hyperliquid Perpetuals Trading SDK for Frontend Applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "preversion": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@ethereumjs/util": "9.0.0",
+    "@metamask/eth-sig-util": "5.1.0",
+    "@msgpack/msgpack": "3.1.2",
+    "@noble/hashes": "1.8.0",
+    "ethereum-cryptography": "2.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.3.1",
+    "prettier": "2.7.1",
+    "rimraf": "6.0.0",
+    "typescript": "5.9.2"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "packageManager": "yarn@1.22.22"
+}