info
endpoint with type: "clearinghouseState"
retrieves a user’s perpetuals account summary including open positions and margin information for the Hyperliquid exchange. This endpoint provides comprehensive data about a user’s trading positions, leverage, margin usage, and account value.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.
Parameters
Request body
type
(string, required) — The request type. Must be"clearinghouseState"
to retrieve user’s account summary.user
(string, required) — Onchain address in 42-character hexadecimal format (e.g.,0x31ca8395cf837de08b24da3f660e77761dfb974b
).dex
(string, optional) — Perp dex name. Defaults to the empty string which represents the first perp dex.
Response
The response is an object containing comprehensive account information:Top-level fields
assetPositions
(array) — Array of the user’s current asset positions.crossMaintenanceMarginUsed
(string) — Cross maintenance margin used.crossMarginSummary
(object) — Cross margin account summary.marginSummary
(object) — Overall margin summary.time
(number) — Timestamp of the data.withdrawable
(string) — Amount available for withdrawal.
Asset positions structure
Each item in theassetPositions
array contains:
position
(object) — Position details:coin
(string) — Asset symbol (e.g., “ETH”, “BTC”).cumFunding
(object) — Cumulative funding information:allTime
(string) — All-time cumulative funding.sinceChange
(string) — Funding since last position change.sinceOpen
(string) — Funding since position opened.
entryPx
(string) — Entry price of the position.leverage
(object) — Leverage information:rawUsd
(string) — Raw USD value.type
(string) — Leverage type (“isolated” or “cross”).value
(number) — Leverage multiplier.
liquidationPx
(string) — Price at which position would be liquidated.marginUsed
(string) — Margin used for this position.maxLeverage
(number) — Maximum leverage allowed for this asset.positionValue
(string) — Current value of the position.returnOnEquity
(string) — Return on equity percentage.szi
(string) — Position size.unrealizedPnl
(string) — Unrealized profit and loss.
type
(string) — Position type (e.g., “oneWay”).
Margin summary objects
BothcrossMarginSummary
and marginSummary
contain:
accountValue
(string) — Total account value.totalMarginUsed
(string) — Total margin used.totalNtlPos
(string) — Total notional position.totalRawUsd
(string) — Total raw USD.
Example request
Shell
Example response
Use case
Theinfo
endpoint with type: "clearinghouseState"
is essential for perpetuals trading applications that need to:
- Display user’s current positions and their performance
- Show margin usage and available leverage
- Calculate liquidation risks and price levels
- Display account value and withdrawable amounts
- Monitor position-level funding payments
- Implement risk management features
- Build trading dashboards with comprehensive position data
Body
application/json
Request type to retrieve user's perpetuals account summary
Available options:
clearinghouseState
Onchain address in 42-character hexadecimal format
Perp dex name. Defaults to empty string which represents the first perp dex
Response
200 - application/json
User's perpetuals account summary including positions and margin information