> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/user-position-data/batchclearinghousestates.md).

# batchClearinghouseStates

Get clearinghouse states for multiple users in a single request.

{% hint style="info" %}
💧**New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.**
{% endhint %}

## POST Request

<table><thead><tr><th width="163.06915283203125">Field</th><th width="135.80908203125">Type</th><th width="471.56585693359375">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"batchClearinghouseStates"</code></td></tr><tr><td><code>users</code></td><td>array</td><td>Array of Ethereum addresses</td></tr><tr><td><code>dex</code></td><td>string</td><td>Perp DEX name. Defaults to empty string (native DEX). Use <code>"ALL_DEXES"</code> to fetch clearinghouse state across all dexes (native + all HIP-3 dexes) in one request.</td></tr></tbody></table>

### Limits

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

{% tabs %}
{% tab title="cURL" %}

```bash
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"
    ]
  }'
```

{% endtab %}

{% tab title="Python" %}

```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())
```

{% endtab %}

{% tab title="Javascript" %}

```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);
}
```

{% endtab %}
{% endtabs %}

***

## 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                                                |

<details>

<summary>Response</summary>

```json
{
  "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"
  ]
}
```

</details>

<details>

<summary>Response ALL_DEXES</summary>

```json
{
    "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": []
  }
```

</details>