batchSpotClearinghouseState | Hyperliquid API Docs

Batch query spot account balances for multiple users in a single request. Custom Dwellir endpoint that fans out spotClearinghouseState calls concurrently.

Custom 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

Billed by wallet responses

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.

Response

Both fields are always present. Order matches input order after malformed and duplicate addresses are dropped.

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

Success 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": []
}

Partial Failure Response

If some calls fail, those addresses appear in failed_wallets:

JSON

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

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

spotClearinghouseState: Get spot balances for a single user
batchClearinghouseStates: Batch query perpetual account states
batchPortfolioState: Batch query perp state, spot balances, and account mode
portfolioState: Get single-user perp state, spot balances, and account mode
spotMeta: Get spot trading asset metadata

Batch query Hyperliquid spot balances with Dwellir's HyperCore Info Endpoint. Get your API key →

Custom 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

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

Billed by wallet responses

Response

Both fields are always present. Order matches input order after malformed and duplicate addresses are dropped.

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

Success 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": []
}

Partial Failure Response

If some calls fail, those addresses appear in failed_wallets:

JSON

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

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

spotClearinghouseState: Get spot balances for a single user
batchClearinghouseStates: Batch query perpetual account states
batchPortfolioState: Batch query perp state, spot balances, and account mode
portfolioState: Get single-user perp state, spot balances, and account mode
spotMeta: Get spot trading asset metadata

Batch query Hyperliquid spot balances with Dwellir's HyperCore Info Endpoint. Get your API key →

batchSpotClearinghouseState - HyperCore Info Endpoint

When to Use This Endpoint

Billing

Response

Success Response

Partial Failure Response

Common Use Cases

1. Multi-Account Spot Dashboard

2. Available Balance Check Across Wallets

On this page

batchSpotClearinghouseState - HyperCore Info Endpoint

When to Use This Endpoint

Billing

Response

Success Response

Partial Failure Response

Common Use Cases

1. Multi-Account Spot Dashboard

2. Available Balance Check Across Wallets

On this page