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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +139 -139
  2. package/dist/client/exchange-client.d.ts +6 -2
  3. package/dist/client/exchange-client.js +21 -5
  4. package/dist/hyperliquid-sdk.d.ts +6 -1
  5. package/dist/hyperliquid-sdk.js +15 -0
  6. package/package.json +37 -37
package/README.md CHANGED
@@ -1,140 +1,140 @@
1
- # Hyperliquid Perpetuals SDK
2
-
3
- 一个简化的 Hyperliquid 永续合约交易 SDK，专为前端应用设计。
4
-
5
- ## 特性
6
-
7
- - ✅ 仅核心API：最重要的交易与查询能力
8
- - ✅ 永续合约专用：不包含现货功能
9
- - ✅ TypeScript：完善的类型定义
10
- - ✅ WebSocket：实时数据订阅
11
- - ✅ 前端友好：基于 fetch API 的轻量实现
12
-
13
- ## 安装
14
-
15
- ```bash
16
- yarn add @debank/hyperliquid-perp-sdk
17
- # or
18
- npm i @debank/hyperliquid-perp-sdk
19
- ```
20
-
21
- ## 快速开始
22
-
23
- ### 仅查询（无需私钥）
24
- ```ts
25
- import { HyperliquidSDK } from '@debank/hyperliquid-perp-sdk';
26
-
27
- const sdk = new HyperliquidSDK({
28
- masterAddress: '0xYourEOA',
29
- isTestnet: true,
30
- });
31
-
32
- // 获取所有中间价
33
- const prices = await sdk.info.getAllMids();
34
-
35
- // 获取市场元数据与资产上下文
36
- const canUseCache = true; //默认使用缓存，多次请求并发去重 ，需要刷新传false
37
- const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs(canUseCache);
38
-
39
-
40
- // 获取账户综合状态
41
- const account = await sdk.info.getClearingHouseState();
42
- ```
43
-
44
- ### 交易（需要提供代理私钥、公钥、名称）
45
- ```ts
46
- const sdk = new HyperliquidSDK({
47
- masterAddress: '0xYourEOA',
48
- agentPrivateKey: '0xYourAgentPrivKey',
49
- agentPublicKey: '0xYourAgentPubKey',
50
- agentName: 'MyAgent',
51
- isTestnet: true,
52
- });
53
-
54
- // 限价下单
55
- await sdk.exchange!.placeOrder({
56
- coin: 'BTC',
57
- isBuy: true,
58
- sz: '0.1',
59
- limitPx: '45000',
60
- orderType: { limit: { tif: 'Gtc' } },
61
- });
62
-
63
- // 批量下单
64
- await sdk.exchange!.multiOrder({
65
- orders: [
66
- { coin: 'ETH', isBuy: true, sz: '1', limitPx: '3000', orderType: { limit: { tif: 'Ioc' } } },
67
- { coin: 'SOL', isBuy: false, sz: '10', limitPx: '150', orderType: { limit: { tif: 'Ioc' } } },
68
- ],
69
- });
70
-
71
- // 市价开仓（带可选的 TP/SL 触发单）
72
- await sdk.exchange!.marketOrderOpen({
73
- coin: 'BTC',
74
- isBuy: true,
75
- size: '0.05',
76
- midPx: '45200',
77
- tpTriggerPx: '47000',
78
- slTriggerPx: '44000',
79
- // slippage 默认 0.08
80
- });
81
-
82
- // 市价平仓
83
- await sdk.exchange!.marketOrderClose({
84
- coin: 'BTC',
85
- isBuy: false,
86
- size: '0.05',
87
- midPx: '45000',
88
- });
89
-
90
- // 绑定 TP/SL 到已有持仓（按位置绑定）
91
- await sdk.exchange!.bindTpslByOrderId({
92
- coin: 'BTC',
93
- isBuy: true, // 持仓方向
94
- tpTriggerPx: '47000',
95
- slTriggerPx: '44000',
96
- });
97
-
98
- // 更新杠杆
99
- await sdk.exchange!.updateLeverage({
100
- coin: 'BTC',
101
- leverage: 5,
102
- isCross: true,
103
- });
104
-
105
- // 撤单（可批量）
106
- await sdk.exchange!.cancelOrder([
107
- { coin: 'BTC', oid: 12345 },
108
- { coin: 'ETH', oid: 67890 },
109
- ]);
110
- ```
111
-
112
- ### 授权持久化代理（主钱包签名）
113
- ```ts
114
- // 准备主钱包签名的 EIP-712 数据（Approve Agent）
115
- const approve = sdk.exchange!.prepareApproveAgent();
116
- // 业务方使用主钱包签名（示例）
117
- const signature = await mainWallet.signTypedData(approve.domain, approve.types, approve.message);
118
- // 发送请求
119
- await sdk.exchange!.sendApproveAgent({ action: approve.message, nonce: approve.nonce, signature });
120
-
121
- // 准备并签名 Builder 费用
122
- const builderFee = sdk.exchange!.prepareApproveBuilderFee({ builder: '0xBuilder', maxFee: '0.1%' });
123
- const sig2 = await mainWallet.signTypedData(builderFee.domain, builderFee.types, builderFee.message);
124
- await sdk.exchange!.sendApproveBuilderFee({ action: builderFee.message, nonce: builderFee.nonce, signature: sig2 });
125
- ```
126
-
127
- ### WebSocket 实时数据
128
- ```ts
129
- await sdk.connectWebSocket();
130
-
131
- // 订阅价格
132
- sdk.ws.subscribeToAllMids((prices) => {
133
- console.log('价格更新:', prices);
134
- });
135
-
136
- // 订阅用户综合数据
137
- sdk.ws.subscribeToWebData2('0xYourEOA', (webData2) => {
138
- console.log('用户数据:', webData2);
139
- });
1
+ # Hyperliquid Perpetuals SDK
2
+
3
+ 一个简化的 Hyperliquid 永续合约交易 SDK，专为前端应用设计。
4
+
5
+ ## 特性
6
+
7
+ - ✅ 仅核心API：最重要的交易与查询能力
8
+ - ✅ 永续合约专用：不包含现货功能
9
+ - ✅ TypeScript：完善的类型定义
10
+ - ✅ WebSocket：实时数据订阅
11
+ - ✅ 前端友好：基于 fetch API 的轻量实现
12
+
13
+ ## 安装
14
+
15
+ ```bash
16
+ yarn add @debank/hyperliquid-perp-sdk
17
+ # or
18
+ npm i @debank/hyperliquid-perp-sdk
19
+ ```
20
+
21
+ ## 快速开始
22
+
23
+ ### 仅查询（无需私钥）
24
+ ```ts
25
+ import { HyperliquidSDK } from '@debank/hyperliquid-perp-sdk';
26
+
27
+ const sdk = new HyperliquidSDK({
28
+ masterAddress: '0xYourEOA',
29
+ isTestnet: true,
30
+ });
31
+
32
+ // 获取所有中间价
33
+ const prices = await sdk.info.getAllMids();
34
+
35
+ // 获取市场元数据与资产上下文
36
+ const canUseCache = true; //默认使用缓存，多次请求并发去重 ，需要刷新传false
37
+ const [meta, assetCtxs] = await sdk.info.metaAndAssetCtxs(canUseCache);
38
+
39
+
40
+ // 获取账户综合状态
41
+ const account = await sdk.info.getClearingHouseState();
42
+ ```
43
+
44
+ ### 交易（需要提供代理私钥、公钥、名称）
45
+ ```ts
46
+ const sdk = new HyperliquidSDK({
47
+ masterAddress: '0xYourEOA',
48
+ agentPrivateKey: '0xYourAgentPrivKey',
49
+ agentPublicKey: '0xYourAgentPubKey',
50
+ agentName: 'MyAgent',
51
+ isTestnet: true,
52
+ });
53
+
54
+ // 限价下单
55
+ await sdk.exchange!.placeOrder({
56
+ coin: 'BTC',
57
+ isBuy: true,
58
+ sz: '0.1',
59
+ limitPx: '45000',
60
+ orderType: { limit: { tif: 'Gtc' } },
61
+ });
62
+
63
+ // 批量下单
64
+ await sdk.exchange!.multiOrder({
65
+ orders: [
66
+ { coin: 'ETH', isBuy: true, sz: '1', limitPx: '3000', orderType: { limit: { tif: 'Ioc' } } },
67
+ { coin: 'SOL', isBuy: false, sz: '10', limitPx: '150', orderType: { limit: { tif: 'Ioc' } } },
68
+ ],
69
+ });
70
+
71
+ // 市价开仓（带可选的 TP/SL 触发单）
72
+ await sdk.exchange!.marketOrderOpen({
73
+ coin: 'BTC',
74
+ isBuy: true,
75
+ size: '0.05',
76
+ midPx: '45200',
77
+ tpTriggerPx: '47000',
78
+ slTriggerPx: '44000',
79
+ // slippage 默认 0.08
80
+ });
81
+
82
+ // 市价平仓
83
+ await sdk.exchange!.marketOrderClose({
84
+ coin: 'BTC',
85
+ isBuy: false,
86
+ size: '0.05',
87
+ midPx: '45000',
88
+ });
89
+
90
+ // 绑定 TP/SL 到已有持仓（按位置绑定）
91
+ await sdk.exchange!.bindTpslByOrderId({
92
+ coin: 'BTC',
93
+ isBuy: true, // 持仓方向
94
+ tpTriggerPx: '47000',
95
+ slTriggerPx: '44000',
96
+ });
97
+
98
+ // 更新杠杆
99
+ await sdk.exchange!.updateLeverage({
100
+ coin: 'BTC',
101
+ leverage: 5,
102
+ isCross: true,
103
+ });
104
+
105
+ // 撤单（可批量）
106
+ await sdk.exchange!.cancelOrder([
107
+ { coin: 'BTC', oid: 12345 },
108
+ { coin: 'ETH', oid: 67890 },
109
+ ]);
110
+ ```
111
+
112
+ ### 授权持久化代理（主钱包签名）
113
+ ```ts
114
+ // 准备主钱包签名的 EIP-712 数据（Approve Agent）
115
+ const approve = sdk.exchange!.prepareApproveAgent();
116
+ // 业务方使用主钱包签名（示例）
117
+ const signature = await mainWallet.signTypedData(approve.domain, approve.types, approve.message);
118
+ // 发送请求
119
+ await sdk.exchange!.sendApproveAgent({ action: approve.message, nonce: approve.nonce, signature });
120
+
121
+ // 准备并签名 Builder 费用
122
+ const builderFee = sdk.exchange!.prepareApproveBuilderFee({ builder: '0xBuilder', maxFee: '0.1%' });
123
+ const sig2 = await mainWallet.signTypedData(builderFee.domain, builderFee.types, builderFee.message);
124
+ await sdk.exchange!.sendApproveBuilderFee({ action: builderFee.message, nonce: builderFee.nonce, signature: sig2 });
125
+ ```
126
+
127
+ ### WebSocket 实时数据
128
+ ```ts
129
+ await sdk.connectWebSocket();
130
+
131
+ // 订阅价格
132
+ sdk.ws.subscribeToAllMids((prices) => {
133
+ console.log('价格更新:', prices);
134
+ });
135
+
136
+ // 订阅用户综合数据
137
+ sdk.ws.subscribeToWebData2('0xYourEOA', (webData2) => {
138
+ console.log('用户数据:', webData2);
139
+ });
140
140
  ```
package/dist/client/exchange-client.d.ts CHANGED
@@ -13,12 +13,16 @@ export declare class ExchangeClient {
13
13
  private builder?;
14
14
  private readonly symbolConversion;
15
15
  constructor(config: ExchangeClientConfig);
16
- initAccount(masterAddress: string, agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
16
+ initAccount(masterAddress: string, agentPrivateKey?: string, agentPublicKey?: string, agentName?: string): void;
17
+ initOrUpdateAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
18
+ /**
19
+ * Check if agent is set
20
+ */
21
+ get isHaveAgent(): boolean;
17
22
  /**
18
23
  * Get the wallet address
19
24
  */
20
25
  get address(): string;
21
- updateExchangeAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
22
26
  private getAgentPrivateKey;
23
27
  /**
24
28
  * @deprecated This method is deprecated. Use the new builder configuration in constructor instead.
package/dist/client/exchange-client.js CHANGED
@@ -82,21 +82,34 @@ class ExchangeClient {
82
82
  }
83
83
  initAccount(masterAddress, agentPrivateKey, agentPublicKey, agentName) {
84
84
  this.masterAddress = masterAddress;
85
+ if (agentPrivateKey && agentPublicKey) {
86
+ this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
87
+ this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
88
+ this.agentName = agentName || '';
89
+ }
90
+ else {
91
+ this.agentPrivateKey = undefined;
92
+ this.agentPublicKey = undefined;
93
+ this.agentName = undefined;
94
+ }
95
+ }
96
+ initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName) {
85
97
  this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
86
98
  this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
87
99
  this.agentName = agentName || '';
88
100
  }
101
+ /**
102
+ * Check if agent is set
103
+ */
104
+ get isHaveAgent() {
105
+ return !!this.agentPrivateKey && !!this.agentPublicKey;
106
+ }
89
107
  /**
90
108
  * Get the wallet address
91
109
  */
92
110
  get address() {
93
111
  return this.masterAddress;
94
112
  }
95
- updateExchangeAgent(agentPrivateKey, agentPublicKey, agentName) {
96
- this.agentPrivateKey = agentPrivateKey.startsWith('0x') ? agentPrivateKey : ethUtil.addHexPrefix(agentPrivateKey);
97
- this.agentPublicKey = agentPublicKey.startsWith('0x') ? agentPublicKey : ethUtil.addHexPrefix(agentPublicKey);
98
- this.agentName = agentName || '';
99
- }
100
113
  getAgentPrivateKey() {
101
114
  if (!this.agentPrivateKey) {
102
115
  throw new Error('Agent private key is not set');
@@ -466,6 +479,9 @@ class ExchangeClient {
466
479
  * Returns typed data that needs to be signed by the main wallet
467
480
  */
468
481
  prepareApproveAgent() {
482
+ if (!this.isHaveAgent) {
483
+ throw new Error('account not have agent, please set agent first.');
484
+ }
469
485
  const nonce = Date.now();
470
486
  const action = {
471
487
  type: constants_1.ExchangeType.APPROVE_AGENT,
package/dist/hyperliquid-sdk.d.ts CHANGED
@@ -29,7 +29,12 @@ export declare class HyperliquidSDK {
29
29
  * Get wallet address (only available if private key was provided)
30
30
  */
31
31
  get address(): string;
32
- initAccount(masterAddress: string, agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
32
+ initAccount(masterAddress: string, agentPrivateKey?: string, agentPublicKey?: string, agentName?: string): void;
33
+ /**
34
+ * Check if agent is set for trading
35
+ */
36
+ get isHaveAgent(): boolean;
37
+ initOrUpdateAgent(agentPrivateKey: string, agentPublicKey: string, agentName?: string): void;
33
38
  /**
34
39
  * Connect to WebSocket for real-time data
35
40
  */
package/dist/hyperliquid-sdk.js CHANGED
@@ -71,6 +71,21 @@ class HyperliquidSDK {
71
71
  });
72
72
  }
73
73
  }
74
+ /**
75
+ * Check if agent is set for trading
76
+ */
77
+ get isHaveAgent() {
78
+ var _a;
79
+ return ((_a = this.exchange) === null || _a === void 0 ? void 0 : _a.isHaveAgent) || false;
80
+ }
81
+ initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName) {
82
+ if (!this.exchange) {
83
+ throw new Error('no exchange client, first initAccount');
84
+ }
85
+ if (this.exchange) {
86
+ this.exchange.initOrUpdateAgent(agentPrivateKey, agentPublicKey, agentName);
87
+ }
88
+ }
74
89
  /**
75
90
  * Connect to WebSocket for real-time data
76
91
  */
package/package.json CHANGED
@@ -1,37 +1,37 @@
1
- {
2
- "name": "@rabby-wallet/hyperliquid-sdk",
3
- "version": "1.0.9",
4
- "description": "Simplified Hyperliquid Perpetuals Trading SDK for Frontend Applications",
5
- "main": "dist/index.js",
6
- "types": "dist/index.d.ts",
7
- "files": [
8
- "dist"
9
- ],
10
- "publishConfig": {
11
- "access": "public"
12
- },
13
- "scripts": {
14
- "build": "rimraf dist && tsc",
15
- "preversion": "npm run build",
16
- "prepublishOnly": "npm run build"
17
- },
18
- "author": "",
19
- "license": "UNLICENSED",
20
- "dependencies": {
21
- "@ethereumjs/util": "9.0.0",
22
- "@metamask/eth-sig-util": "5.1.0",
23
- "@msgpack/msgpack": "3.1.2",
24
- "@noble/hashes": "1.8.0",
25
- "ethereum-cryptography": "2.2.1"
26
- },
27
- "devDependencies": {
28
- "@types/node": "24.3.1",
29
- "prettier": "2.7.1",
30
- "rimraf": "6.0.0",
31
- "typescript": "5.9.2"
32
- },
33
- "engines": {
34
- "node": ">=16.0.0"
35
- },
36
- "packageManager": "yarn@1.22.22"
37
- }
1
+ {
2
+ "name": "@rabby-wallet/hyperliquid-sdk",
3
+ "version": "1.1.0-beta.1",
4
+ "description": "Simplified Hyperliquid Perpetuals Trading SDK for Frontend Applications",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "publishConfig": {
11
+ "access": "public"
12
+ },
13
+ "scripts": {
14
+ "build": "rimraf dist && tsc",
15
+ "preversion": "npm run build",
16
+ "prepublishOnly": "npm run build"
17
+ },
18
+ "author": "",
19
+ "license": "UNLICENSED",
20
+ "dependencies": {
21
+ "@ethereumjs/util": "9.0.0",
22
+ "@metamask/eth-sig-util": "5.1.0",
23
+ "@msgpack/msgpack": "3.1.2",
24
+ "@noble/hashes": "1.8.0",
25
+ "ethereum-cryptography": "2.2.1"
26
+ },
27
+ "devDependencies": {
28
+ "@types/node": "24.3.1",
29
+ "prettier": "2.7.1",
30
+ "rimraf": "6.0.0",
31
+ "typescript": "5.9.2"
32
+ },
33
+ "engines": {
34
+ "node": ">=16.0.0"
35
+ },
36
+ "packageManager": "yarn@1.22.22"
37
+ }