Skip to main content

hl_batchClearinghouseStates JSON-RPC Method

Retrieves clearinghouse states (perp positions and margin data) for multiple users simultaneously in a single request. Maximum of 1000 users per request.

Updated on
Oct 15, 2026
Access to /hypercore JSON-RPC methods requires a Build plan or higher. View pricing to upgrade. For complete stream type definitions and filtering options, see the datasets documentation. This method efficiently retrieves clearinghouse states for up to 1000 users in a single request. The response includes both successful states and any failed wallet addresses. Use the optional dex parameter with value "ALL_DEXES" to retrieve data across all DEXes (native, xyz, flx, vntl, hyna, km, abcd, cash, para, mkts, io). To get spot balances and account mode in the same request, see the multi-wallet balance queries guide.

Parameters

users
array
REQUIRED

Array of Ethereum wallet addresses (0x-prefixed, 42 characters each). Maximum 1000 addresses

dex
string

Optional. Omit for native DEX only, or use 'ALL_DEXES' to fetch data across all DEXes. When using ALL_DEXES, each clearinghouse state will be organized by DEX name (native, xyz, flx, vntl, hyna, km, abcd, cash, para, mkts, io)

Returns

result
object

Batch response containing successful states and failed wallets

successful_states
array

Array of [address, data] tuples. When dex parameter is omitted: data is a clearinghouseState object. When dex='ALL_DEXES': data is an object keyed by DEX names (native, xyz, flx, vntl, hyna, km, abcd, cash, para, mkts, io), where each value is a clearinghouseState object

address
string

Ethereum wallet address (0x-prefixed)

data
object

Clearinghouse state data. Structure depends on dex parameter. Each clearinghouse state contains the following fields

marginSummary
object

Summary of margin metrics

accountValue
string

Total account value as a stringified number

totalMarginUsed
string

Total margin used across all positions as a stringified number

totalNtlPos
string

Total notional position value as a stringified number

totalRawUsd
string

Total raw USD value as a stringified number

crossMarginSummary
object

Summary of cross-margin metrics with identical structure to marginSummary

crossMaintenanceMarginUsed
string

Cross maintenance margin used as a stringified number

withdrawable
string

Amount available for withdrawal as a stringified number

assetPositions
array

Array of position objects for each asset

position
object

Individual asset position data

coin
string

Asset symbol (e.g., BTC, ETH)

entryPx
string

Entry price as a stringified number

leverage
object

Leverage settings for the position

liquidationPx
string

Liquidation price as a stringified number

marginUsed
string

Margin used for this position as a stringified number

unrealizedPnl
string

Unrealized profit and loss as a stringified number

time
integer

Timestamp in milliseconds since Unix epoch

failed_wallets
array

Array of wallet addresses that could not be fetched

address
string

Ethereum wallet address that failed (0x-prefixed)

Request
Don't have an account yet?
Create your Quicknode endpoint in seconds and start building
Get started for free