Skip to main content

hl_portfolioState JSON-RPC Method

Retrieves clearinghouse state (perp positions), spot clearinghouse state (spot balances), and account abstraction mode for a single user in one consolidated request.

Updated on
May 07, 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 data from the clearinghouseState, spotClearinghouseState, and userAbstraction endpoints into a single request, providing complete portfolio information for a user. Use the optional dex parameter with value "ALL_DEXES" to retrieve data across all DEXes (native, xyz, flx, vntl, hyna, km, abcd, cash, para).

Parameters

user
string
REQUIRED

Ethereum wallet address (0x-prefixed, 42 characters)

dex
string

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

Returns

result
object

Portfolio state containing perp positions, spot balances, and account mode

clearinghouseState
object

When dex parameter is omitted: returns clearinghouse state object directly with keys marginSummary, crossMarginSummary, crossMaintenanceMarginUsed, withdrawable, assetPositions, time. When dex='ALL_DEXES': returns an object keyed by DEX names (native, xyz, flx, vntl, hyna, km, abcd, cash, para), where each value is a clearinghouse state object with the same structure

dexName (when using ALL_DEXES)
object

DEX-specific clearinghouse state (e.g., native, xyz, flx). Each DEX contains the following structure

marginSummary
object

Summary of margin metrics

accountValue
string

Total account value as a stringified number

totalNtlPos
string

Total notional position value as a stringified number

totalRawUsd
string

Total raw USD value as a stringified number

totalMarginUsed
string

Total margin used across all positions as a stringified number

crossMarginSummary
object

Summary of cross-margin metrics with same structure as marginSummary

accountValue
string

Total account value as a stringified number

totalNtlPos
string

Total notional position value as a stringified number

totalRawUsd
string

Total raw USD value as a stringified number

totalMarginUsed
string

Total margin used across all positions as a stringified number

crossMaintenanceMarginUsed
string

Cross maintenance margin used as a stringified number

withdrawable
string

Amount available for withdrawal as a stringified number

assetPositions
array

Array of asset position objects

assetPosition
object

Asset position wrapper

type
string

Position type (e.g., oneWay)

position
object

Position details

coin
string

Asset symbol (e.g., BTC, ETH, HYPE). For non-native DEXes, prefixed with dex name (e.g., flx:USDE)

szi
string

Signed position size as a stringified number (negative for short, positive for long)

leverage
object

Leverage configuration

type
string

Leverage type (e.g., cross, isolated)

value
integer

Leverage multiplier value

entryPx
string

Entry price as a stringified number

positionValue
string

Current position value as a stringified number

unrealizedPnl
string

Unrealized profit and loss as a stringified number

returnOnEquity
string

Return on equity as a stringified number

liquidationPx
string

Liquidation price as a stringified number

marginUsed
string

Margin used for this position as a stringified number

maxLeverage
integer

Maximum allowed leverage for this asset

cumFunding
object

Cumulative funding information

allTime
string

All-time cumulative funding as a stringified number

sinceOpen
string

Cumulative funding since position opened as a stringified number

sinceChange
string

Cumulative funding since last position change as a stringified number

time
integer

Timestamp in milliseconds since Unix epoch

spotClearinghouseState
object

Spot balances and available amounts

balances
array

Array of spot balance objects

balance
object

Individual spot balance data

coin
string

Coin symbol (e.g., USDC, HYPE, USDE)

token
integer

Token index number

total
string

Total balance as a stringified number

hold
string

Amount on hold as a stringified number

entryNtl
string

Entry notional value as a stringified number

tokenToAvailableAfterMaintenance
array

Array of [tokenId, availableAmount] tuples showing available balance after maintenance margin

tuple
array

[tokenId, availableAmount] tuple

tokenId
integer

Token index number

availableAmount
string

Available amount after maintenance margin as a stringified number

userAbstraction
string

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

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