Node + Data
Trader-first Hyperliquid data from an owned node and orderbook stack.
Omni operates the node, orderbook, stream, and derived-data path used to expose public trader positions, margin state, liquidation levels, L4 depth, and wallet investigation workflows.
At a glance
- Delivery
- Dedicated or shared Customers can use a dedicated node setup or lower-cost shared fanout with an explicit latency tradeoff.
- Trader state
- Positions + margin Public profiles and global views expose live positions, leverage, funding, fills, and activity.
- Market depth
- L4 + identity Order-level depth and per-fill maker/taker identity support liquidity and wallet investigation.
Why It Matters
What traders and researchers should take away
- Liquidation levels are more useful when they are tied to live public position and margin state.
- A trader profile should show current actions, positions, fills, funding, and leverage—not only historical PnL.
- Desks and builders need a clear choice between low-latency dedicated infrastructure and cheaper shared access.
How it works
What the product uses behind the scenes
- The consensus node and orderbook services feed stream processing and derived analytics rather than reselling a generic RPC response.
- Customer REST requests use https://api-data.omniterminal.app. Health, stream health, the topic catalog, and WebSocket documentation are public; use a server-side x-api-key provisioned for the data service for positions and bounded clearinghouse snapshots. On the auth-enabled service, explicitly scoped keys must include hl_data:read; another product key is not interchangeable.
- Typed WebSocket routes cover trades, BBO, L2/L4 books, candles, positions, fills, TWAP, liquidations, and node sync. The raw node proxy remains an administrative surface rather than a normal customer route.
- ClickHouse, Kafka, and stream consumers support historical and live views while keeping private infrastructure details out of public docs.
Notes
Things to know
- Shared fanout can have higher latency than a dedicated customer deployment.
- Liquidation levels and margin stress are analytical views of available state, not guarantees of forced execution.
- Public docs never expose credential values, private host inventory, or private customer data. Customer keys belong only in the x-api-key header and must not appear in URLs or browser bundles.
Trader and market data products
One source path supports both terminal features and external data access.
- All-user positions, margin use, liquidation levels, and funding state.
- L4 order-level depth, fill identity, wallet clusters, and trader profiles.
- REST, websocket, and fanout contracts for customer applications and research.
Dedicated setup versus shared fanout
The delivery model makes the latency and cost tradeoff explicit.
- Dedicated customer node and data services for the lowest controlled latency.
- Shared fanout and APIs for lower setup cost and simpler integration.
- Public-safe documentation and observable contracts for verification.
Live streams and historical context
Stable data contracts connect low-latency market state to the history needed for analysis.
- WebSocket streams deliver orderbook, trade, funding, position, and liquidation updates.
- REST snapshots provide bounded recovery and historical context for terminal and customer workflows.
- Canonical symbols and per-dex identity keep instruments consistent across live and stored data.
Production customer API quickstart
Start with public discovery, then add a scoped server-side key for bounded trader-state reads.
- Check GET /api/v1/health, GET /api/v2/health/streams, and GET /api/v1/ws/topics on api-data.omniterminal.app without a key.
- Positions accept coin or dex:coin symbols, not terminal display IDs; default limit is 1,000 and the handler clamps it to 1–20,000. The returned count is not total population or full history.
- Send x-api-key with hl_data:read on GET /api/v2/positions/current, GET /api/v2/positions/recent, and POST /api/v2/clearinghouse/batch; keep batch user lists within the advertised service limit. Older absent-metadata keys retain compatibility, but newly provisioned keys should use an explicit scope.
- Use /api/v1/ws/topics as the machine-readable stream catalog and /docs/ws for current subscribe payloads. Prefer typed streams; do not request an admin key for the raw /ws/v2/node proxy.
- A missing key returns 401; an invalid key, an explicitly restricted scope or malformed scope metadata returns 403. Treat 429 as a backoff signal and 503 as a temporary authentication or upstream-service failure, not a reason to broaden permissions.
References
Implementation references
Customer Node/Data API quickstart
omni-terminal/docs/HL_DATA_API_QUICKSTART.mdDocuments exact position queries, nullable fields, bounded main-dex batches, failure formats and freshness limits.
Node authority
omni-terminal/docs/LLM_NODE_AUTHORITY.mdDocuments why Omni operates its own Hyperliquid node and the public-safe authority boundary.
Terminal and API architecture
omni-terminal/docs/ARCHITECTURE_TERMINAL_API.mdDocuments the node-to-API-to-terminal contract and public route model.
Websocket streams
omni-terminal/docs/WS_STREAMS.mdDocuments live stream surfaces used by price, L4, positions, liquidations, and news.
Live Node/Data WebSocket reference
https://api-data.omniterminal.app/docs/wsPublishes the production stream routes and current subscribe payloads.