> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypedexer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# allDexsClearinghouseState

> Account state for every user trading through a builder code: one snapshot, then versioned updates

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.