Omni Terminal

Terminal & API Architecture

A split API and stream chain designed for browser UX and external clients.

Omni Terminal uses a split API: browser-facing terminal routes without API keys and separate public API routes for external clients. That model sits on a stream chain that runs from Omni-operated node/orderbook infrastructure into data-api Kafka and ClickHouse derivations, then into terminal websocket and page routes.

At a glance

API split
/terminal + /api/v1 Browser-facing terminal routes and external keyed routes live on the same backend with different access and rate-limit models.
Stream chain
Node -> data-api -> terminal Hyperliquid market data flows through node/orderbook websocket contracts, data-api Kafka topics, and browser terminal routes.
Browser model
Relative paths The frontend is designed to use browser-safe relative terminal routes behind the proxy.

Why It Matters

What traders and researchers should take away

  • The architecture explains why Omni can serve both browser UX and external API consumers cleanly.
  • It clarifies which routes are intended for the terminal and which are intended for keyed public clients.
  • It provides a clear explanation of how the stack is assembled rather than hand-wavy marketing.

How it works

What the product uses behind the scenes

  • Omni architecture docs describe the terminal/public route split and rate-limiting model.
  • WS stream docs describe how live views rely on websocket-first updates.
  • AI notes and sibling data-api docs describe the topic and payload contract across the stream chain.

Notes

Things to know

  • The terminal does not connect directly to the node/orderbook docker stack.
  • Topic names and payload contracts are treated as interfaces and should not be changed casually.
  • Public-facing docs should explain the architecture without disclosing private deployment inventory.

What Omni does here

The split API is a core design choice rather than an implementation accident.

  • Uses /terminal/* for browser-facing terminal routes with IP-based rate limiting.
  • Uses /api/v1/* for external keyed API access with tiered limits.
  • Keeps frontend browser calls relative so the reverse proxy and app routes stay aligned.

How data reaches the terminal

Hyperliquid market data follows an explicit chain into the browser-facing terminal.

  • node-orderbook-docker provides upstream orderbook and market stream inputs.
  • hyperliquid-data-api publishes and reshapes fills, orderbook, BBO, L4, liquidation, and position deltas via Kafka and ClickHouse-backed derivations.
  • omni-terminal consumes those contracts and serves browser-facing websocket and page routes without making the browser talk directly to the node stack.

Terminal routes versus public API routes

The split keeps app UX and external client access from sharing one generic surface.

  • /terminal/* routes are for the browser terminal and use the app proxy and IP-oriented protection.
  • /api/v1/* routes are for external clients and use API-key tiers.
  • The public docs keep app-heavy/private routes out of search while documenting the canonical product and guide URLs.

References

Implementation references

  • Terminal vs Public API

    omni-terminal/docs/ARCHITECTURE_TERMINAL_API.md

    Primary documentation for the route split, access model, and browser-relative path strategy.

  • WebSocket streams

    omni-terminal/docs/WS_STREAMS.md

    Documents how the browser-facing terminal relies on websocket-first data delivery.

  • Omni AI notes

    omni-terminal/docs/ai-notes.md

    Documents the node-orderbook-docker -> data-api -> terminal chain and downstream stream conventions.

  • Data-api Kafka and ClickHouse streams

    hyperliquid-data-api/docs/KAFKA_AND_CH_STREAMS.md

    Documents live topic contracts for positions, liquidation stats, fills, orderbook, BBO, and L4 consumers.

Next