Skip to content
New guideAgent Cookbook 12 copy-ready prompts for AI coding agents.See recipes
All blog posts
Hyperliquid Infrastructure Stack for Developers 2026: Info API, WebSocket, gRPC, Order Book and HyperEVM RPC

Hyperliquid Infrastructure Stack for Developers 2026: Info API, WebSocket, gRPC, Order Book and HyperEVM RPC

By Elias FaltinUpdated 14 min read

A Hyperliquid trading bot that polls the REST API every second misses fills between polls. A market maker reading the public WebSocket loses state when the server drops the connection without warning. An indexer that sends eth_call to read an order book gets nothing, because order books live on HyperCore, not HyperEVM. Each of these is the same mistake: the wrong Hyperliquid API for the job.

This guide maps each Hyperliquid API surface to the work it does, shows the request shapes, and gives a stack per application type. For how Hyperliquid itself works, including HyperBFT consensus, API servers and nodes, read how Hyperliquid's infrastructure works. To compare providers on price, archive and HyperCore coverage, read the best Hyperliquid RPC providers ranked.

HyperCore and HyperEVM in one paragraph

Hyperliquid is one chain with one state, split into two execution environments under HyperBFT consensus. HyperCore is the native trading engine: perpetual and spot order books, the clearinghouse, funding and liquidations, all on-chain, with gas-free trading. HyperEVM is a general-purpose EVM at chain ID 999 that runs Solidity contracts and can read HyperCore state through precompiles. EVM tooling works on HyperEVM. HyperCore data needs Hyperliquid's own APIs. Most production applications need both. The architecture page has the details.

HyperCore

The trading layer

Fully on-chain order books and matching for perpetuals and spot markets. Every order, cancel, and fill is recorded in a block.

Consensus
HyperBFT
Orders per second
200k
Order books
On-chain
  • Perps up to 40x on BTC
  • HIP-3 perp DEXs
  • HIP-4 outcome markets
HyperEVM

The smart contract layer

An Ethereum-compatible environment for standard Solidity contracts, wallets, and tooling.

Chain ID
999
Block time
< 1s
Gas token
HYPE
  • ethers.js
  • viem
  • Hardhat
  • Foundry
HyperBFT consensusOne state: both layers land in the same blocks, final in under a second. How it works
Dwellir nodesRead every block and write the seven HyperCore record types listed next.

The Hyperliquid API surfaces

SurfaceProtocolServed byUse it for
Info endpointREST, POST /infoHyperliquid API servers; providers proxy parts of itAccount state, metadata, snapshots, history
Exchange endpointREST, POST /exchangeHyperliquid API servers onlySigned orders, cancels, transfers
WebSocketWSSHyperliquid API servers (wss://api.hyperliquid.xyz/ws)Live trades, books and user events within public limits
gRPC streamsgRPC over TLSProviders such as Dwellir and QuickNodeRaw node feeds and typed market streams
Order book feedsWSSProviders such as Dwellir and HydromancerL2 depth beyond 20 levels, L4 individual orders
HyperEVM RPCJSON-RPC over HTTPS and WSSrpc.hyperliquid.xyz/evm and providersSmart contracts, tokens, EVM logs and traces

The public surfaces have per-IP limits: 1,200 weight per minute on REST, 10 WebSocket connections and 1,000 subscriptions per IP, and 100 requests per minute on HyperEVM JSON-RPC. The public rate limits table lists the weights per request type. Those limits, more than features, are why production systems add a provider.

Info endpoint: account state and reference data

The Info endpoint is Hyperliquid's read API. Every request is a POST to /info with a JSON body whose type field picks the query. It is read-only, even though it uses POST.

What the Info endpoint returns

  • Account state: positions, margin and balances (clearinghouseState, spotClearinghouseState), open orders (openOrders, frontendOpenOrders)
  • Reference data: perpetual and spot metadata (meta, spotMeta), metadata with live mark prices and funding (metaAndAssetCtxs)
  • Market snapshots: mid prices (allMids), an L2 book snapshot (l2Book), candles (candleSnapshot)
  • History: a user's fills (userFills), funding history (fundingHistory)

Providers proxy different subsets. Dwellir's Info endpoint at https://api-hyperliquid-mainnet-info.n.dwellir.com/info serves account and state queries, including clearinghouseState, openOrders, meta and metaAndAssetCtxs, plus Dwellir-only batch methods such as batchClearinghouseStates that return many wallets in one request. Market snapshots and history (l2Book, allMids, candleSnapshot, userFills, fundingHistory) are not proxied. Read them from the public https://api.hyperliquid.xyz/info, from a stream, or from the historical data archive.

Request structure

JavaScript:

JavaScript
const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info';
const API_KEY = 'your-api-key-here';

async function getClearinghouseState(userAddress) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY
    },
    body: JSON.stringify({
      type: 'clearinghouseState',
      user: userAddress
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

Python:

Python
import requests

ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info'
API_KEY = 'your-api-key-here'

def get_clearinghouse_state(user_address: str) -> dict:
    """Get a user's perpetual account state"""
    response = requests.post(
        ENDPOINT,
        json={
            'type': 'clearinghouseState',
            'user': user_address
        },
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': API_KEY
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

You can also put the key in the path: https://api-hyperliquid-mainnet-info.n.dwellir.com/<your-api-key>/info. Cache meta for up to an hour and poll account state every 5-10 seconds unless your strategy needs faster updates. For faster updates, stream them instead.

When to use the Info endpoint

  • Startup state: positions, balances and open orders, so the bot does not duplicate orders
  • Reference data: asset specifications, size decimals, funding settings
  • Reconciliation: periodic balance and position checks against your own state
  • One-off queries: investigating a specific order or account

Don't use it for live order book tracking or fill monitoring. Polling adds a round trip to every update and still misses events between polls.

Exchange endpoint: placing and cancelling orders

Every write goes through POST /exchange on Hyperliquid's API servers: orders, cancels, modifies, transfers and scheduleCancel, the dead man's switch that cancels all orders at a set time. Actions are signed with your wallet or an approved agent wallet. The response is the committed execution result, not an acknowledgement.

No managed provider proxies /exchange, Dwellir included. A paid RPC plan does not make orders land faster. The write path depends on where your bot runs (Tokyo is closest to the validators), on Hyperliquid's priority fees, and on each address's request budget, which starts at 10,000 actions and grows by one per 1 USDC traded. The Hyperliquid Python SDK handles signing.

WebSocket: live data within public limits

Hyperliquid's public WebSocket at wss://api.hyperliquid.xyz/ws streams trades, l2Book (20 levels), bbo, candles, and user channels such as userFills and orderUpdates. It is free and good enough for many bots. Its limits are 10 connections, 1,000 subscriptions and 10 unique users across user-specific subscriptions per IP. The server may also drop connections without warning, so clients must reconnect and rebuild state from the snapshot sent on reconnect.

When those limits bind, or when you need depth beyond 20 levels or individual orders, move to a provider's order book feed or gRPC.

Order book feeds: L2 depth and L4 orders

Provider order book feeds use the same subscription shape as the public WebSocket and add depth. Dwellir's Order Book WebSocket runs from Singapore and Tokyo at wss://api-hyperliquid-mainnet-orderbook.n.dwellir.com/<your-api-key>/ws.

L2 book, aggregated price levels, 1 to 100 levels per side:

JSON
{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC",
    "nLevels": 50
  }
}

L4 book, every individual order with its user address and order ID:

JSON
{
  "method": "subscribe",
  "subscription": {
    "type": "l4Book",
    "coin": "BTC"
  }
}

L4 opens with a full snapshot and then sends diffs. Snapshots are several megabytes, so raise your WebSocket client's maximum message size. Fill details such as execution price and counterparty come on the trades stream, not on the L4 channel. The L4 book reference explains the order data flow.

In a Tokyo benchmark on 28 October 2026, Dwellir's Order Book WebSocket delivered the L2 book with a median of 177 ms against 282 ms on the public API, over 30% lower, measured on a dedicated node. Shared endpoints were within 15 ms at the median. The add-on costs $199 a month plus one API credit per message.

Use it for quoting, slippage estimates, spread monitoring, queue position and large-order tracking. Don't use it for historical order book reconstruction. Use the historical data archive for that.

gRPC: raw node feeds and typed market streams

gRPC is where you get the data a Hyperliquid node writes: every block, every fill, every order status change and every book diff, as Protocol Buffers over one long-lived connection. Hyperliquid itself does not run a public gRPC endpoint. Providers run nodes and serve the feeds.

Dwellir's gRPC API has two V3 services:

ServiceWhat it servesReplay
HyperliquidL1GatewayRaw feeds: blocks, fills, raw book diffs, order statuses, TWAP statuses, misc events and pre-consensus mempool transactions, each as a stream and a unary lookup, plus generated order book snapshotsResume from a block number or timestamp within the retained window (mempool by timestamp only)
MarketStreaming14 typed streams: L2 book, L2 diffs, L4 book, L4 order updates, BBO, trades, all fills, user fills, builder fills, liquidation fills, TP/SL updates, candles, mids, asset contextLive only

The fills, raw book diffs, order statuses and TWAP statuses streams take users and coins filters, so a copy-trading bot can stream fills for ten wallets without parsing every fill on the chain. Retained replay history is short and varies by feed and endpoint. If a cursor is older than that (the server returns NOT_FOUND), backfill from the historical data archive and switch to the live stream. Authentication is the x-api-key metadata header over TLS. The add-on costs $299 a month plus one API credit per streamed message.

Bash
curl -fsSLo v3.proto https://www.dwellir.com/docs/hyperliquid/grpc/v3.proto

grpcurl -proto v3.proto \
  -H "x-api-key: ${DWELLIR_API_KEY}" \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/ListFeeds

Use gRPC for fill and liquidation monitoring, copy trading, order status tracking, state reconstruction and any feed you want to filter server-side. Don't use it for startup state (use the Info endpoint) or history older than the replay window (use the archive). For a first stream, start with StreamBlocks and the streaming troubleshooting guide.

HyperEVM RPC: contracts, tokens and traces

HyperEVM RPC is standard Ethereum JSON-RPC. Ethers.js, viem, Web3.py, Hardhat and Foundry work without changes.

PropertyValue
Mainnet chain ID999 (testnet 998)
Gas tokenHYPE, 18 decimals
BlocksSmall blocks every second (3M gas), big blocks every minute (30M gas)
Official RPChttps://rpc.hyperliquid.xyz/evm, 100 requests per minute, no WebSocket
Dwellir RPChttps://api-hyperliquid-mainnet-evm.n.dwellir.com/<your-api-key>, WSS on the same host, full archive, debug_* and trace_* on every plan

JavaScript (Ethers.js):

JavaScript
const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider(
  'https://api-hyperliquid-mainnet-evm.n.dwellir.com/YOUR_API_KEY'
);

const balance = await provider.getBalance('0x...');
console.log(`Balance: ${ethers.formatEther(balance)} HYPE`);

const contract = new ethers.Contract(contractAddress, abi, provider);
const result = await contract.someReadMethod();

Python (Web3.py):

Python
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    'https://api-hyperliquid-mainnet-evm.n.dwellir.com/YOUR_API_KEY'
))

print(f"Chain ID: {w3.eth.chain_id}")  # 999
print(f"Latest block: {w3.eth.block_number}")

balance = w3.eth.get_balance('0x...')
print(f"Balance: {w3.from_wei(balance, 'ether')} HYPE")

Contracts on HyperEVM read HyperCore state through read precompiles and send HyperCore actions through the CoreWriter contract at 0x3333333333333333333333333333333333333333. The architecture page covers both.

Use HyperEVM RPC for contract deployment, ERC-20 and DeFi interactions, eth_getLogs indexing and transaction tracing. Don't use it for order books, fills or positions. Those are HyperCore data.

Which stack for which application

ApplicationInfo endpointExchangeWebSocket or order book feedgRPCHyperEVM RPC
Trading botStartup state, reconciliationYesLive book and tradesOptional, for fillsNo
Market makerPositionsYesL2 or L4 book, primaryOptionalOptional, for hedging
Copy tradingLeader positions on startupYesOptionalFiltered fills, primaryNo
Liquidation botAccount stateYesOptionalLiquidation fills, primaryNo
Analytics dashboardReference dataNoOptionalRaw feeds, primaryOptional
Portfolio trackerBatch account stateNoOptionalNoToken balances
DeFi applicationMarket contextNoOptionalNoPrimary
BacktestingReference dataNoNoNoNo; use the historical archive

Trading bot

  1. Startup: Info endpoint for balances, positions and open orders.
  2. Live data: subscribe to the L2 book and trades for your markets over WebSocket.
  3. Orders: signed actions to /exchange, with scheduleCancel as a dead man's switch.
  4. Reconciliation: Info endpoint every few minutes to check that your state matches the chain.

Market maker

Text
+-------------------------------------------+
|           Quote placement logic           |
+-------------------------------------------+
         |                         |
         v                         v
+------------------+     +-------------------+
| Order book feed  |     |   Info endpoint   |
|   (L2 or L4)     |     |    (positions)    |
+------------------+     +-------------------+
         |                         |
         +------------+------------+
                      |
                      v
            +-------------------+
            |    Risk engine    |
            +-------------------+
                      |
                      v
            +-------------------+
            |  /exchange        |
            |  (signed orders)  |
            +-------------------+

The order book feed drives quotes, the Info endpoint keeps position and margin state honest, and the risk engine sits between them and /exchange. Add HyperEVM RPC only if you hedge or manage collateral on-chain.

Analytics platform

  1. Backfill from the historical data archive: fills, order statuses and book diffs by block.
  2. Live ingestion over gRPC raw feeds, resuming from the last stored block number after any outage.
  3. Reference data from the Info endpoint.
  4. Optional: HyperEVM eth_getLogs for protocol activity on the EVM side.

Copy trading

The Hyperliquid copy trading bot tutorial uses the Info endpoint to load the leader's positions on startup, a filtered gRPC fills stream to follow new trades, and the Info endpoint again every few minutes to reconcile.

When to add a provider, and which one

Start on the public endpoints. Add a provider when one of these happens:

  • HyperEVM calls exceed 100 per minute, or you need WebSocket, archive or trace on HyperEVM.
  • REST weight runs out: 1,200 per minute per IP is about 60 metaAndAssetCtxs calls or 600 clearinghouseState calls.
  • You need raw node data: every fill, order status or book diff. Only a node or a provider's gRPC feed has it.
  • You need depth beyond 20 levels or individual orders (L4).

Providers differ most on HyperCore coverage, not on HyperEVM. The Hyperliquid RPC providers ranking compares Info coverage, gRPC, order book depth and price per call across five providers. If you need full control, run your own non-validating node in Tokyo and peer it with Dwellir. If you need it run for you with no metering, a Dedicated Node Cluster is the next step.

Dwellir's Hyperliquid stack

ServiceWhat you getPrice
HyperEVM RPCHTTPS and WSS, full archive, debug and trace, one credit per responseFree tier, then from $49 a month
Info endpointAccount and state queries, batch methodsOne API credit per response on any API plan
gRPC APIRaw node feeds with replay, 14 typed market streams$299 a month plus usage
Order Book WebSocketL2 up to 100 levels, L4, trades, BBO, from Singapore and Tokyo$199 a month plus usage
Historical dataFills, order statuses, book diffs, replica_cmds and more on S3Per dataset
PeeringReserved gossip peer slots for your own node$500 a month per slot
Dedicated Node ClusterTwo or more dedicated backend nodes with HyperEVM, Info, gRPC and Order Book included, unmeteredFrom $4,000 a month

Full pricing is on the Hyperliquid pricing page.

Getting started

  1. Create a free Dwellir account for HyperEVM RPC and the Info endpoint.
  2. Add the gRPC API or the Order Book WebSocket from the pricing page when you need streams.
  3. For unmetered production capacity, contact the Dwellir team about a Dedicated Node Cluster.

Code examples

Frequently asked questions

Which Hyperliquid API should a trading bot use?

Most trading bots use three surfaces: the Info endpoint for positions, balances and open orders on startup, a WebSocket or gRPC stream for live order book and fill data, and the Exchange endpoint at api.hyperliquid.xyz/exchange to place and cancel signed orders. HyperEVM JSON-RPC is only needed if the bot also uses smart contracts.

What is the difference between the Hyperliquid Info endpoint and the Exchange endpoint?

The Info endpoint (POST /info) is read-only and returns market data, metadata and account state. The Exchange endpoint (POST /exchange) accepts signed actions such as orders, cancels and transfers. Managed providers proxy parts of the Info endpoint; none proxy the Exchange endpoint, so orders always go to Hyperliquid's API servers or your own node.

How do I stream HyperCore data from Hyperliquid?

Use the public WebSocket at wss://api.hyperliquid.xyz/ws for trades, l2Book and user events within its limits of 10 connections and 1,000 subscriptions per IP. For raw node feeds such as every fill, order status or book diff, use a gRPC stream from a provider: Dwellir's gRPC API serves raw feeds with cursor replay and 14 typed market streams for $299 a month plus usage.

What is the HyperEVM chain ID?

HyperEVM mainnet is chain ID 999 and testnet is chain ID 998. The gas token is HYPE with 18 decimals, and the official RPC at rpc.hyperliquid.xyz/evm allows 100 requests per minute over HTTP with no WebSocket.

Start free.1 response = 1 credit.

100,000 responses a day at 20 per second, on 150+ networks. Upgrade when you need more.