@rabby-wallet/hyperliquid-sdk 1.0.8 → 1.0.9-beta.1

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

@@ -1,4 +1,4 @@
-import type { OrderResponse, CancelResponse, ExchangeClientConfig, PlaceOrderParams, MultiOrderParams, CancelOrderParams, ModifyOrderParams, WithdrawParams, ApproveBuilderFeeParams, PrepareApproveBuilderFeeResult, SendApproveParams, MarketOrderParams, UpdateLeverageParams, BindTpslByOrderIdParams } from '../types';
+import type { OrderResponse, CancelResponse, ExchangeClientConfig, PlaceOrderParams, MultiOrderParams, CancelOrderParams, ModifyOrderParams, WithdrawParams, ApproveBuilderFeeParams, PrepareApproveBuilderFeeResult, SendApproveParams, MarketOrderParams, UpdateLeverageParams, BindTpslByOrderIdParams, UpdateIsolatedMarginParams } from '../types';
 /**
  * Client for executing trades on Hyperliquid (perpetuals only)
  * Only includes essential trading APIs as specified
@@ -29,7 +29,24 @@ export declare class ExchangeClient {
      * Place a single order
      */
     placeOrder(params: PlaceOrderParams): Promise<OrderResponse>;
+    /**
+     * Calculate slippage price for market orders following Hyperliquid price rules
+     * Based on official Python SDK logic
+     *
+     * Rules:
+     * - Round to 5 significant figures
+     * - Round to (6 - szDecimals) decimal places for perps
+     *
+     * @param midPx - Middle price as string
+     * @param slippage - Slippage rate (e.g., 0.08 for 8%)
+     * @param isBuy - True for buy orders, false for sell orders
+     * @param szDecimals - Size decimals from meta endpoint (default 0)
+     */
     private getSlippagePx;
+    /**
+     * Round a number to specified decimal places
+     */
+    private roundToDecimals;
     /**
      * Place a market order
      * default slippage is 0.08
@@ -50,6 +67,7 @@ export declare class ExchangeClient {
      * Modify an existing order
      */
     modifyOrder(params: ModifyOrderParams): Promise<any>;
+    updateIsolatedMargin(params: UpdateIsolatedMarginParams): Promise<any>;
     /**
      * Set referrer for 10% fee
      */

package/dist/client/exchange-client.js

@@ -167,12 +167,39 @@ class ExchangeClient {
             });
         });
     }
-    getSlippagePx(midPx, slippage, isBuy) {
-        var _a;
-        const decimals = ((_a = midPx.toString().split('.')[1]) === null || _a === void 0 ? void 0 : _a.length) || 0;
-        const prepDecimals = Math.max(0, decimals - 1);
-        const px = isBuy ? (Number(midPx) * (1 + slippage)).toFixed(prepDecimals) : (Number(midPx) * (1 - slippage)).toFixed(prepDecimals);
-        return (0, number_1.removeTrailingZeros)(px);
+    /**
+     * Calculate slippage price for market orders following Hyperliquid price rules
+     * Based on official Python SDK logic
+     *
+     * Rules:
+     * - Round to 5 significant figures
+     * - Round to (6 - szDecimals) decimal places for perps
+     *
+     * @param midPx - Middle price as string
+     * @param slippage - Slippage rate (e.g., 0.08 for 8%)
+     * @param isBuy - True for buy orders, false for sell orders
+     * @param szDecimals - Size decimals from meta endpoint (default 0)
+     */
+    getSlippagePx(midPx, slippage, isBuy, szDecimals = 0) {
+        let px = parseFloat(midPx);
+        if (isNaN(px) || px <= 0) {
+            throw new Error('Invalid midPx: must be a positive number');
+        }
+        // Calculate slippage price
+        px *= isBuy ? (1 + slippage) : (1 - slippage);
+        // Round to 5 significant figures
+        const sigFigRounded = parseFloat(px.toPrecision(5));
+        // Round to (6 - szDecimals) decimals for perps
+        const maxDecimals = 6 - szDecimals;
+        const decimalRounded = this.roundToDecimals(sigFigRounded, maxDecimals);
+        return (0, number_1.removeTrailingZeros)(decimalRounded.toFixed(maxDecimals));
+    }
+    /**
+     * Round a number to specified decimal places
+     */
+    roundToDecimals(value, decimals) {
+        const multiplier = Math.pow(10, decimals);
+        return Math.round(value * multiplier) / multiplier;
     }
     /**
      * Place a market order
@@ -183,7 +210,8 @@ class ExchangeClient {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const slippage = params.slippage || constants_1.SLIPPAGE;
-                const px = this.getSlippagePx((0, number_1.removeTrailingZeros)(params.midPx), slippage, params.isBuy);
+                const szDecimals = yield this.symbolConversion.getAssetSzDecimals(params.coin);
+                const px = this.getSlippagePx((0, number_1.removeTrailingZeros)(params.midPx), slippage, params.isBuy, szDecimals);
                 const orders = [{
                         coin: params.coin,
                         isBuy: params.isBuy,
@@ -241,7 +269,8 @@ class ExchangeClient {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const slippage = params.slippage || constants_1.SLIPPAGE;
-                const px = this.getSlippagePx(params.midPx, slippage, params.isBuy);
+                const szDecimals = yield this.symbolConversion.getAssetSzDecimals(params.coin);
+                const px = this.getSlippagePx(params.midPx, slippage, params.isBuy, szDecimals);
                 const orders = [{
                         coin: params.coin,
                         isBuy: params.isBuy,
@@ -266,6 +295,7 @@ class ExchangeClient {
      */
     multiOrder(params) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
             const nonce = Date.now();
             const assetIndexCache = new Map();
             const orderWires = yield Promise.all(params.orders.map((order) => __awaiter(this, void 0, void 0, function* () {
@@ -295,22 +325,29 @@ class ExchangeClient {
                 };
             }
             const signature = (0, signer_1.signL1AgentAction)(this.getAgentPrivateKey(), action, this.isTestnet, nonce);
-            return this.httpClient.exchange({
+            const res = yield this.httpClient.exchange({
                 action,
                 nonce,
                 signature,
             });
+            (_c = (_b = (_a = res === null || res === void 0 ? void 0 : res.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.statuses) === null || _c === void 0 ? void 0 : _c.forEach((status, index) => {
+                if (status.error) {
+                    throw new Error(status.error);
+                }
+            });
+            return res;
         });
     }
     bindTpslByOrderId(params) {
         return __awaiter(this, void 0, void 0, function* () {
             let orders = [];
+            const szDecimals = yield this.symbolConversion.getAssetSzDecimals(params.coin);
             if (params.tpTriggerPx) {
                 orders.push({
                     coin: params.coin,
                     isBuy: !params.isBuy,
                     sz: '0',
-                    limitPx: this.getSlippagePx((0, number_1.removeTrailingZeros)(params.tpTriggerPx), constants_1.SLIPPAGE, !params.isBuy),
+                    limitPx: this.getSlippagePx((0, number_1.removeTrailingZeros)(params.tpTriggerPx), constants_1.SLIPPAGE, !params.isBuy, szDecimals),
                     reduceOnly: true,
                     orderType: {
                         trigger: {
@@ -326,7 +363,7 @@ class ExchangeClient {
                     coin: params.coin,
                     isBuy: !params.isBuy,
                     sz: '0',
-                    limitPx: this.getSlippagePx((0, number_1.removeTrailingZeros)(params.slTriggerPx), constants_1.SLIPPAGE, !params.isBuy),
+                    limitPx: this.getSlippagePx((0, number_1.removeTrailingZeros)(params.slTriggerPx), constants_1.SLIPPAGE, !params.isBuy, szDecimals),
                     reduceOnly: true,
                     orderType: {
                         trigger: {
@@ -401,6 +438,24 @@ class ExchangeClient {
             });
         });
     }
+    updateIsolatedMargin(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nonce = Date.now();
+            const assetIndex = yield this.symbolConversion.getAssetIndex(params.coin);
+            const action = {
+                asset: assetIndex,
+                isBuy: true,
+                ntli: (0, number_1.floatToInt)(params.value, 6), // 6 decimals
+                type: constants_1.ExchangeType.UPDATE_ISOLATED_MARGIN,
+            };
+            const signature = (0, signer_1.signL1AgentAction)(this.getAgentPrivateKey(), action, this.isTestnet, nonce);
+            return this.httpClient.exchange({
+                action,
+                nonce,
+                signature,
+            });
+        });
+    }
     /**
      * Set referrer for 10% fee
      */

package/dist/client/symbolConversion.d.ts

@@ -2,6 +2,7 @@ import { HttpClientConfig } from "./http-client";
 import { InfoClient } from "./info-client";
 export declare class SymbolConversion {
     private assetToIndexMap;
+    private assetSzDecimalsMap;
     private httpClient;
     private initialized;
     private infoClient?;
@@ -10,6 +11,7 @@ export declare class SymbolConversion {
     private ensureInitialized;
     private refreshAssetMaps;
     getAssetIndex(assetSymbol: string): Promise<number>;
+    getAssetSzDecimals(assetSymbol: string): Promise<number>;
     getAllAssets(): Promise<{
         perp: string[];
     }>;

package/dist/client/symbolConversion.js

@@ -15,6 +15,7 @@ const http_client_1 = require("./http-client");
 class SymbolConversion {
     constructor(config, infoClient) {
         this.assetToIndexMap = new Map();
+        this.assetSzDecimalsMap = new Map();
         this.initialized = false;
         this.infoClient = infoClient;
         this.httpClient = new http_client_1.HttpClient({
@@ -64,9 +65,11 @@ class SymbolConversion {
                     throw new Error('Invalid perpetual metadata response');
                 }
                 this.assetToIndexMap.clear();
+                this.assetSzDecimalsMap.clear();
                 // Handle perpetual assets
                 perpMeta[0].universe.forEach((asset, index) => {
                     this.assetToIndexMap.set(asset.name, index);
+                    this.assetSzDecimalsMap.set(asset.name, asset.szDecimals);
                 });
             }
             catch (error) {
@@ -84,6 +87,16 @@ class SymbolConversion {
             return index;
         });
     }
+    getAssetSzDecimals(assetSymbol) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.ensureInitialized();
+            const szDecimals = this.assetSzDecimalsMap.get(assetSymbol);
+            if (szDecimals === undefined) {
+                throw new Error(`Unknown asset szDecimals: ${assetSymbol}`);
+            }
+            return szDecimals;
+        });
+    }
     getAllAssets() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.ensureInitialized();

package/dist/types/index.d.ts

@@ -393,6 +393,10 @@ export interface CancelOrderParams {
     coin: string;
     oid: OrderId;
 }
+export interface UpdateIsolatedMarginParams {
+    coin: string;
+    value: number;
+}
 export interface ModifyOrderParams {
     oid: OrderId;
     coin: string;

package/dist/utils/number.d.ts

@@ -10,3 +10,4 @@
  * @returns The normalized string without trailing zeros
  */
 export declare function removeTrailingZeros(value: string): string;
+export declare function floatToInt(x: number, power: number): number;

package/dist/utils/number.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeTrailingZeros = removeTrailingZeros;
+exports.floatToInt = floatToInt;
 /**
  * Removes trailing zeros from a string representation of a number.
  * This is useful when working with price and size fields directly.
@@ -20,3 +21,10 @@ function removeTrailingZeros(value) {
         return '0';
     return normalized;
 }
+function floatToInt(x, power) {
+    const withDecimals = x * Math.pow(10, power);
+    if (Math.abs(Math.round(withDecimals) - withDecimals) >= 1e-3) {
+        throw new Error(`floatToInt causes rounding: ${x}`);
+    }
+    return Math.round(withDecimals);
+}

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@rabby-wallet/hyperliquid-sdk",
-  "version": "1.0.8",
-  "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.0.9-beta.1",
+  "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"
+}