POST
/
4f8d8f4040bdacd1577bff8058438274
/
info
info (clearinghouseState)
curl --request POST \
  --url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "clearinghouseState",
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "dex": ""
}'
{
  "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>"
}
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 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 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

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

Response

200 - application/json

User's perpetuals account summary including positions and margin information

The response is of type object.