> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# batchClearinghouseState | Hyperliquid Info API
> Hyperliquid batchClearinghouseState: fetch perpetuals account state for up to 50 wallets in a single request.
25 per call
Realtime
The Hyperliquid info endpoint with `type: "batchClearinghouseState"` is used to fetch perpetuals account state for up to 50 wallets in a single request.
Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbatch-clearinghouse-state).
* No upstream equivalent. This endpoint exists only on `hypercore.goldrushdata.com`. It is not a passthrough.
* Deduplication is case-insensitive. Two addresses that differ only in case (`0xAbC...` vs `0xabc...`) collapse to a single slot in the output, at the position of the first occurrence in the input.
* Order preservation. The order of slots in the response matches the order of unique wallets in the input.
* Partial failure is normal. HTTP `200 OK` is returned even when individual slots are error envelopes. Always check for the `error` key on each slot before using its fields.
* No cursor or pagination. All requested wallets are fanned out in parallel. For batches larger than 50, issue multiple calls.
* Use cases: portfolio dashboards, multi-wallet PnL aggregators, fleet-level liquidation risk monitoring, copy-trade source-wallet inventory.
Fetches perpetuals account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet, so polling N wallets means N round trips; this endpoint fans them out in parallel against our private node and returns a single combined response.
This is a **GoldRush-native extension**. There is no equivalent on `api.hyperliquid.xyz/info`. The wrapped slots return exactly the same shape as Hyperliquid’s native single-wallet `clearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails.
## Endpoint
```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer
Content-Type: application/json
```
## Request
Always `"batchClearinghouseState"`.
List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries.
Optional perpetuals DEX name. Forwarded unchanged to each per-wallet upstream call. Omit for the primary DEX.
### Example
```bash cURL theme={null}
curl -X POST https://hypercore.goldrushdata.com/info \
-H "Authorization: Bearer $GOLDRUSH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "batchClearinghouseState",
"users": [
"0xb0a55f13d22f66e6d495ac98113841b2326e9540",
"0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
"0x31ca8395cf837de08b24da3f660e77761dfb974b"
]
}'
```
```typescript TypeScript theme={null}
const response = await fetch("https://hypercore.goldrushdata.com/info", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "batchClearinghouseState",
users: [
"0xb0a55f13d22f66e6d495ac98113841b2326e9540",
"0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
"0x31ca8395cf837de08b24da3f660e77761dfb974b",
],
}),
});
const slots = await response.json();
for (const [i, slot] of slots.entries()) {
if ("error" in slot) {
console.warn(`wallet ${slot.user} failed: ${slot.message}`);
continue;
}
console.log(`wallet ${i}: ${slot.withdrawable} USD withdrawable`);
}
```
```python Python theme={null}
import os, requests
response = requests.post(
"https://hypercore.goldrushdata.com/info",
headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"},
json={
"type": "batchClearinghouseState",
"users": [
"0xb0a55f13d22f66e6d495ac98113841b2326e9540",
"0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
"0x31ca8395cf837de08b24da3f660e77761dfb974b",
],
},
)
slots = response.json()
for i, slot in enumerate(slots):
if "error" in slot:
print(f"wallet {slot['user']} failed: {slot['message']}")
continue
print(f"wallet {i}: {slot['withdrawable']} USD withdrawable")
```
## Response
```
HTTP/2 200 OK
Content-Type: application/json
```
The body is a JSON array. **Element `i` corresponds to the i-th unique wallet in the deduplicated input order.** Each element is either:
* The raw upstream Hyperliquid response object for that wallet (success), or
* A slot-level error object (failure for that wallet only, see below).
### All success
Example success body for `batchClearinghouseState` with 3 wallets: one empty account, one with a single cross-margin position, one with a single isolated-margin position.
```json theme={null}
[
{
"user": "0x.....",
"marginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"},
"crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"},
"crossMaintenanceMarginUsed": "0.0",
"withdrawable": "0.0",
"assetPositions": [],
"time": 1777671895013
},
{
"user": "0x.....",
"marginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"},
"crossMarginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"},
"crossMaintenanceMarginUsed": "6.715183",
"withdrawable": "6.464613",
"assetPositions": [
{
"type": "oneWay",
"position": {
"coin": "SUI",
"szi": "-145.8",
"leverage": { "type": "cross", "value": 6 },
"entryPx": "0.91652",
"positionValue": "134.30367",
"unrealizedPnl": "-0.674997",
"returnOnEquity": "-0.0303077319",
"liquidationPx": "1.0657275328",
"marginUsed": "22.383945",
"maxLeverage": 10,
"cumFunding": { "allTime": "0.348217", "sinceOpen": "0.234102", "sinceChange": "0.206894" }
}
}
],
"time": 1777671895076
},
{
"user": "0x.....",
"marginSummary": {"accountValue":"681.226963","totalNtlPos":"1353.54306","totalRawUsd":"-672.316097","totalMarginUsed":"681.226963"},
"crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"},
"crossMaintenanceMarginUsed": "0.0",
"withdrawable": "0.0",
"assetPositions": [
{
"type": "oneWay",
"position": {
"coin": "BTC",
"szi": "0.01734",
"leverage": { "type": "isolated", "value": 2, "rawUsd": "-672.316097" },
"entryPx": "77441.3",
"positionValue": "1353.54306",
"unrealizedPnl": "10.710288",
"returnOnEquity": "0.0159517823",
"liquidationPx": "39263.3464441622",
"marginUsed": "681.226963",
"maxLeverage": 40,
"cumFunding": { "allTime": "0.326319", "sinceOpen": "0.271556", "sinceChange": "-0.026742" }
}
}
],
"time": 1777671895076
}
]
```
### Mixed result (one wallet failed)
When a single wallet fails (upstream timeout, transport failure, parse failure, etc.), only its slot is replaced with an error object. The rest of the batch is unaffected. The HTTP status is still `200 OK`.
```json theme={null}
[
{ "withdrawable": "13104.514502", "...": "..." },
{
"error": "upstream_error",
"user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
"message": "overall batch timeout exceeded"
},
{ "withdrawable": "0.0", "...": "..." }
]
```
### Per-wallet error slot
Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field.
The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order.
Human-readable description: `upstream_error: `, `upstream returned HTTP `, `overall batch timeout exceeded`, or similar.
## clearinghouseState slot field reference
Each success slot mirrors Hyperliquid's native `clearinghouseState` response: `assetPositions[]`, `crossMarginSummary`, `marginSummary`, `crossMaintenanceMarginUsed`, `time`, `withdrawable`. There is no schema imposition - it's the raw upstream object.
For full per-field types and notes (including the two `leverage` shapes and the nullable `liquidationPx`), see the single-wallet endpoint:
Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot.
For the canonical upstream documentation, see Hyperliquid's [Perpetuals info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals).
## Related endpoints
fetch spot account balances for up to 50 wallets in a single request.
fetch a single user's perpetuals account state by wallet address.
fetch a single user's spot account balances by wallet address.
*Last reviewed: 2026-06-13*