# HTTP — `GET /v1/clearinghouseState` One-shot account snapshot: positions, margin, caps, the market catalog, and venue status. ```http GET /v1/clearinghouseState?user=0x0000000000000000000000000000000000000001 ``` The endpoint is public. `user` is an EVM address; if omitted, the server uses its default user. A malformed address fails with `bad_request`. The endpoint fails with HTTP `503` and `oracle_unavailable` or `risk_core_unavailable` when the account state cannot be priced or read. Right after an accepted placement, the margin and open-order impact can lag until Mosaiq applies the venue acknowledgement. REST returns `data.assetData`, `data.venueData`, `data.marketData`, and `data.userData` together. The WebSocket `clearinghouseState` topic sends the same four payloads as separate messages. See the [user-data WebSocket](/api/websocket#clearinghousestate) for the stream contract. The WebSocket market filter does not change this REST response. ```jsonc { "status": "ok", "data": { "assetData": { "universe": [ { "name": "BTC", "szDecimals": 5, "maxLeverage": 40, "marginTableId": 56, "constraints": { "sizeDecimals": 5, "sizeIncrement": "0.00001", "priceDecimals": 1, "tickSize": "0.1", "minNotional": "10", "supportsReduceOnly": true, "supportsPostOnly": true }, "venues": [ { "venue": "hyperliquid", "venueSymbol": "BTC", "instrumentType": "perp", "status": "active", "constraints": { "sizeDecimals": 5, "sizeIncrement": "0.00001", "priceDecimals": 1, "tickSize": "0.1", "minNotional": "10", "supportsReduceOnly": true, "supportsPostOnly": true } } ] } ] }, "venueData": { "meta": { "venues": [ { "venue": "hyperliquid", "status": "online", "lastCheckedAtMs": 1780000000000, "lastOkAtMs": 1780000000000 } ] } }, "marketData": { "marketCtxs": [ { "name": "BTC", "venue": "hyperliquid", "funding": "0.0000125", "oraclePx": "65000" } ], "openInterestUsdc": { "BTC": "32500" } }, "userData": { "user": "0x0000000000000000000000000000000000000001", "positions": [ { "coin": "BTC", "venue": "hyperliquid", "entryPx": 64000, "szi": 0.5, "positionValue": 32500, "unrealizedPnl": 500, "unrealizedFunding": -1.25 } ], "marginSummary": { "accountValue": 10500, "totalCashUsdc": 10000, "availableFunds": 8657.6, "excessLiquidity": 10093.75, "initialMarginUsed": 1842.4, "maintenanceMarginUsed": 406.25, "grossNotional": 32500, "cushion": 0.9613, "leverage": 3.095 }, "userCaps": { "tier": "beta", "openOrders": 0, "maxOpenOrders": 20, "maxSingleOrderNotionalUsdc": 50000, "openOrderNotionalUsdc": 0, "maxOpenOrderNotionalUsdc": 250000, "grossNotionalUsdc": 32500, "maxGrossNotionalUsdc": 500000, "initialMarginUsageRate": 0.1755, "maxInitialMarginUsageRate": 0.8, "maxAssetVenueNotionalUsdc": 100000, "assetVenueNotionals": [ { "asset": "BTC", "venue": "hyperliquid", "notionalUsdc": 32500 } ] } } }, "server_time_ms": 1780000000100 } ``` ## Positions and margin `positions` are venue-scoped legs identified by `(coin, venue)`. Margin is charged per leg: a long on one venue and a short on another are not netted. Values in `positions`, `marginSummary`, and `userCaps` are JSON numbers. * `accountValue`: cash plus unrealized PnL. * `availableFunds`: `accountValue - initialMarginUsed`, the room to open risk. * `excessLiquidity`: `accountValue - maintenanceMarginUsed`, the distance to liquidation. * `initialMarginUsed`: positions plus every open non-reduce-only order, whatever its time-in-force. * `maintenanceMarginUsed`: positions only. * `leverage`: `grossNotional / accountValue`, or 0 when `accountValue` is zero or negative. There is no leverage setting. * `entryPx`: the average entry price rounded to the venue's price decimals, for display only. `positionValue` and `unrealizedPnl` are computed from the unrounded value, so they need not match `entryPx * szi` exactly. `userCaps` are the limits for your account tier, checked before Mosaiq accepts an order. `cap_exceeded` on `/v1/exchange` refers to these limits. ## Market catalog `assetData.universe[*].name` is the canonical asset used as `a` on `/v1/exchange`, as `coin` in positions, and as `name` in `marketData.marketCtxs`. `assetData.universe[*].venues[*]` lists each venue market with its trading `status` and the `constraints` that `/v1/exchange` validates for that venue. The asset-level `constraints` is an aggregate for display. `onlyIsolated` and `isDelisted` appear only when true. `requiresIsolatedMargin` and `minBaseAmount` appear on venues that have them. `marketData.marketCtxs[*].funding` is the venue's current predicted hourly funding rate as a decimal: `0.0000125` is 0.00125% per hour. It matches the `funding` field of Hyperliquid's asset contexts, a prediction that moves during the hour. It is not the rate a settlement applied; settled rates are in [`/v1/userFunding`](/api/user-funding). Lighter's percent rate is converted to the same decimal form. `funding` is absent when Mosaiq had no fresh rate for that venue market when it built the data. A Hyperliquid rate stays fresh for 60 seconds after its last update. A Lighter rate stays fresh while the Lighter feed of Mosaiq is connected, because Lighter sends a market only when its stats change. The rate expires 60 seconds after that feed disconnects, or 60 seconds after Lighter sends the market without a rate. A WebSocket message can reach you after that check, so the rate it carries can be slightly older. `oraclePx` uses the live oracle price when available, otherwise the last funding settlement price, and is absent until observed. This fallback does not price account positions or margin. ### Open interest and initial margin `marketData.openInterestUsdc[name]` is Mosaiq's global gross open interest for an asset across all users and venues. It includes position notional at oracle price and the remaining notional of non-reduce-only open orders. The value is `null` when a position lacks a fresh oracle price. Do not read `null` as zero. The initial-margin rate starts at `1 / maxLeverage` and can rise to 100% as open interest increases. The maintenance rate remains `1 / (2 * maxLeverage)`. The thresholds for that increase are not published, so `maxLeverage` alone does not determine an order's margin requirement. Use `marginSummary` for your account's current requirements; Mosaiq checks new orders when submitted. `marginTableId` is venue metadata, not Mosaiq's margin schedule. ## Venue status `venueData.meta.venues[*].status` reports whether Mosaiq can reach the venue. It is `online` when the last check succeeded, `offline` when it failed or timed out, and `unknown` before the first check. An `offline` entry carries the failure in `message`. It is separate from each market's `assetData.universe[*].venues[*].status`. `venueData.meta.recovery` appears only while a venue is `recovering` or `halted`. It explains `venue_recovering` rejections on `/v1/exchange`.