From 7e35e1099ee348a2e6c50c2140ee37acb2890086 Mon Sep 17 00:00:00 2001 From: Ake <10195782+akegaviar@users.noreply.github.com> Date: Wed, 24 Jun 2026 14:53:57 +0800 Subject: [PATCH 1/2] docs(hyperliquid): fix 4 flagged HL method pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - perp-dex-limits: add the required `dex` param to the curl + OpenAPI spec, document the real response (open interest caps), and add Python (hyperliquid-python-sdk) + TypeScript (@nktkas/hyperliquid) examples. Verified live with dex="xyz" (curl, Python SDK, and nktkas all match). - eth-subscribe-syncing: add a WebSocket `## Example request` CodeGroup (wscat + web3.py + ethers + viem), matching the other eth_subscribe pages. All four transports verified against the live endpoint. - aligned-quote-token-info: deprecate in place — Hyperliquid removed the method (~Jun 2026, nktkas #154); the API no longer recognizes the type. - batch-clearinghouse-states: deprecate in place — never an official public method; returns null for every address. Points to clearinghouseState per-user. Endpoints/keys unchanged. Deprecations keep the URLs (both still get agent-read traffic, now corrected instead of misleading). --- .../hypercore_info/info_perp_dex_limits.json | 35 +++++++- .../hyperliquid-evm-eth-subscribe-syncing.mdx | 82 +++++++++++++++++++ ...erliquid-info-aligned-quote-token-info.mdx | 10 +-- ...liquid-info-batch-clearinghouse-states.mdx | 8 +- .../hyperliquid-info-perp-dex-limits.mdx | 59 +++++++++++-- 5 files changed, 176 insertions(+), 18 deletions(-) diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json b/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json index 789b6472..383b3a8a 100644 --- a/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json +++ b/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json @@ -32,10 +32,16 @@ "enum": [ "perpDexLimits" ] + }, + "dex": { + "type": "string", + "description": "Name of the builder-deployed perp DEX. The empty string is not allowed.", + "default": "xyz" } }, "required": [ - "type" + "type", + "dex" ] } } @@ -47,7 +53,32 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "nullable": true, + "properties": { + "totalOiCap": { + "type": "string", + "description": "Total open interest cap across the DEX." + }, + "oiSzCapPerPerp": { + "type": "string", + "description": "Open interest size cap per perpetual." + }, + "maxTransferNtl": { + "type": "string", + "description": "Maximum transfer notional amount." + }, + "coinToOiCap": { + "type": "array", + "description": "Array of [coin, oiCap] tuples giving the open interest cap per asset.", + "items": { + "type": "array", + "items": { + "type": "string" + } + } + } + } } } } diff --git a/reference/hyperliquid-evm-eth-subscribe-syncing.mdx b/reference/hyperliquid-evm-eth-subscribe-syncing.mdx index 6c06c578..d5303e72 100644 --- a/reference/hyperliquid-evm-eth-subscribe-syncing.mdx +++ b/reference/hyperliquid-evm-eth-subscribe-syncing.mdx @@ -372,6 +372,88 @@ const monitor = new NodeHealthMonitor('wss://hyperliquid-mainnet.core.chainstack monitor.connect(); ``` +## Example request + +`eth_subscribe("syncing")` runs over a WebSocket connection. After subscribing, the node sends a notification with the current state and then another on every change: `false` when fully synced, or an object with `startingBlock`, `currentBlock`, and `highestBlock` while syncing. The Shell tab uses `wscat` for a quick check; the Python, JavaScript, and TypeScript tabs use the WebSocket transport of each library. + + + +```shell wscat +$ wscat -c wss://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/evm +# Wait for the connection to be established + +Connected (press CTRL+C to quit) + +> {"id":1,"jsonrpc":"2.0","method":"eth_subscribe","params":["syncing"]} +< {"jsonrpc":"2.0","id":1,"result":"0x4f9f6872aa4c474b686cf23e352b725c"} + +# A notification is sent immediately with the current state, then on every change. +# When the node is fully synced: +< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x4f9f6872aa4c474b686cf23e352b725c","result":false}} + +# When the node is syncing: +< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x4f9f6872aa4c474b686cf23e352b725c","result":{"startingBlock":"0x0","currentBlock":"0x1234","highestBlock":"0x5678"}}} +``` + +```python web3.py +import asyncio +from web3 import AsyncWeb3, WebSocketProvider + + +async def main(): + async with AsyncWeb3(WebSocketProvider("YOUR_CHAINSTACK_ENDPOINT")) as w3: + subscription_id = await w3.eth.subscribe("syncing") + print(f"Subscribed with ID: {subscription_id}") + + async for message in w3.socket.process_subscriptions(): + # result is False when synced, or a progress object while syncing + print(f"Sync status: {message['result']}") + + +asyncio.run(main()) +``` + +```javascript ethers.js +import { WebSocketProvider } from "ethers"; + +const provider = new WebSocketProvider("YOUR_CHAINSTACK_ENDPOINT"); + +// ethers has no high-level "syncing" event, so listen on the underlying +// WebSocket and send the eth_subscribe request directly. +provider.websocket.addEventListener("message", (event) => { + const message = JSON.parse(event.data.toString()); + if (message.method === "eth_subscription") { + // result is false when synced, or a progress object while syncing + console.log("Sync status:", message.params.result); + } +}); + +await provider.send("eth_subscribe", ["syncing"]); +``` + +```typescript viem +import { createPublicClient, webSocket } from "viem"; + +const client = createPublicClient({ + transport: webSocket("YOUR_CHAINSTACK_ENDPOINT"), +}); + +// viem has no high-level syncing action, so use the transport's low-level subscribe. +const { unsubscribe } = await client.transport.subscribe({ + params: ["syncing"], + onData: (data) => { + // data.result is false when synced, or a progress object while syncing + console.log("Sync status:", data.result); + }, +}); +``` + + + + +**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production. + + ## Use cases The `eth_subscribe("syncing")` method is essential for applications that need to: diff --git a/reference/hyperliquid-info-aligned-quote-token-info.mdx b/reference/hyperliquid-info-aligned-quote-token-info.mdx index f015ef05..116ba8b1 100644 --- a/reference/hyperliquid-info-aligned-quote-token-info.mdx +++ b/reference/hyperliquid-info-aligned-quote-token-info.mdx @@ -4,13 +4,13 @@ openapi: /openapi/hyperliquid_node_api/hypercore_info/info_aligned_quote_token_i description: "The info endpoint with type: \"alignedQuoteTokenInfo\" retrieves supply, rate, and pending payment information for an aligned quote token." --- - -This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. - + +**Removed by Hyperliquid (~June 2026).** The Hyperliquid API no longer recognizes the `alignedQuoteTokenInfo` request type — requests fail to deserialize — and the method has been dropped from the official SDKs. There is no direct replacement. For the aligned quote asset mechanism, see [Aligned quote assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/aligned-quote-assets) in the Hyperliquid docs; for spot token metadata, see [tokenDetails](/reference/hyperliquid-info-token-details). This page is kept for reference. + -The `info` endpoint with `type: "alignedQuoteTokenInfo"` retrieves supply, rate, and pending payment information for an aligned quote token. Aligned quote tokens are HIP-1 spot tokens that deployers have registered as collateral for HIP-3 perpetual DEXes through the CoreWriter contract on HyperEVM. +The `info` endpoint with `type: "alignedQuoteTokenInfo"` returned supply, rate, and pending payment information for an aligned quote token. Aligned quote tokens are HIP-1 spot tokens that deployers had registered as collateral for HIP-3 perpetual DEXes through the CoreWriter contract on HyperEVM. -Returns `null` if the token has not been registered as an aligned quote asset. +It returned `null` if the token had not been registered as an aligned quote asset. diff --git a/reference/hyperliquid-info-batch-clearinghouse-states.mdx b/reference/hyperliquid-info-batch-clearinghouse-states.mdx index fab2ad42..4e1c34c8 100644 --- a/reference/hyperliquid-info-batch-clearinghouse-states.mdx +++ b/reference/hyperliquid-info-batch-clearinghouse-states.mdx @@ -4,11 +4,11 @@ openapi: /openapi/hyperliquid_node_api/hypercore_info/info_batch_clearinghouse_s description: "The info endpoint with type: \"batchClearinghouseStates\" retrieves perpetuals account summaries for multiple users in one call. On Hyperliquid info." --- - -You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet. See [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. - + +**Not available.** This batch method is not served by the public Hyperliquid API — requests return `null` for every address — and it is not available through Chainstack. To fetch perpetuals account state for multiple users, call [clearinghouseState](/reference/hyperliquid-info-clearinghousestate) once per address. Some third-party providers offer their own batch aggregators built on per-user calls. This page is kept for reference. + -The `info` endpoint with `type: "batchClearinghouseStates"` retrieves perpetuals account summaries for multiple users in one call. Use this to efficiently fetch positions, margin usage, and account values across many addresses. +The `info` endpoint with `type: "batchClearinghouseStates"` was intended to retrieve perpetuals account summaries for multiple users in one call — positions, margin usage, and account values across many addresses. diff --git a/reference/hyperliquid-info-perp-dex-limits.mdx b/reference/hyperliquid-info-perp-dex-limits.mdx index 2f503bf4..13af1b39 100644 --- a/reference/hyperliquid-info-perp-dex-limits.mdx +++ b/reference/hyperliquid-info-perp-dex-limits.mdx @@ -8,7 +8,7 @@ description: "Reference for the perpDexLimits JSON-RPC method on the Hyperliquid This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. -The `info` endpoint with `type: "perpDexLimits"` retrieves the configuration limits for perpetual DEXes on Hyperliquid, including maximum number of assets and other deployment constraints. +The `info` endpoint with `type: "perpDexLimits"` retrieves the market limits for a builder-deployed perpetual DEX on Hyperliquid — the total open interest cap, the per-perpetual open interest size cap, the maximum transfer notional, and the per-asset open interest caps. @@ -25,30 +25,75 @@ You can sign up with your GitHub, X, Google, or Microsoft account. ### Request body * `type` (string, required) — The request type. Must be `"perpDexLimits"`. +* `dex` (string, required) — The name of the builder-deployed perp DEX, for example `"xyz"`. The empty string is not allowed. Use [perpDexs](/reference/hyperliquid-info-perpdexs) to list deployed perp DEX names. ## Response -The response contains the perp DEX deployment limits and configuration constraints. +Returns a perp DEX limits object, or `null` if the DEX has no configured limits. + +* `totalOiCap` (string) — Total open interest cap across the DEX. +* `oiSzCapPerPerp` (string) — Open interest size cap per perpetual. +* `maxTransferNtl` (string) — Maximum transfer notional amount. +* `coinToOiCap` (array) — Array of `[coin, oiCap]` tuples giving the open interest cap per asset. ## Example request + + ```shell Shell curl -X POST \ -H "Content-Type: application/json" \ - -d '{"type": "perpDexLimits"}' \ + -d '{"type": "perpDexLimits", "dex": "xyz"}' \ https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info ``` +```python Python (hyperliquid-python-sdk) +from hyperliquid.info import Info + +# skip_ws=True avoids opening a WebSocket connection for this REST call +info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True) + +# The SDK has no dedicated perpDexLimits helper, so post the request directly. +perp_dex_limits = info.post("/info", {"type": "perpDexLimits", "dex": "xyz"}) +print(perp_dex_limits) +``` + +```typescript TypeScript (@nktkas/hyperliquid) +import { HttpTransport, InfoClient } from "@nktkas/hyperliquid"; + +// apiUrl points the transport at a custom server (your Chainstack endpoint) +const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" }); +const info = new InfoClient({ transport }); + +const perpDexLimits = await info.perpDexLimits({ dex: "xyz" }); +console.log(perpDexLimits); +``` + + + + +**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production. + + ## Example response ```json -null +{ + "totalOiCap": "7000000000.0", + "oiSzCapPerPerp": "20000000000.0", + "maxTransferNtl": "3000000000.0", + "coinToOiCap": [ + ["xyz:AAPL", "100000000.0"], + ["xyz:ALUMINIUM", "25000000.0"], + ["xyz:AMD", "100000000.0"] + ] +} ``` ## Use case The `info` endpoint with `type: "perpDexLimits"` is useful for: -* Checking deployment constraints before deploying a new perp DEX -* Understanding the maximum number of assets allowed per DEX -* Building deployment tools that validate against current limits +* Checking the open interest caps of a builder-deployed perp DEX before opening positions +* Monitoring per-asset open interest caps on a perp DEX +* Building risk and deployment tools that validate against current market limits From 1a6ab284a995764993858b696dfb1cc0918b09ef Mon Sep 17 00:00:00 2001 From: Ake <10195782+akegaviar@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:21:06 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(hyperliquid):=20address=20CodeRabbit?= =?UTF-8?q?=20=E2=80=94=20enforce=20dex=20minLength,=20coinToOiCap=20tuple?= =?UTF-8?q?=20shape,=20mark=20removed=20methods=20deprecated=20in=20specs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../hypercore_info/info_aligned_quote_token_info.json | 1 + .../hypercore_info/info_batch_clearinghouse_states.json | 1 + .../hypercore_info/info_perp_dex_limits.json | 3 +++ 3 files changed, 5 insertions(+) diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_aligned_quote_token_info.json b/openapi/hyperliquid_node_api/hypercore_info/info_aligned_quote_token_info.json index 2b08280b..ad347474 100644 --- a/openapi/hyperliquid_node_api/hypercore_info/info_aligned_quote_token_info.json +++ b/openapi/hyperliquid_node_api/hypercore_info/info_aligned_quote_token_info.json @@ -18,6 +18,7 @@ ], "summary": "info (alignedQuoteTokenInfo)", "operationId": "infoAlignedQuoteTokenInfo", + "deprecated": true, "requestBody": { "required": true, "content": { diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_batch_clearinghouse_states.json b/openapi/hyperliquid_node_api/hypercore_info/info_batch_clearinghouse_states.json index b18f6b20..3b358bc9 100644 --- a/openapi/hyperliquid_node_api/hypercore_info/info_batch_clearinghouse_states.json +++ b/openapi/hyperliquid_node_api/hypercore_info/info_batch_clearinghouse_states.json @@ -18,6 +18,7 @@ ], "summary": "info (batchClearinghouseStates)", "operationId": "infoBatchClearinghouseStates", + "deprecated": true, "requestBody": { "required": true, "content": { diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json b/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json index 383b3a8a..ff53b459 100644 --- a/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json +++ b/openapi/hyperliquid_node_api/hypercore_info/info_perp_dex_limits.json @@ -35,6 +35,7 @@ }, "dex": { "type": "string", + "minLength": 1, "description": "Name of the builder-deployed perp DEX. The empty string is not allowed.", "default": "xyz" } @@ -73,6 +74,8 @@ "description": "Array of [coin, oiCap] tuples giving the open interest cap per asset.", "items": { "type": "array", + "minItems": 2, + "maxItems": 2, "items": { "type": "string" }