Reference

How it works. From feed to gap.

Materral reads public market data, normalizes it, evaluates every route at your size, and tracks the gaps over time. The same cost code runs everywhere, so numbers cannot drift between views.

Data flow#

exchange WebSockets ─┐
HyperCore WS + REST ─┼─► live state ─► evaluate every route at size ─► rank ─► gap tracker ─► terminal
EVM JSON-RPC pools  ─┘

By default the browser connects to the feeds itself. Each route is checked in both directions and evaluated at your size. A stale or blocked route stays visible but is excluded from ranking.

Live feeds per venue#

• HyperCore l2Book snapshots arrived about every 5.3 s (p50, measured); bbo updates every 130–290 ms. Depth comes from l2Book; bbo flags top-of-book drift since the last depth snapshot.
• Ethereum pools are polled every 6 s; Arbitrum and Base pools every 3 s.
• Hyperliquid REST calls stay inside a budget of 900 of the 1,200 weight per minute per IP.

Staleness limits#

Maximum quote age before a route is excluded from ranking:

Feed health#

• A feed is degraded after 10 s of silence and down after 30 s.
• When HyperCore disconnects, its books are deleted, never served as current. While its WebSocket is down, REST snapshots are taken inside the rate budget.
• Reconnects use exponential backoff with jitter.

How gaps are found#

On every recompute the tracker looks at each live route's gross spread.

• A gap opens when gross reaches 2 bps on fresh quotes.
• It is New for its first 60 s, then Open.
• It closes when gross falls under 0.5 bps, when a quote goes stale, or when the route can no longer be priced.
• Closed gaps are kept for 15 minutes.

Each gap records the observation that first crossed the threshold (legs, prices, source timestamps and pricing method) and a gross/net series for its chart.

How pools are quoted#

A pool's spot price says little about what a large swap would get. Materral quotes the swap itself.

• Every 15 s, each pool's initialized ticks around the price are read (about 240 per HyperEVM pool).
• Quotes run the Uniswap v3 swap loop across those ticks, crossing ticks and updating liquidity as the pool does. The math is ported from Uniswap v3 TickMath, SqrtPriceMath and SwapMath, in integer arithmetic with the same rounding.
• Rounding goes against you: amounts received round down, amounts paid round up.
• Size beyond the loaded range is reported as unpriced, never extrapolated. The tick map is flagged once it is more than 60 s old.
• The fee is read from the pool's fee(), the fee the next swap pays.

One Multicall3 read#

The public HyperEVM RPC ignores block tags: an eth_call always serves the latest state. So anything that must agree, pool state together with its ticks, is read inside a single Multicall3 call, which returns one consistent view.

Verified against the chain#

The verify-pool-quotes script runs each pool's real swap() through eth_call with a code override: the swap callback reverts with the amounts, so nothing is deployed or sent. On 2026-11-03, all 24 cases matched Materral's quote to the wei: both HyperEVM pools, buy and sell, 1 to 10,000 WHYPE, up to 92 ticks crossed.

pnpm verify:pools

materral docs. Read-only, no keys, no real orders. Not investment advice.