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.
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
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

HyperCore data
Live
The Hyperliquid API surfaces
| Surface | Protocol | Served by | Use it for |
|---|---|---|---|
| Info endpoint | REST, POST /info | Hyperliquid API servers; providers proxy parts of it | Account state, metadata, snapshots, history |
| Exchange endpoint | REST, POST /exchange | Hyperliquid API servers only | Signed orders, cancels, transfers |
| WebSocket | WSS | Hyperliquid API servers (wss://api.hyperliquid.xyz/ws) | Live trades, books and user events within public limits |
| gRPC streams | gRPC over TLS | Providers such as Dwellir and QuickNode | Raw node feeds and typed market streams |
| Order book feeds | WSS | Providers such as Dwellir and Hydromancer | L2 depth beyond 20 levels, L4 individual orders |
| HyperEVM RPC | JSON-RPC over HTTPS and WSS | rpc.hyperliquid.xyz/evm and providers | Smart 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:
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:
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:
{
"method": "subscribe",
"subscription": {
"type": "l2Book",
"coin": "BTC",
"nLevels": 50
}
}L4 book, every individual order with its user address and order ID:
{
"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:
| Service | What it serves | Replay |
|---|---|---|
HyperliquidL1Gateway | Raw 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 snapshots | Resume from a block number or timestamp within the retained window (mempool by timestamp only) |
MarketStreaming | 14 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 context | Live 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.
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/ListFeedsUse 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.
| Property | Value |
|---|---|
| Mainnet chain ID | 999 (testnet 998) |
| Gas token | HYPE, 18 decimals |
| Blocks | Small blocks every second (3M gas), big blocks every minute (30M gas) |
| Official RPC | https://rpc.hyperliquid.xyz/evm, 100 requests per minute, no WebSocket |
| Dwellir RPC | https://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):
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):
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
| Application | Info endpoint | Exchange | WebSocket or order book feed | gRPC | HyperEVM RPC |
|---|---|---|---|---|---|
| Trading bot | Startup state, reconciliation | Yes | Live book and trades | Optional, for fills | No |
| Market maker | Positions | Yes | L2 or L4 book, primary | Optional | Optional, for hedging |
| Copy trading | Leader positions on startup | Yes | Optional | Filtered fills, primary | No |
| Liquidation bot | Account state | Yes | Optional | Liquidation fills, primary | No |
| Analytics dashboard | Reference data | No | Optional | Raw feeds, primary | Optional |
| Portfolio tracker | Batch account state | No | Optional | No | Token balances |
| DeFi application | Market context | No | Optional | No | Primary |
| Backtesting | Reference data | No | No | No | No; use the historical archive |
Trading bot
- Startup: Info endpoint for balances, positions and open orders.
- Live data: subscribe to the L2 book and trades for your markets over WebSocket.
- Orders: signed actions to
/exchange, withscheduleCancelas a dead man's switch. - Reconciliation: Info endpoint every few minutes to check that your state matches the chain.
Market maker
+-------------------------------------------+
| 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
- Backfill from the historical data archive: fills, order statuses and book diffs by block.
- Live ingestion over gRPC raw feeds, resuming from the last stored block number after any outage.
- Reference data from the Info endpoint.
- Optional: HyperEVM
eth_getLogsfor 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
metaAndAssetCtxscalls or 600clearinghouseStatecalls. - 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
| Service | What you get | Price |
|---|---|---|
| HyperEVM RPC | HTTPS and WSS, full archive, debug and trace, one credit per response | Free tier, then from $49 a month |
| Info endpoint | Account and state queries, batch methods | One API credit per response on any API plan |
| gRPC API | Raw node feeds with replay, 14 typed market streams | $299 a month plus usage |
| Order Book WebSocket | L2 up to 100 levels, L4, trades, BBO, from Singapore and Tokyo | $199 a month plus usage |
| Historical data | Fills, order statuses, book diffs, replica_cmds and more on S3 | Per dataset |
| Peering | Reserved gossip peer slots for your own node | $500 a month per slot |
| Dedicated Node Cluster | Two or more dedicated backend nodes with HyperEVM, Info, gRPC and Order Book included, unmetered | From $4,000 a month |
Full pricing is on the Hyperliquid pricing page.
Getting started
- Create a free Dwellir account for HyperEVM RPC and the Info endpoint.
- Add the gRPC API or the Order Book WebSocket from the pricing page when you need streams.
- For unmetered production capacity, contact the Dwellir team about a Dedicated Node Cluster.
Code examples
- Hyperliquid gRPC examples (Go, Python, Node.js)
- Order Book WebSocket examples
- Copy trading bot in Python
- Real-time liquidation tracker
Related reading
- How Hyperliquid's infrastructure works
- Best Hyperliquid RPC providers 2026, ranked
- How to get a Hyperliquid node
- Alternatives to the public Hyperliquid API
- Hyperliquid latency explained
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.




