Skip to main content
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
​
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

​
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