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

# batchSpotClearinghouseState | Hyperliquid Info API

> Hyperliquid batchSpotClearinghouseState: fetch spot account balances for up to 50 wallets in a single request.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 25 per call</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

The Hyperliquid info endpoint with `type: "batchSpotClearinghouseState"` is used to fetch spot account balances for up to 50 wallets in a single request.

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fbatch-spot-clearinghouse-state).
</Tip>

<Info>
  * 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 collapse to a single slot at the position of the first occurrence in the input.
  * Order preservation. Slots in the response are in 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: token treasury monitoring, holder analytics, balance reconciliation, multi-wallet airdrop eligibility checks.
</Info>

Fetches spot account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet; this endpoint fans the requests out in parallel against our private node and returns a 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 `spotClearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails.

## Endpoint

```
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
```

## Request

<ParamField body="type" type="string" required default="batchSpotClearinghouseState">
  Always `"batchSpotClearinghouseState"`.
</ParamField>

<ParamField body="users" type="array<string>" required>
  List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries.
</ParamField>

<ParamField body="dex" type="string">
  Reserved for future HIP-3 spot DEX support. Pass empty string or omit.
</ParamField>

### Example

<CodeGroup>
  ```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": "batchSpotClearinghouseState",
      "users": [
        "0xb0a55f13d22f66e6d495ac98113841b2326e9540",
        "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
      ]
    }'
  ```

  ```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: "batchSpotClearinghouseState",
      users: [
        "0xb0a55f13d22f66e6d495ac98113841b2326e9540",
        "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
      ],
    }),
  });

  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.balances.length} tokens`);
  }
  ```

  ```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": "batchSpotClearinghouseState",
          "users": [
              "0xb0a55f13d22f66e6d495ac98113841b2326e9540",
              "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
          ],
      },
  )

  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}: {len(slot['balances'])} tokens")
  ```
</CodeGroup>

## 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 `batchSpotClearinghouseState` with 3 wallets: one empty wallet, one with a single USDC balance, one with multiple tokens including held amounts.

```json theme={null}
[
  { 
    "user": "0x.....",
    "balances": [] },
  {
    "user": "0x.....",
    "balances": [
      { "coin": "USDC",  "token": 0,   "total": "0.001124", "hold": "0.0", "entryNtl": "0.0" },
      { "coin": "USDE",  "token": 235, "total": "0.0",      "hold": "0.0", "entryNtl": "0.0" },
      { "coin": "USDT0", "token": 268, "total": "0.0",      "hold": "0.0", "entryNtl": "0.0" },
      { "coin": "USDH",  "token": 360, "total": "0.0",      "hold": "0.0", "entryNtl": "0.0" }
    ],
    "tokenToAvailableAfterMaintenance": [[0, "0.001124"]]
  },
  {
    "user": "0x.....",
    "balances": [
      { "coin": "USDC", "token": 0,   "total": "129411.68874505", "hold": "73888.84763", "entryNtl": "0.0" },
      { "coin": "HYPE", "token": 150, "total": "959.37146013",    "hold": "0.0",         "entryNtl": "33092.4684" },
      { "coin": "UBTC", "token": 197, "total": "0.2104009544",    "hold": "0.0",         "entryNtl": "16128.2486005" },
      { "coin": "UETH", "token": 221, "total": "20.87812637",     "hold": "7.0018",      "entryNtl": "49605.34810641" }
    ]
  }
]
```

### 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}
[
  { "balances": [...] },
  {
    "error": "upstream_error",
    "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
    "message": "overall batch timeout exceeded"
  }
]
```

### Per-wallet error slot

<ResponseField name="error" type="string">
  Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field.
</ResponseField>

<ResponseField name="user" type="string">
  The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable description: `upstream_error: <node message>`, `upstream returned HTTP <status>`, `overall batch timeout exceeded`, or similar.
</ResponseField>

## spotClearinghouseState slot field reference

Each success slot mirrors Hyperliquid's native `spotClearinghouseState` response: `balances[]` plus the optional `tokenToAvailableAfterMaintenance` field. There is no schema imposition - it's the raw upstream object.

The `tokenToAvailableAfterMaintenance` field is **optional** and only present when at least one token has a non-zero margin-deduction-aware balance. Wallets without this field can simply ignore it; absence is normal for empty or inactive wallets.

For full per-field types and notes, see the single-wallet endpoint:

<Card title="spotClearinghouseState field reference" icon="code" href="/api-reference/hyperliquid-info/spot-clearinghouse-state">
  Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot.
</Card>

For the canonical upstream documentation, see Hyperliquid's [Spot info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot).

## Related endpoints

<CardGroup cols={2}>
  <Card title="batchClearinghouseState" href="/api-reference/hyperliquid-info/batch-clearinghouse-state">fetch perpetuals account state for up to 50 wallets in a single request.</Card>
  <Card title="spotClearinghouseState" href="/api-reference/hyperliquid-info/spot-clearinghouse-state">fetch a single user's spot account balances by wallet address.</Card>
  <Card title="clearinghouseState" href="/api-reference/hyperliquid-info/clearinghouse-state">fetch a single user's perpetuals account state by wallet address.</Card>
  <Card title="spotMeta" href="/api-reference/hyperliquid-info/spot-meta">fetch the spot universe metadata and full token configuration without live market context.</Card>
</CardGroup>

*Last reviewed: 2026-05-21*