# batchSpotClearinghouseState - HyperCore Info Endpoint

Batch query spot account balances for multiple users in a single request. This is a Dwellir custom endpoint. Standard Hyperliquid nodes do not serve it.

Authenticate by including your Dwellir API key in the URL path: `https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info`.

## When to Use This Endpoint

The `batchSpotClearinghouseState` endpoint serves applications that need spot balances for many users at once. It fans out individual `spotClearinghouseState` calls concurrently and aggregates the results. You do not manage fan-out or per-wallet error handling yourself.

Spot state is not DEX-scoped. There is no `dex` field.

- **Portfolio Dashboards**: Fetch spot balances for all tracked wallets in one call
- **Treasury Monitoring**: Track available and held balances across a fleet of accounts
- **Trade Validation**: Check whether many wallets have enough free balance before placing orders
- **Fund Management**: Aggregate token holdings across sub-accounts or strategies

## Billing

`batchSpotClearinghouseState` is billed by the number of distinct valid wallets in the batch, not as one response per HTTP request.
A request with `1,000` distinct valid wallets counts as `1,000` responses/API credits.

Wallets listed in `failed_wallets` still count because an upstream lookup was performed for them. Duplicate and malformed wallet entries are removed before the batch runs and do not count. Non-success HTTP responses are not charged.

## Request Parameters

- `type` (`string, required`): parameter: Must be `"batchSpotClearinghouseState"`
- `users` (`string[], required`): parameter: Non-empty list of wallet addresses

## Request Example

```bash
curl -X POST "https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info" \
  -H "content-type: application/json" \
  -d '{
  "type": "batchSpotClearinghouseState",
  "users": [
    "0x00f2548cf639e54420e501a35346e8458989e6bd",
    "0x010461c14e146ac35fe42271bdc1134ee31c703a"
  ]
}'
```

## Response Fields

- `successful_states` (`[address, state][], required`): Array of two-element tuples. `address` is the wallet address; `state` is the raw upstream `spotClearinghouseState` object.
- `failed_wallets` (`string[], required`): Addresses whose upstream call failed (timeout, non-200, etc.).

## Successful Response

```json
{
  "successful_states": [
    [
      "0x00f2548cf639e54420e501a35346e8458989e6bd",
      {
        "balances": [
          {
            "coin": "USDC",
            "token": 0,
            "total": "0.01261784",
            "hold": "0.0",
            "entryNtl": "0.0"
          }
        ]
      }
    ],
    [
      "0x010461c14e146ac35fe42271bdc1134ee31c703a",
      {
        "balances": [
          {
            "coin": "USDC",
            "token": 0,
            "total": "12.27568764",
            "hold": "0.0",
            "entryNtl": "0.0"
          }
        ]
      }
    ]
  ],
  "failed_wallets": []
}
```

## Common Use Cases

### 1. Multi-Account Spot Dashboard

Fetch and display spot balances for a set of tracked wallets:

```javascript
async function getMultiAccountSpotBalances(wallets) {
  const result = await getBatchSpotClearinghouseState(wallets);

  const dashboard = result.successful_states.map(([address, state]) => {
    const holdings = state.balances
      .filter((balance) => parseFloat(balance.total) > 0)
      .map((balance) => ({
        token: balance.coin,
        total: parseFloat(balance.total),
        available: parseFloat(balance.total) - parseFloat(balance.hold)
      }));

    return { address, holdings };
  });

  if (result.failed_wallets.length > 0) {
    console.warn(`Failed to fetch: ${result.failed_wallets.join(', ')}`);
  }

  return dashboard;
}
```

### 2. Available Balance Check Across Wallets

Calculate free USDC for every wallet in the batch:

```javascript
async function getAvailableUsdc(wallets) {
  const result = await getBatchSpotClearinghouseState(wallets);

  return result.successful_states.map(([address, state]) => {
    const usdc = state.balances.find((balance) => balance.coin === 'USDC');
    const total = usdc ? parseFloat(usdc.total) : 0;
    const hold = usdc ? parseFloat(usdc.hold) : 0;

    return {
      address,
      available: total - hold,
      hold
    };
  });
}
```

## Related Endpoints

- [**spotClearinghouseState**](https://www.dwellir.com/docs/hyperliquid/spot-clearinghouse-state): Get spot balances for a single user
- [**batchClearinghouseStates**](https://www.dwellir.com/docs/hyperliquid/batch-clearinghouse-states): Batch query perpetual account states
- [**batchPortfolioState**](https://www.dwellir.com/docs/hyperliquid/batch-portfolio-state): Batch query perp state, spot balances, and account mode
- [**portfolioState**](https://www.dwellir.com/docs/hyperliquid/portfolio-state): Get single-user perp state, spot balances, and account mode
- [**spotMeta**](https://www.dwellir.com/docs/hyperliquid/spot-meta): Get spot trading asset metadata

***

*Batch query Hyperliquid spot balances with Dwellir's HyperCore Info Endpoint. [Get your API key →](https://dashboard.dwellir.com/register)*