# 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.universeData` and `data.userData` together. The WebSocket
`clearinghouseState` topic splits the shared fields into `assetData`, `venueData`,
and `marketData`, and sends `userData` separately. See the
[user-data WebSocket](/api/websocket#clearinghousestate) for the stream contract.
The WebSocket market filter does not change this REST response.

This replaces the old `data.user` / `data.clearinghouseState` response. Read
positions, margin and caps from `data.userData`; read markets and venue health
from `data.universeData`. No subscription flag or legacy format is supported.

```jsonc
{
  "status": "ok",
  "data": {
    "universeData": {
      "universe": [
        {
          "name": "BTC",
          "szDecimals": 5,
          "maxLeverage": 40,
          "marginTableId": 56,
          "openInterestUsdc": "32500",
          "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
              }
            }
          ]
        }
      ],
      "marketCtxs": [
        {
          "name": "BTC",
          "venue": "hyperliquid",
          "funding": "0.0000125",
          "oraclePx": "65000"
        }
      ],
      "meta": {
        "venues": [
          {
            "venue": "hyperliquid",
            "status": "online",
            "lastCheckedAtMs": 1780000000000,
            "lastOkAtMs": 1780000000000
          }
        ]
      }
    },
    "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`. There is no leverage setting.

`userCaps` are the account-tier limits enforced at admission; `cap_exceeded`
on `/v1/exchange` refers to them.

## Market catalog

`universe[*].name` is the canonical asset used as `a` on `/v1/exchange` and as
`coin` in positions and `marketCtxs`. `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.
`marketCtxs` carries the latest funding rate and oracle price per listed venue
market; either field is absent until observed.

### Open interest and initial margin

`universe[*].openInterestUsdc` is Mosaiq's global gross open interest for the
asset across all users and venues: position notional at oracle price plus the
remaining notional of non-reduce-only open orders. It is `null` when a position
lacks a fresh oracle price; do not read `null` as zero.

The initial-margin rate scales with that value:

```text
baseIMF = 1 / maxLeverage
maintenanceMarginRate = baseIMF / 2

effectiveIMF(oi) =
  baseIMF                                                    if oi <= oiLower
  1                                                          if oi >= oiUpper
  baseIMF + (oi - oiLower) / (oiUpper - oiLower) * (1 - baseIMF)  otherwise
```

`oiLower` and `oiUpper` are per-asset margin parameters set by the operator
and are not published. The defaults are 0 and 1,000,000 USDC; the initial
schedule sets `oiUpper` between 7,000,000 and 30,000,000 USDC per asset.

To estimate the margin of a new order, add its absolute notional to
`openInterestUsdc` and apply `effectiveIMF` to the result. Limit notional
uses the limit price; market notional uses the oracle price moved by
`slippage` in the order's direction. The server stays authoritative.
`marginTableId` is venue metadata and plays no part in this.

## Venue status

`meta.venues[*].status` is gateway-side reachability: `online` when the last
metadata ping succeeded, `offline` when it failed or timed out, `unknown`
before the first ping. An `offline` entry carries the failure in `message`.
It is separate from each market's `universe[*].venues[*].status`.

`meta.recovery` appears only while a venue is `recovering` or `halted` and
explains `venue_recovering` rejections on `/v1/exchange`.