batchClearinghouseStates

Get clearinghouse states for multiple users in a single request.

Get clearinghouse states for multiple users in a single request.

💧New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

POST Request

Field	Type	Description
type	string	Must be "batchClearinghouseStates"
users	array	Array of Ethereum addresses
dex	string	Perp DEX name. Defaults to empty string (native DEX). Use "ALL_DEXES" to fetch clearinghouse state across all dexes (native + all HIP-3 dexes) in one request.

Limits

You can query 1000 users at once. Note that with the ALL_DEXES field passed that limit is 100 users.

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batchClearinghouseStates",
    "users": [
      "0x0000000000000000000000000000000000000001",
      "0x0000000000000000000000000000000000000002"
    ]
  }'

Python

import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'batchClearinghouseStates',
        'users': [
            '0x0000000000000000000000000000000000000001',
            '0x0000000000000000000000000000000000000002'
        ]
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Javascript

import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'batchClearinghouseStates',
        users: [
            '0x0000000000000000000000000000000000000001',
            '0x0000000000000000000000000000000000000002'
        ]
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}

---

Response Fields

Field	Type	Description
successful_states	array	Array of [address, clearinghouseState] tuples
successful_states[n][0]	string	User address
successful_states[n][1].marginSummary	object	Margin summary (accountValue, totalMarginUsed, totalNtlPos, totalRawUsd, withdrawable)
successful_states[n][1].crossMarginSummary	object	Cross margin summary (same fields as marginSummary)
successful_states[n][1].assetPositions	array	Array of position objects
successful_states[n][1].time	int	Timestamp in milliseconds
failed_wallets	array	Array of addresses that failed to fetch

Response

{
  "successful_states": [
    [
      "0x0000000000000000000000000000000000000001",
      {
        "marginSummary": {
          "accountValue": "50000.00",
          "totalMarginUsed": "10000.00",
          "totalNtlPos": "25000.00",
          "totalRawUsd": "45000.00",
          "withdrawable": "15000.00"
        },
        "crossMarginSummary": {
          "accountValue": "50000.00",
          "totalMarginUsed": "10000.00",
          "totalNtlPos": "25000.00",
          "totalRawUsd": "45000.00",
          "withdrawable": "15000.00"
        },
        "assetPositions": [
          {
            "position": {
              "coin": "BTC",
              "entryPx": "45000.00",
              "leverage": {
                "type": "cross",
                "value": 5
              },
              "liquidationPx": "40000.00",
              "marginUsed": "5000.00",
              "maxTradeSzs": ["100000.00", "100000.00"],
              "positionValue": "50000.00",
              "returnOnEquity": "0.10",
              "szi": "1.0",
              "unrealizedPnl": "500.00"
            },
            "type": "oneWay"
          }
        ],
        "time": 1234567890123
      }
    ]
  ],
  "failed_wallets": [
    "0x0000000000000000000000000000000000000003"
  ]
}

Response ALL_DEXES

{
    "successful_states": [
      [
        "0x0000000000000000000000000000000000000001",
        {
          "native": {
            "marginSummary": {
              "accountValue": "50000.00",
              "totalMarginUsed": "10000.00",
              "totalNtlPos": "25000.00",
              "totalRawUsd": "45000.00",
              "withdrawable": "15000.00"
            },
            "crossMarginSummary": {
              "accountValue": "50000.00",
              "totalMarginUsed": "10000.00",
              "totalNtlPos": "25000.00",
              "totalRawUsd": "45000.00",
              "withdrawable": "15000.00"
            },
            "assetPositions": [],
            "time": 1234567890123
          },
          "xyz": {
            "marginSummary": {
              "accountValue": "10000.00",
              "totalMarginUsed": "2000.00",
              "totalNtlPos": "5000.00",
              "totalRawUsd": "9000.00",
              "withdrawable": "3000.00"
            },
            "crossMarginSummary": {
              "accountValue": "10000.00",
              "totalMarginUsed": "2000.00",
              "totalNtlPos": "5000.00",
              "totalRawUsd": "9000.00",
              "withdrawable": "3000.00"
            },
            "assetPositions": [],
            "time": 1234567890123
          },
          ..
        }
      ]
    ],
    "failed_wallets": []
  }