Hyperliquid API 端点速查：常用请求与参数详解

这是一份按端点组织的速查表，方便你直接搜某个 type（比如 clearinghouseState、candleSnapshot）查它的请求参数和返回字段。完整协议说明看 API 概览，纯 Python 用法看 Python SDK 文档。

准备好开始交易了吗？

免 KYC、3 分钟开户。通过本站邀请链接注册 Hyperliquid，享 4% 手续费折扣。

所有 Info 端点都是 POST https://api.hyperliquid.xyz/info，请求体里用 type 字段区分。

⚠️ 原始 type 名 vs SDK 方法名

你在搜索里看到的 clearinghouseState、candleSnapshot 是 API 的原始 type 名。Python SDK 把它们封装成了更顺口的方法名（如 info.user_state()），下面每个端点都标了对应关系，两边对得上。

按用途速查

我想做什么	用哪个端点	备注
查账户余额 / 持仓	`clearinghouseState`	需要传 `user` 地址
查所有交易对实时中间价	`allMids`	最轻量的价格接口
查标记价 / 资金费率 / 未平仓量	`metaAndAssetCtxs`	一次返回所有交易对
查美股 / ETF 永续行情（xyz:NVDA 等）	`metaAndAssetCtxs` + `"dex":"xyz"`	必须加 dex 参数，否则返回加密永续
拉 K 线 / OHLCV 历史	`candleSnapshot`	支持 1m~1d 周期，传毫秒时间戳
查 L2 订单簿深度	`l2Book`	传 `coin` 参数
查交易对最大杠杆和数量精度	`meta`	下单前先查 `szDecimals`
查当前挂单	`openOrders`	需要传 `user` 地址
查成交历史（含清算）	`userFills`	需要传 `user` 地址
下单 / 撤单 / 改单	Exchange API `/exchange`	每次请求需要钱包签名
实时行情推送（低延迟）	WebSocket	延迟 10-50ms，见 API 概览

Info API 端点

clearinghouseState — 永续账户状态

用户最常查的端点，返回永续合约账户的保证金、持仓、账户总价值。注意原始 type 名是 clearinghouseState，不是 userState。

请求

{ "type": "clearinghouseState", "user": "0xYourAddress" }

返回关键字段

字段	含义
`marginSummary.accountValue`	账户总价值（USDC）
`marginSummary.totalRawUsd`	持仓和余额的原始美元值
`crossMarginSummary`	全仓保证金汇总
`assetPositions[].position`	每个持仓：`coin` 币种、`szi` 仓位大小、`entryPx` 开仓均价、`unrealizedPnl` 浮盈
`withdrawable`	可提现金额

SDK 方法：info.user_state(address)

现货账户用 spotClearinghouseState，返回结构里是 balances 数组。

candleSnapshot — K 线 / OHLCV 历史

拉历史 K 线（即 OHLCV：开高低收量）做回测或画图。

请求

{
  "type": "candleSnapshot",
  "req": {
    "coin": "ETH",
    "interval": "1h",
    "startTime": 1730000000000,
    "endTime": 1730100000000
  }
}

interval 可选：1m 5m 15m 1h 4h 1d 等。时间是毫秒时间戳。

返回关键字段：数组，每根 K 线含 t（开始时间）、o h l c（开高低收）、v（成交量）、n（成交笔数）。

SDK 方法：info.candles_snapshot(coin, interval, startTime, endTime)

l2Book — L2 订单簿

请求

{ "type": "l2Book", "coin": "ETH" }

返回关键字段：levels 是两个数组 [bids, asks]，每档含 px（价格）、sz（数量）、n（订单数）。

SDK 方法：info.l2_snapshot(coin)

allMids — 所有中间价

请求

{ "type": "allMids" }

返回：一个对象，键是币种、值是中间价字符串，如 {"ETH": "3001.5", "BTC": "62000.0"}。适合快速取价，比订单簿轻量。

SDK 方法：info.all_mids()

metaAndAssetCtxs — 元数据 + 实时行情

一次拿到所有交易对的元数据和实时上下文（标记价、资金费率、未平仓量）。

请求

{ "type": "metaAndAssetCtxs" }

返回：长度为 2 的数组。[0].universe 是交易对元数据；[1] 是对应的实时上下文，每项含 markPx（标记价）、funding（资金费率）、openInterest（未平仓）、dayNtlVlm（24h 成交额）。

SDK 方法：info.meta_and_asset_ctxs()

metaAndAssetCtxs（TradFi）— 美股 / ETF 合成永续行情

Hyperliquid 的 TradFi 合成永续（xyz:NVDA、xyz:TSLA、xyz:CXMT、xyz:EWY 等）独立于加密永续市场。查询 TradFi 行情需在请求体加 "dex":"xyz" 参数；不加则返回加密永续。

请求

{ "type": "metaAndAssetCtxs", "dex": "xyz" }

返回：结构与加密版相同——[0].universe 是 TradFi 交易对元数据，[1] 是对应实时行情（markPx 标记价、funding 资金费率、openInterest 未平仓量、dayNtlVlm 24h 成交额）。ticker 格式为 xyz:<代码>，例如 xyz:NVDA、xyz:GOOGL、xyz:EWY。

meta — 交易对元数据

请求：{ "type": "meta" }

返回：universe 数组，每个交易对含 name、maxLeverage（最大杠杆）、szDecimals（数量精度）。

SDK 方法：info.meta()

用户相关端点

下面这些都需要传 user 地址。

type	用途	SDK 方法
`openOrders`	当前所有挂单	`info.open_orders(addr)`
`userFills`	成交历史	`info.user_fills(addr)`
`userFunding`	资金费率收付历史	`info.user_funding(addr, start, end)`
`historicalOrders`	历史订单	`info.historical_orders(addr)`
`userRateLimit`	当前速率限制状态	—
`subAccounts`	子账户列表	—

Exchange API 端点

所有交易操作走 POST /exchange，请求体含 action、nonce（毫秒时间戳）、signature。每个请求都要钱包签名，建议直接用 Python SDK 处理签名，别手动拼。

action	用途	SDK 方法
`order`	下单（单笔或批量）	`exchange.order(...)` / `market_open(...)`
`cancel`	按 oid 撤单	`exchange.cancel(coin, oid)`
`cancelByCloid`	按客户端订单 ID 撤单	`exchange.cancel_by_cloid(...)`
`modify`	改单	`exchange.modify_order(...)`
`updateLeverage`	调整杠杆	`exchange.update_leverage(...)`
`usdSend`	转账 USDC	`exchange.usd_transfer(...)`
`withdraw3`	提现	`exchange.withdraw_from_bridge(...)`
`vaultTransfer`	金库存取	`exchange.vault_usd_transfer(...)`
`approveAgent`	授权 agent wallet	`exchange.approve_agent()`
`approveBuilderFee`	授权 builder code 抽成	`exchange.approve_builder_fee(...)`

🚨 价格精度

下单的 px 必须按交易对的 tick size 取整，否则会被 Invalid price 拒掉。szDecimals 从 meta 端点拿。

常见问题

如何查询 TradFi 永续（美股、ETF）的实时行情？

在 metaAndAssetCtxs 请求中加 "dex":"xyz" 参数：{ "type": "metaAndAssetCtxs", "dex": "xyz" }。返回的 universe 切换为 TradFi 市场，包含 xyz:NVDA、xyz:TSLA、xyz:EWY、xyz:CXMT 等合成永续的标记价、资金费率和未平仓量。只需要某个 TradFi ticker 的中间价时可用 allMids 再按 xyz: 前缀筛选。

OHLCV / K 线数据用哪个端点？

candleSnapshot。K 线即 OHLCV（开高低收量），用 interval 指定周期（1m 5m 15m 1h 4h 1d 等），startTime/endTime 传毫秒时间戳。SDK 方法：info.candles_snapshot(coin, interval, start, end)。

如何获取实时标记价、资金费率和未平仓量？

用 metaAndAssetCtxs，一次返回所有交易对的 markPx（标记价）、funding（资金费率）、openInterest（未平仓量）和 dayNtlVlm（24h 成交额）。只需要中间价的轻量场景用 allMids。

如何获取清算数据？

用户自身的清算事件通过 userFills 端点查询（每笔成交记录含方向和类型信息）；如需实时推送，订阅 WebSocket userFills 频道。全市场清算数据通过 WebSocket 订阅获取，具体频道和字段见 API 概览。

如何获取订单簿深度（Market Data）？

l2Book 端点，传 coin 参数，返回 levels[0]（bids）和 levels[1]（asks），每档含价格 px、数量 sz、订单数 n。如需实时流，用 WebSocket l2Book 订阅。

API 有速率限制吗？

有。Info API 公共端点按 IP 计限，Exchange API 写操作（下单/撤单）按地址计限，超限返回 HTTP 429。具体数值可能随官方调整，开发时建议在循环请求间加指数退避机制。详见 API 概览。

什么时候用 WebSocket，什么时候用 REST 轮询？

实时性要求高（监控行情、立刻感知订单成交）用 WebSocket，延迟约 10-50ms；偶尔查账户状态或拉历史数据用 REST Info API，延迟约 50-200ms。频繁 REST 轮询除了延迟高，还容易触发速率限制——有实时需求时优先用 WebSocket 订阅。WebSocket 订阅格式和频道列表见 API 概览。