# HTTP — `GET /v1/clearinghouseState`

Fetch a one-shot account-state snapshot.

```http
GET /v1/clearinghouseState?user=0x0000000000000000000000000000000000000001
```

The endpoint is public. Pass `user` to choose an EVM account address; if omitted,
the server uses the same default user as WebSocket subscriptions.

This is a live RAM snapshot. Right after a place request is accepted, the margin
and open-order impact may be absent for a short window until Mosaiq applies the
venue acknowledgement into live state.

:::note\[Response shape]
All REST endpoints return the same top-level envelope:
`{ status, data, server_time_ms }`. For WebSocket `clearinghouseState`, the
payload under `message.data` matches this endpoint's `data`.
:::

```jsonc
{
  "status": "ok",
  "data": {
    "user": "0x0000000000000000000000000000000000000001",
    "clearinghouseState": {
      "positions": [],
      "marginSummary": {
        "accountValue": 0,
        "totalCashUsdc": 0,
        "availableFunds": 0,
        "excessLiquidity": 0,
        "initialMarginUsed": 0,
        "maintenanceMarginUsed": 0,
        "grossNotional": 0,
        "cushion": 0,
        "leverage": 0
      },
      "userCaps": {
        "tier": "beta",
        "openOrders": 0,
        "maxOpenOrders": 20,
        "maxSingleOrderNotionalUsdc": 10000,
        "openOrderNotionalUsdc": 0,
        "maxOpenOrderNotionalUsdc": 50000,
        "grossNotionalUsdc": 0,
        "maxGrossNotionalUsdc": 100000,
        "initialMarginUsageRate": 0,
        "maxInitialMarginUsageRate": 0.8,
        "maxAssetVenueNotionalUsdc": 50000,
        "assetVenueNotionals": []
      },
      "universe": [
        {
          "name": "BTC",
          "szDecimals": 5,
          "maxLeverage": 50,
          "marginTableId": 0,
          "constraints": {
            "sizeDecimals": 5,
            "sizeIncrement": "0.00001",
            "priceDecimals": 1,
            "tickSize": "0.1",
            "minNotional": "10"
          },
          "venues": [
            {
              "venue": "hyperliquid",
              "venueSymbol": "BTC",
              "instrumentType": "perp",
              "status": "active",
              "constraints": {
                "tickSize": "0.1",
                "sizeIncrement": "0.00001",
                "minNotional": "10"
              }
            }
          ]
        }
      ],
      "marketCtxs": [
        {
          "name": "BTC",
          "venue": "hyperliquid",
          "funding": "0.0000125",
          "oraclePx": "100000"
        }
      ],
      "meta": { "venues": [{ "venue": "hyperliquid", "status": "online" }] }
    }
  },
  "server_time_ms": 1780000000100
}
```

## Symbols and Markets

`universe` follows the Hyperliquid `meta.universe` shape, but `name` is
Mosaiq's canonical asset symbol. Use that canonical symbol everywhere:
`positions[*].coin`, `marketCtxs[*].name`, and `/v1/exchange.orders[*].a`.

`constraints` is the aggregate view for display and client-side prevalidation.
`venues[*].constraints` is the selected-venue source used by `/v1/exchange`.
These fields help size orders, but clients do not need to reimplement every
venue price-format rule. Mosaiq performs final precision fitting and validation
when accepting an exchange request.

`marketCtxs` exposes per-venue context for active perp markets, currently latest
funding and oracle price when available.

## Venue Status

`meta.venues` reports runtime venue reachability as observed by the gateway.
`online` means the gateway can currently fetch the venue's public metadata;
`offline` means the last ping failed or timed out; `unknown` is the boot state
before the first ping completes.

This is separate from `universe[*].venues[*].status`, which describes whether a
specific market is active, post-only, reduce-only, prelisted, delisted, or
inactive.

`meta.recovery` is omitted while recovery is clear. When present, it identifies
venues in `recovering` or `halted` phase and explains temporary
`venue_recovering` trading rejections.