Skip to main content
Subscribe with {"method":"subscribe","subscription":{"type":"allDexsClearinghouseState","builder":"0x..."}} (builder required: a 0x-prefixed builder address). One subscription covers every user with open positions or orders placed through that builder, across all dexes — no per-address subscriptions needed. Acknowledgement uses subscriptionResponse. The snapshot then arrives on the same socket as AllDexsClearinghouseStateSnapshot chunks (isSnapshot: true, part, final, userCount); live pushes follow as AllDexsClearinghouseStateUpdate, both in components/schemas of the same OpenAPI file. The first snapshot after a cold start can take up to ~2 minutes to be assembled (one state query per user per dex, served from our own nodes); the subscription stays warm afterwards.

​
Consistency contract

Snapshot and stream share the socket, so there is no separate REST call to race against. The remaining ordering cases are resolved by the version field:
  • v is strictly increasing per user. Upsert by user, and drop any frame whose v is lower than or equal to the one you already hold. An update may arrive while snapshot parts are still being delivered — the rule handles it.
  • states holds one entry per dex the user trades: "" is the core perp dex, other values are HIP-3 dex names (xyz, io, …). Each clearinghouseState has the HL shape for that dex and covers the user’s whole account, not only positions opened through the builder.
  • Updates are sent within ~1–3 s of any fill, order change, leverage change (updateLeverage) or isolated-margin change (updateIsolatedMargin), with bursts coalesced per user.

​
Periodic refresh (optional)

Add refreshSec to the subscription (e.g. {"type":"allDexsClearinghouseState","builder":"0x...","refreshSec":5}) and every user holding open positions is re-sent at that cadence (floor 5 s), so PnL and margin track the mark price between fills. Two kinds of frames then arrive, both following the same v rule:
  • source: "mark" — every refreshSec seconds, batched (users[], up to 50 per frame, see AllDexsClearinghouseStateMarkUpdate). The server fetches the current mark prices and revalues each user’s last node state locally: positionValue, unrealizedPnl, returnOnEquity, marginUsed, the margin summaries, crossMaintenanceMarginUsed and withdrawable follow the mark; liquidationPx is carried from the node state (adjusted for the account’s other cross positions); cumFunding, entryPx and leverage only change on node reads. Users whose numbers did not move are omitted.
  • source: "node" — one frame per user, read from the node: on every fill, order, leverage or isolated-margin change, and as a full re-read about every 35 s (longer on very large builders), which re-anchors the revaluation.
Measured against the node on the largest builder (4,100 position holders, October 2026): mark-to-market position values are within 0.01 % at the 90th percentile; the residual comes from mark-price timing between Hyperliquid’s public API and the node, and disappears at the next node read. Without refreshSec, you get event-driven updates only (plus a slow background sweep).

​
Membership

A user enters the tracked set on their first fill through the builder (the set is seeded from the last 30 days of fills; a user who only placed an order but never filled appears at their first fill). When a user goes flat with no open orders, after a grace period you receive {"user", "v", "removed": true, "states": []}. Usage is billed as standard WebSocket events against your plan’s credits.

Account-state update for one user of the subscribed builder, sent within ~1-3 s of any fill, order change, leverage change (updateLeverage) or isolated-margin change (updateIsolatedMargin) (bursts are coalesced per user); these frames carry source: "node" (state read from the node). When a user leaves the set (flat and no open orders, after a grace period), the frame carries removed: true and empty states. With refreshSec set on the subscription, position holders are also re-sent periodically: see AllDexsClearinghouseStateMarkUpdate for the batched mark-to-market frames.

​
channel
enum<string>
required
Available options:
allDexsClearinghouseState
​
data
object
required