POST
/
info
info (batchClearinghouseStates)
curl --request POST \
  --url https://api.hyperliquid.xyz/info \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "batchClearinghouseStates",
  "users": [
    "0x5e9ee1089755c3435139848e47e6635505d5a13a",
    "0xb7b6f3cea3f66bf525f5d8f965f6dbf6d9b017b2"
  ],
  "dex": ""
}'
[
  {
    "assetPositions": [
      {
        "position": {
          "coin": "<string>",
          "cumFunding": {
            "allTime": "<string>",
            "sinceChange": "<string>",
            "sinceOpen": "<string>"
          },
          "entryPx": "<string>",
          "leverage": {
            "rawUsd": "<string>",
            "type": "<string>",
            "value": 123
          },
          "liquidationPx": "<string>",
          "marginUsed": "<string>",
          "maxLeverage": 123,
          "positionValue": "<string>",
          "returnOnEquity": "<string>",
          "szi": "<string>",
          "unrealizedPnl": "<string>"
        },
        "type": "<string>"
      }
    ],
    "crossMaintenanceMarginUsed": "<string>",
    "crossMarginSummary": {
      "accountValue": "<string>",
      "totalMarginUsed": "<string>",
      "totalNtlPos": "<string>",
      "totalRawUsd": "<string>"
    },
    "marginSummary": {
      "accountValue": "<string>",
      "totalMarginUsed": "<string>",
      "totalNtlPos": "<string>",
      "totalRawUsd": "<string>"
    },
    "time": 123,
    "withdrawable": "<string>"
  }
]
You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet.
The info endpoint with type: "batchClearinghouseStates" retrieves perpetuals account summaries for multiple users in one call. Use this to efficiently fetch positions, margin usage, and account values across many addresses.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

Request body

  • type (string, required) — Must be "batchClearinghouseStates".
  • users (array of strings, required) — One or more onchain addresses in 42‑character hexadecimal format.
  • dex (string, optional) — Perp dex name. Defaults to the empty string which represents the first perp dex.

Example request

Shell
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batchClearinghouseStates",
    "users": [
      "0x31ca8395cf837de08b24da3f660e77761dfb974b",
      "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036"
    ]
  }' \
  https://api.hyperliquid.xyz/info

Response

Returns an array. Each item matches the clearinghouseState schema with fields like assetPositions, marginSummary, crossMarginSummary, time, and withdrawable.

Example response

[
  {
    "assetPositions": [
      {
        "position": {
          "coin": "ETH",
          "cumFunding": {
            "allTime": "514.085417",
            "sinceChange": "0.0",
            "sinceOpen": "0.0"
          },
          "entryPx": "2986.3",
          "leverage": {
            "rawUsd": "-95.059824",
            "type": "isolated",
            "value": 20
          },
          "liquidationPx": "2866.26936529",
          "marginUsed": "4.967826",
          "maxLeverage": 50,
          "positionValue": "100.02765",
          "returnOnEquity": "-0.0026789",
          "szi": "0.0335",
          "unrealizedPnl": "-0.0134"
        },
        "type": "oneWay"
      }
    ],
    "crossMaintenanceMarginUsed": "0.0",
    "crossMarginSummary": {
      "accountValue": "13104.514502",
      "totalMarginUsed": "0.0",
      "totalNtlPos": "0.0",
      "totalRawUsd": "13104.514502"
    },
    "marginSummary": {
      "accountValue": "13109.482328",
      "totalMarginUsed": "4.967826",
      "totalNtlPos": "100.02765",
      "totalRawUsd": "13009.454678"
    },
    "time": 1708622398623,
    "withdrawable": "13104.514502"
  },
  {
    "assetPositions": [],
    "crossMaintenanceMarginUsed": "0.0",
    "crossMarginSummary": {
      "accountValue": "0.0",
      "totalMarginUsed": "0.0",
      "totalNtlPos": "0.0",
      "totalRawUsd": "0.0"
    },
    "marginSummary": {
      "accountValue": "0.0",
      "totalMarginUsed": "0.0",
      "totalNtlPos": "0.0",
      "totalRawUsd": "0.0"
    },
    "time": 1708622398623,
    "withdrawable": "0.0"
  }
]

Use cases

  • Fetch multiple users’ perpetuals states for portfolio screens or multi‑account dashboards.
  • Power backtesting or analytics jobs that require snapshots across many addresses.
  • Reduce API round trips by batching reads.

Body

application/json

Response

200 - application/json

Array of users' perpetuals account summaries including positions and margin information

The response is of type object[].