batchSpotClearinghouseState - HyperCore Info Endpoint
Batch query spot account balances for multiple users in a single request. Custom Dwellir endpoint that fans out spotClearinghouseState calls concurrently.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
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.
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
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
{
"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:
{
"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:
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:
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: 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 →
batchPortfolioState
Batch query clearinghouse state, spot balances, and account abstraction mode for multiple users in a single request. Custom Dwellir endpoint with optional ALL_DEXES aggregation.
clearinghouseState
Get comprehensive perpetual account state including margin summary, positions, unrealized PnL, and liquidation prices for any user on Hyperliquid.