- The Hyperliquid Info API, a
POST /uni/v1/hyperliquid/infodispatch endpoint where the body’stypefield selects the operation. - The GoldRush WebSocket at
wss://websocket.uniblock.dev/goldrush, for order books and live fill streams.
Create your project and grab your API key from the
Uniblock dashboard. New to Hyperliquid’s
architecture? Read HyperCore vs. HyperEVM
first. This series is entirely HyperCore (the native order book), not the EVM side.
What you’ll build
Architecture: put a proxy in front
Your API key must never reach the browser. For the REST side that’s a familiar rule. For the WebSocket side it’s a hard constraint: browsers cannot set headers on a WebSocket handshake, so browser code physically cannot authenticate towss://websocket.uniblock.dev/goldrush with an X-API-KEY header. A small server-side
bridge isn’t a stylistic preference here; it’s the only way to open the stream from a
web app at all.
The whole server is about forty lines: forward Info request bodies verbatim, and pipe
WebSocket frames in both directions.
POST /api/info against that proxy. To keep the
snippets readable, they all assume this helper:
Two conventions that apply everywhere
Numbers arrive as decimal strings
Hyperliquid returns almost every number as a string:"1234.5", not 1234.5. This is
deliberate: it preserves exact decimal precision that IEEE-754 floats would lose. Keep
values as strings while you carry them around, and convert only at the point you do
display math:
chainId selects the network
999 is Hyperliquid mainnet (the default), 998 is testnet. Every example here uses
mainnet.
Which provider serves what
Uniblock routes each Info request through a provider waterfall: Alchemy, Dwellir, Chainstack, GoldRush, in that priority order. Different providers serve different Info types, and that has a practical consequence: the historical and market-data types this series leans on are served by GoldRush alone.
You don’t normally need to act on this, because the waterfall automatically picks a
provider that serves your
type. It matters in two situations:
- Debugging. If a response looks wrong, pinning
?provider=lets you compare providers directly and find out whether you’re looking at a routing artifact or real data. - Consistency. If you want two related reads to come from the same source, pin both.
openOrders is the one asymmetry worth remembering: GoldRush serves
frontendOpenOrders but not openOrders. If you want your open-orders read to
survive a failover to GoldRush, use frontendOpenOrders. It returns the same orders
with extra frontend metadata.Cost model
Two meters run, and they behave differently. REST is billed per request. A batch type multiplies:batchPortfolioStates over 50
addresses is billed as 50 lookups, not one. That’s still far cheaper than 50 separate
requests, but it isn’t free.
WebSocket is billed per subscription-minute, and the rate depends on the channel:
The shape of that table is the whole argument for scoping your subscriptions:
subscribing to
l2Book for three coins costs 1.5/min; omitting coin to get all of them
costs 50/min, over thirty times more for data you’ll mostly discard.
The general rule that follows: prefer one WebSocket subscription over a polling loop.
A stream you hold open for an hour costs 60 units; polling the same data every two
seconds costs 1,800 requests. Where you must poll, poll slowly and back off on 429.
Routing through Uniblock removes Hyperliquid’s per-IP request-weight cap, but your
plan’s rate limits still apply, and bursts return
429. See
Rate limits, caching & polling.