Skip to main content

hl_batchPortfolioStates JSON-RPC Method

Retrieves complete portfolio states (perp positions, spot balances, and account abstraction mode) for multiple users simultaneously in a single request. Maximum of 500 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 consolidates clearinghouse states, spot balances, and account abstraction modes for up to 500 users in a single request. The response includes both successful portfolio 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). Credits are charged dynamically based on the number of users in the request. For a full walkthrough with curl, TypeScript, and SQL Explorer, see the multi-wallet balance queries guide.

Parameters

users
array
REQUIRED

Array of Ethereum wallet addresses (0x-prefixed, 42 characters each). Maximum 500 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 portfolio states and failed wallets

successful_states
array

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

address
string

Ethereum wallet address (0x-prefixed)

data
object

Portfolio state data. Structure depends on dex parameter

clearinghouseState
object

When dex parameter is omitted: a single clearinghouse state object. When dex='ALL_DEXES': an object keyed by DEX names (native, xyz, flx, vntl, hyna, km, abcd, cash, para, mkts, io), where each value is a clearinghouse state object

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

withdrawable
string

Amount available for withdrawal as a stringified number

crossMarginSummary
object

Summary of cross-margin metrics with identical structure to marginSummary

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

spotClearinghouseState
object

Spot clearinghouse state containing balances and available amounts after maintenance

balances
array

Array of spot balance objects

coin
string

Coin symbol

token
integer

Token index

total
string

Total balance as a stringified number

hold
string

Amount on hold as a stringified number

entryNtl
string

Entry notional as a stringified number

tokenToAvailableAfterMaintenance
array

Array of [token_index, available_amount] tuples showing available balance after maintenance requirements for each token

userAbstraction
string

Account mode: unifiedAccount, portfolioMargin, disabled, default, or dexAbstraction

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