clearinghouseState | Hyperliquid info

Reference docs for the clearinghouseState JSON-RPC method on the Hyperliquid info blockchain, available via Chainstack JSON-RPC nodes.

POST /4f8d8f4040bdacd1577bff8058438274/info

info (clearinghouseState)

cURL

curl --request POST \
  --url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "clearinghouseState",
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "dex": ""
}
'

200

{
  "assetPositions": [
    {
      "position": {
        "coin": "<string>",
        "cumFunding": {
          "allTime": "<string>",
          "sinceChange": "<string>",
          "sinceOpen": "<string>"
        },
        "entryPx": "<string>",
        "leverage": {
          "rawUsd": "<string>",
          "type": "<string>",
          "value": 123
        },
        "liquidationPx": "<string>",
        "marginUsed": "<string>",
        "maxLeverage": 123,
        "positionValue": "<string>",
        "returnOnEquity": "<string>",
        "szi": "<string>",
        "unrealizedPnl": "<string>"
      },
      "type": "<string>"
    }
  ],
  "crossMaintenanceMarginUsed": "<string>",
  "crossMarginSummary": {
    "accountValue": "<string>",
    "totalMarginUsed": "<string>",
    "totalNtlPos": "<string>",
    "totalRawUsd": "<string>"
  },
  "marginSummary": {
    "accountValue": "<string>",
    "totalMarginUsed": "<string>",
    "totalNtlPos": "<string>",
    "totalRawUsd": "<string>"
  },
  "time": 123,
  "withdrawable": "<string>"
}

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 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.

Get your own node endpoint today

Start 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 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

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "clearinghouseState", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b"}' \
  https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info

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. The curl above uses a shared public endpoint for quick checks only; do not use it in production.

Example response

{
  "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.

Body

application/json

type · enum<string> · default: clearinghouseState · required

Request type to retrieve user's perpetuals account summary

Available options: clearinghouseState

user · string · default: 0x31ca8395cf837de08b24da3f660e77761dfb974b · required

Onchain address in 42-character hexadecimal format

dex · string · default: ""

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

assetPositions · object[]

Array of user's asset positions

Show child attributes

crossMaintenanceMarginUsed · string

Cross maintenance margin used

crossMarginSummary · object

Cross margin account summary

Show child attributes

marginSummary · object

Overall margin summary

Show child attributes

time · number

Timestamp of the data

withdrawable · string

Amount available for withdrawal