1. 1. Hyperliquid API文档详解：WebSocket、HTTP接口与限流规则
    1. 1.1. 背景
    2. 1.2. API端点
      1. 1.2.1. 主网与测试网
      2. 1.2.2. SDK支持
    3. 1.3. HTTP接口
      1. 1.3.1. Info端点
        1. 1.3.1.1. 基础请求格式
        2. 1.3.1.2. 常用查询接口
          1. 1.3.1.2.1. 1. 获取所有币种中间价
          2. 1.3.1.2.2. 2. 获取用户未成交订单
          3. 1.3.1.2.3. 3. 获取用户账户状态
          4. 1.3.1.2.4. 4. 获取订单簿数据
          5. 1.3.1.2.5. 5. 获取元数据
        3. 1.3.1.3. 分页机制
        4. 1.3.1.4. 永续合约与现货
      2. 1.3.2. Exchange端点
        1. 1.3.2.1. 请求结构
        2. 1.3.2.2. 下单
        3. 1.3.2.3. 取消订单
        4. 1.3.2.4. 取消所有订单
        5. 1.3.2.5. 修改订单
        6. 1.3.2.6. USDC转账
        7. 1.3.2.7. TWAP订单
    4. 1.4. WebSocket接口
      1. 1.4.1. 连接
      2. 1.4.2. 订阅消息格式
      3. 1.4.3. 订阅类型
        1. 1.4.3.1. 1. 所有中间价 (allMids)
        2. 1.4.3.2. 2. 交易数据 (trades)
        3. 1.4.3.3. 3. 订单簿 (l2Book)
        4. 1.4.3.4. 4. K线数据 (candle)
        5. 1.4.3.5. 5. 用户订单更新 (orderUpdates)
        6. 1.4.3.6. 6. 用户成交记录 (userFills)
        7. 1.4.3.7. 7. 用户资金费率 (userFundings)
        8. 1.4.3.8. 8. 用户通知 (notification)
        9. 1.4.3.9. 9. 清算所状态 (clearinghouseState)
        10. 1.4.3.10. 10. 未成交订单 (openOrders)
        11. 1.4.3.11. 11. 资产上下文 (activeAssetCtx)
      4. 1.4.4. 取消订阅
      5. 1.4.5. WebSocket POST请求
    5. 1.5. 限流规则
      1. 1.5.1. IP级别限流
        1. 1.5.1.1. REST请求
        2. 1.5.1.2. WebSocket限制
        3. 1.5.1.3. EVM JSON-RPC
      2. 1.5.2. 地址级别限流
        1. 1.5.2.1. 请求限制
        2. 1.5.2.2. 未成交订单限制
        3. 1.5.2.3. 高拥堵时期
      3. 1.5.3. 批量请求
    6. 1.6. 最佳实践
      1. 1.6.1. 1. 使用WebSocket获取实时数据
      2. 1.6.2. 2. 处理重连
      3. 1.6.3. 3. 签名请求
      4. 1.6.4. 4. 限流管理
      5. 1.6.5. 5. 资产索引处理
    7. 1.7. 参考资料
    8. 1.8. 总结

Hyperliquid API文档详解：WebSocket、HTTP接口与限流规则

(Updated: )

Hyperliquid API文档详解：WebSocket、HTTP接口与限流规则

背景

Hyperliquid作为高性能去中心化交易所，提供了完善的API接口供开发者进行程序化交易和数据分析。本文将详细介绍Hyperliquid的WebSocket实时数据流、HTTP REST接口以及接口限流规则，帮助开发者快速接入Hyperliquid生态。

API端点

主网与测试网

环境 HTTP端点 WebSocket端点
主网 https://api.hyperliquid.xyz wss://api.hyperliquid.xyz/ws
测试网 https://api.hyperliquid-testnet.xyz wss://api.hyperliquid-testnet.xyz/ws

SDK支持

Hyperliquid官方和社区提供了多种语言的SDK：

HTTP接口

Hyperliquid的HTTP API主要分为两大类：Info端点（查询信息）和Exchange端点（交易操作）。

Info端点

Info端点用于获取交易所和用户相关信息，所有请求都使用POST方法发送到 https://api.hyperliquid.xyz/info。

基础请求格式

1
2
3
4
{
  "type": "<请求类型>",
  // 其他参数...
}

常用查询接口

1. 获取所有币种中间价
1
2
3
4
5
6
7
8
9
10
11
// 请求
{
  "type": "allMids"
}

// 响应
{
  "APE": "4.33245",
  "ARB": "1.21695",
  ...
}
2. 获取用户未成交订单
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 请求
{
  "type": "openOrders",
  "user": "0x..."  // 42字符十六进制地址
}

// 响应
[
  {
    "coin": "BTC",
    "limitPx": "29792.0",
    "oid": 91490942,
    "side": "A",
    "sz": "0.0",
    "timestamp": 1681247412573
  }
]
3. 获取用户账户状态
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 请求
{
  "type": "clearinghouseState",
  "user": "0x..."
}

// 响应
{
  "assetPositions": [...],
  "marginSummary": {
    "accountValue": 1000.0,
    "totalNtlPos": 500.0,
    "totalRawUsd": 500.0,
    "totalMarginUsed": 100.0
  },
  "withdrawable": 900.0
}
4. 获取订单簿数据
1
2
3
4
5
6
7
// 请求
{
  "type": "l2Book",
  "coin": "BTC"
}

// 响应包含买卖盘深度数据
5. 获取元数据
1
2
3
4
5
6
// 请求
{
  "type": "meta"
}

// 响应包含所有交易对信息、资产索引等

分页机制

返回时间范围数据的接口最多返回500个元素。要查询更大范围，使用最后返回的时间戳作为下一次请求的 startTime。

永续合约与现货

  • 永续合约: coin 使用 meta 响应中返回的名称
  • 现货: coin 格式为 PURR/USDC 或 @{index}（如 @107 表示HYPE）

Exchange端点

Exchange端点用于执行交易操作，所有请求发送到 https://api.hyperliquid.xyz/exchange，需要签名认证。

请求结构

1
2
3
4
5
6
7
8
9
10
11
{
  "action": {
    "type": "<操作类型>",
    // 操作参数
  },
  "nonce": 1704067200000,  // 毫秒时间戳
  "signature": {
    // EIP-712签名数据
  },
  "vaultAddress": "0x..."  // 可选，用于子账户或金库
}

下单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "action": {
    "type": "order",
    "orders": [{
      "a": 0,           // 资产索引
      "b": true,        // 是否买入
      "p": "50000",     // 价格
      "s": "0.1",       // 数量
      "r": false,       // 是否reduceOnly
      "t": {
        "limit": {
          "tif": "Gtc"  // Good-Til-Cancelled
        }
      }
    }],
    "grouping": "na"
  },
  "nonce": 1704067200000,
  "signature": {...}
}

订单类型 (TIF)：

  • Gtc (Good-Til-Cancelled): 订单持续有效直到成交或取消
  • Ioc (Immediate-Or-Cancel): 立即成交或取消未成交部分
  • Alo (Add-Liquidity-Only): Post-Only，只做Maker

取消订单

1
2
3
4
5
6
7
8
9
10
11
{
  "action": {
    "type": "cancel",
    "cancels": [{
      "a": 0,           // 资产索引
      "oid": 12345678   // 订单ID
    }]
  },
  "nonce": 1704067200000,
  "signature": {...}
}

取消所有订单

1
2
3
4
5
6
7
8
9
10
11
{
  "action": {
    "type": "cancelByCloid",
    "cancels": [{
      "asset": 0,
      "cloid": "0x1234..."  // 客户端订单ID
    }]
  },
  "nonce": 1704067200000,
  "signature": {...}
}

修改订单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "action": {
    "type": "modify",
    "oid": 12345678,
    "order": {
      "a": 0,
      "b": true,
      "p": "51000",
      "s": "0.2",
      "r": false,
      "t": { "limit": { "tif": "Gtc" } }
    }
  },
  "nonce": 1704067200000,
  "signature": {...}
}

USDC转账

1
2
3
4
5
6
7
8
9
{
  "action": {
    "type": "usdcTransfer",
    "destination": "0x...",
    "amount": "100.0"
  },
  "nonce": 1704067200000,
  "signature": {...}
}

TWAP订单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "action": {
    "type": "twapOrder",
    "twap": {
      "a": 0,
      "b": true,
      "s": "1.0",
      "r": false,
      "m": 10,          // 分钟数
      "t": { "limit": { "tif": "Gtc" } }
    }
  },
  "nonce": 1704067200000,
  "signature": {...}
}

WebSocket接口

WebSocket提供实时数据流，适合需要低延迟数据更新的场景。

连接

1
wscat -c wss://api.hyperliquid.xyz/ws

重要提示: 所有自动化用户应处理服务器断开连接并优雅重连。断开可能定期发生且无通知。重连期间错过的数据将在重连时的快照确认中呈现。

订阅消息格式

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "<订阅类型>",
    // 其他参数
  }
}

订阅类型

1. 所有中间价 (allMids)

1
2
3
4
{
  "method": "subscribe",
  "subscription": { "type": "allMids" }
}

2. 交易数据 (trades)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

3. 订单簿 (l2Book)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

4. K线数据 (candle)

支持的间隔: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M

1
2
3
4
5
6
7
8
{
  "method": "subscribe",
  "subscription": {
    "type": "candle",
    "coin": "BTC",
    "interval": "1h"
  }
}

5. 用户订单更新 (orderUpdates)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "orderUpdates",
    "user": "0x..."
  }
}

6. 用户成交记录 (userFills)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "userFills",
    "user": "0x..."
  }
}

7. 用户资金费率 (userFundings)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "userFundings",
    "user": "0x..."
  }
}

8. 用户通知 (notification)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "notification",
    "user": "0x..."
  }
}

9. 清算所状态 (clearinghouseState)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "clearinghouseState",
    "user": "0x..."
  }
}

10. 未成交订单 (openOrders)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "openOrders",
    "user": "0x..."
  }
}

11. 资产上下文 (activeAssetCtx)

1
2
3
4
5
6
7
{
  "method": "subscribe",
  "subscription": {
    "type": "activeAssetCtx",
    "coin": "BTC"
  }
}

取消订阅

1
2
3
4
{
  "method": "unsubscribe",
  "subscription": { ... }  // 与订阅时相同的对象
}

WebSocket POST请求

WebSocket也可用于发送交易请求，与HTTP Exchange端点功能相同：

1
2
3
4
5
6
7
8
9
{
  "method": "post",
  "id": "unique-request-id",
  "request": {
    "action": { ... },
    "nonce": 1704067200000,
    "signature": { ... }
  }
}

限流规则

IP级别限流

REST请求

  • 总权重限制: 每分钟1200权重

权重计算：

请求类型 权重
Exchange API请求 1 + floor(batch_length / 40)
单个操作 1
79个批量订单 2
l2Book, allMids, clearinghouseState, orderStatus, spotClearinghouseState, exchangeStatus 2
userRole 60
其他Info请求 20
Explorer API请求 40

额外权重（按返回项目数）：

  • recentTrades, historicalOrders, userFills, userFillsByTime, fundingHistory, userFunding, nonUserFundingUpdates, twapHistory, userTwapSliceFills, userTwapSliceFillsByTime, delegatorHistory, delegatorRewards, validatorStats: 每20个项目增加权重
  • candleSnapshot: 每60个项目增加权重

WebSocket限制

限制项 数值
最大WebSocket连接数 10
每分钟新WebSocket连接数 30
最大WebSocket订阅数 1000
用户特定订阅的唯一用户数 10
每分钟WebSocket消息数 2000
同时进行中的POST消息数 100

EVM JSON-RPC

  • rpc.hyperliquid.xyz/evm: 每分钟100个请求

地址级别限流

地址级别限制按用户计算，子账户视为独立用户。

请求限制

  • 基础逻辑: 自地址创建以来每交易1 USDC允许1个请求
  • 初始缓冲: 10000个请求
  • 限流后: 每10秒允许1个请求
  • 取消订单限制: min(limit + 100000, limit * 2)

此限制仅适用于操作（actions），不适用于信息查询（info requests）。

未成交订单限制

  • 默认限制: 1000个未成交订单
  • 额外配额: 每5M USDC交易量增加1个订单
  • 上限: 5000个未成交订单
  • 限制触发时: reduce-only订单和触发订单将被拒绝

高拥堵时期

在高拥堵期间，地址被限制使用其做市商份额百分比2倍的区块空间。

批量请求

  • IP限流: n个订单的批量请求视为1个请求
  • 地址限流: n个订单的批量请求视为n个请求

最佳实践

1. 使用WebSocket获取实时数据

WebSocket延迟最低，适合实时数据更新：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import asyncio
import websockets
import json

async def subscribe_trades():
    uri = "wss://api.hyperliquid.xyz/ws"
    async with websockets.connect(uri) as ws:
        # 订阅BTC交易数据
        subscribe_msg = {
            "method": "subscribe",
            "subscription": {"type": "trades", "coin": "BTC"}
        }
        await ws.send(json.dumps(subscribe_msg))
        
        async for msg in ws:
            data = json.loads(msg)
            print(data)

2. 处理重连

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import asyncio
import websockets
import json

async def connect_with_reconnect():
    while True:
        try:
            async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws:
                # 处理消息
                async for msg in ws:
                    process_message(msg)
        except Exception as e:
            print(f"Disconnected: {e}, reconnecting...")
            await asyncio.sleep(5)

3. 签名请求

使用Python SDK进行签名：

1
2
3
4
5
6
7
8
9
10
11
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants

# 初始化
exchange = Exchange(
    "0x你的私钥",
    constants.MAINNET_API_URL
)

# 下单
order_result = exchange.order("BTC", True, 0.1, 50000, {"limit": {"tif": "Gtc"}})

4. 限流管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import time
from collections import deque

class RateLimiter:
    def __init__(self, max_weight=1200, window=60):
        self.max_weight = max_weight
        self.window = window
        self.requests = deque()
    
    def can_request(self, weight=1):
        now = time.time()
        # 清理过期请求
        while self.requests and self.requests[0][0] < now - self.window:
            self.requests.popleft()
        
        # 检查权重
        current_weight = sum(w for _, w in self.requests)
        if current_weight + weight <= self.max_weight:
            self.requests.append((now, weight))
            return True
        return False
    
    def wait_time(self, weight=1):
        if not self.requests:
            return 0
        # 计算需要等待的时间
        current_weight = sum(w for _, w in self.requests)
        if current_weight + weight <= self.max_weight:
            return 0
        return self.requests[0][0] + self.window - time.time()

5. 资产索引处理

1
2
3
4
5
6
7
8
9
10
11
12
13
def get_asset_index(coin, meta, spot_meta):
    """获取资产索引"""
    # 永续合约
    for i, asset in enumerate(meta['universe']):
        if asset['name'] == coin:
            return i
    
    # 现货
    for i, asset in enumerate(spot_meta['universe']):
        if asset['name'] == coin:
            return 10000 + i
    
    return None

参考资料

总结

Hyperliquid提供了完整的WebSocket和HTTP API接口，支持程序化交易和数据分析。关键要点：

  1. 双端点架构: Info端点用于查询，Exchange端点用于交易
  2. WebSocket实时数据: 支持交易、订单簿、K线等多种订阅
  3. 严格的限流规则: IP级别和地址级别双重限制
  4. 签名认证: Exchange操作需要EIP-712签名
  5. 批量操作支持: 提高效率但需注意限流计算

开发者应根据实际需求选择合适的数据获取方式，并严格遵守限流规则，确保稳定可靠的API接入。