Skip to main content
POST
spotClearinghouseState | Hyperliquid Info API

Credit Cost

1 per call

Processing

Realtime
The Hyperliquid info endpoint with type: "spotClearinghouseState" is used to fetch a single user’s spot account balances by wallet address.
Estimate your monthly cost for this API using the Pricing Calculator.
  • Wire-equal to POST api.hyperliquid.xyz/info with {"type": "spotClearinghouseState", "user": "..."}.
  • USDC balance is returned as token: 0.
  • For real-time push of spot transfers, subscribe to walletTxs and read LedgerSpotTransfer events.
Returns a single user’s spot account state - token-by-token balances and the total USD value. User-keyed. Cached and kept fresh by a per-user WebSocket subscription, so updates are sub-second after any user event.

Endpoint

Request

type
string
default:"spotClearinghouseState"
required
Always "spotClearinghouseState".
user
string
required
The wallet address (lowercase 0x-prefixed hex).
dex
string
Reserved for future HIP-3 spot DEX support. Pass empty string.

Example

Response

Field descriptions

All numeric balance fields (total, hold, entryNtl) are returned as decimal strings, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type.
balances
array<object>
One entry per token the wallet has interacted with on Hyperliquid spot. May be empty ([]) for wallets with no spot history.
tokenToAvailableAfterMaintenance
array<[int, string]>
Optional. Present only when at least one token has a non-zero margin-deduction-aware balance. Each tuple is [tokenId, availableAmountString] where tokenId references balances[].token. Wallets without this field can ignore it; absence is normal for empty or inactive wallets.

batchSpotClearinghouseState

fetch spot account balances for up to 50 wallets in a single request.

batchClearinghouseState

fetch perpetuals account state for up to 50 wallets in a single request.

clearinghouseState

fetch a single user’s perpetuals account state by wallet address.

spotMeta

fetch the spot universe metadata and full token configuration without live market context.
Last reviewed: 2026-06-13