> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# clearinghouseState | Hyperliquid info
> Reference docs for the clearinghouseState JSON-RPC method on the Hyperliquid info blockchain, available via Chainstack JSON-RPC nodes.
This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown.
The `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.
## 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 the `assetPositions` 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
Both `crossMarginSummary` 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 Shell theme={"system"}
curl -X POST \
-H "Content-Type: application/json" \
-d '{"type": "clearinghouseState", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b"}' \
https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info
```
```python hyperliquid-python-sdk theme={"system"}
from hyperliquid.info import Info
info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True)
# user_state posts {"type": "clearinghouseState", "user": address}.
state = info.user_state("0x31ca8395cf837de08b24da3f660e77761dfb974b")
print(state)
```
```typescript @nktkas/hyperliquid theme={"system"}
import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
const transport = new HttpTransport({
apiUrl: "YOUR_CHAINSTACK_ENDPOINT",
});
const info = new InfoClient({ transport });
// clearinghouseState posts {"type": "clearinghouseState", "user": address}.
const state = await info.clearinghouseState({
user: "0x31ca8395cf837de08b24da3f660e77761dfb974b",
});
console.log(state);
```
**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR\_CHAINSTACK\_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production.
## Example response
```json theme={"system"}
{
"assetPositions": [
{
"position": {
"coin": "ETH",
"cumFunding": {
"allTime": "514.085417",
"sinceChange": "0.0",
"sinceOpen": "0.0"
},
"entryPx": "2986.3",
"leverage": {
"rawUsd": "-95.059824",
"type": "isolated",
"value": 20
},
"liquidationPx": "2866.26936529",
"marginUsed": "4.967826",
"maxLeverage": 50,
"positionValue": "100.02765",
"returnOnEquity": "-0.0026789",
"szi": "0.0335",
"unrealizedPnl": "-0.0134"
},
"type": "oneWay"
}
],
"crossMaintenanceMarginUsed": "0.0",
"crossMarginSummary": {
"accountValue": "13104.514502",
"totalMarginUsed": "0.0",
"totalNtlPos": "0.0",
"totalRawUsd": "13104.514502"
},
"marginSummary": {
"accountValue": "13109.482328",
"totalMarginUsed": "4.967826",
"totalNtlPos": "100.02765",
"totalRawUsd": "13009.454678"
},
"time": 1708622398623,
"withdrawable": "13104.514502"
}
```
## Use case
The `info` 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
This endpoint is typically called frequently to keep trading interfaces updated with real-time position and account information.
## OpenAPI
````yaml openapi/hyperliquid_node_api/hypercore_info/info_clearinghousestate.json post /4f8d8f4040bdacd1577bff8058438274/info
openapi: 3.0.0
info:
title: Hyperliquid Node API
version: 1.0.0
description: This is an API for interacting with Chainstack Hyperliquid node.
servers:
- url: https://hyperliquid-mainnet.core.chainstack.com
security: []
paths:
/4f8d8f4040bdacd1577bff8058438274/info:
post:
tags:
- hyperliquid operations
summary: info (clearinghouseState)
operationId: infoClearinghouseState
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
default: clearinghouseState
enum:
- clearinghouseState
description: Request type to retrieve user's perpetuals account summary
user:
type: string
default: '0x31ca8395cf837de08b24da3f660e77761dfb974b'
description: Onchain address in 42-character hexadecimal format
dex:
type: string
default: ''
description: >-
Perp dex name. Defaults to empty string which represents the
first perp dex
required:
- type
- user
responses:
'200':
description: >-
User's perpetuals account summary including positions and margin
information
content:
application/json:
schema:
type: object
properties:
assetPositions:
type: array
description: Array of user's asset positions
items:
type: object
properties:
position:
type: object
properties:
coin:
type: string
description: Asset symbol
cumFunding:
type: object
description: Cumulative funding information
properties:
allTime:
type: string
description: All-time cumulative funding
sinceChange:
type: string
description: Funding since last position change
sinceOpen:
type: string
description: Funding since position opened
entryPx:
type: string
description: Entry price
leverage:
type: object
description: Leverage information
properties:
rawUsd:
type: string
description: Raw USD value
type:
type: string
description: Leverage type (isolated/cross)
value:
type: number
description: Leverage value
liquidationPx:
type: string
description: Liquidation price
marginUsed:
type: string
description: Margin used for this position
maxLeverage:
type: number
description: Maximum leverage allowed
positionValue:
type: string
description: Current position value
returnOnEquity:
type: string
description: Return on equity
szi:
type: string
description: Position size
unrealizedPnl:
type: string
description: Unrealized profit and loss
type:
type: string
description: Position type
crossMaintenanceMarginUsed:
type: string
description: Cross maintenance margin used
crossMarginSummary:
type: object
description: Cross margin account summary
properties:
accountValue:
type: string
description: Total account value
totalMarginUsed:
type: string
description: Total margin used
totalNtlPos:
type: string
description: Total notional position
totalRawUsd:
type: string
description: Total raw USD
marginSummary:
type: object
description: Overall margin summary
properties:
accountValue:
type: string
description: Total account value
totalMarginUsed:
type: string
description: Total margin used
totalNtlPos:
type: string
description: Total notional position
totalRawUsd:
type: string
description: Total raw USD
time:
type: number
description: Timestamp of the data
withdrawable:
type: string
description: Amount available for withdrawal
````