clearinghouseState | Hyperliquid API Docs

Get comprehensive perpetual account state including margin summary, positions, unrealized PnL, and liquidation prices for any user on Hyperliquid.

Get comprehensive account state for perpetual trading, including margin summary, open positions, unrealized PnL, and liquidation prices.

The live response includes top-level withdrawable, crossMaintenanceMarginUsed, and time fields alongside marginSummary and assetPositions.

Why Hyperliquid? Build on the trading-focused EVM and HyperCore ecosystem built for onchain perpetuals and market data with HyperCore market structure, sub-second finality, and direct access to trading-focused data services.

Authenticate HyperCore Info requests by sending your Dwellir API key in the x-api-key header to https://api-hyperliquid-mainnet-info.n.dwellir.com/info.

When to Use This Endpoint

The clearinghouseState endpoint is essential for derivatives traders, portfolio managers, and trading platforms who need to:

Monitor Account Health — Track account value, margin usage, and withdrawable balance
Risk Management — Monitor liquidation prices and position exposure
Portfolio Analytics — Calculate unrealized PnL across all positions
Trading Bots — Make automated trading decisions based on account state

Common Use Cases

1. Check Account Health

Monitor account health and margin utilization:

JavaScript

async function checkAccountHealth(userAddress) {
  const state = await getClearinghouseState(userAddress);
  const margin = state.marginSummary;

  const marginUsed = parseFloat(margin.totalMarginUsed);
  const accountValue = parseFloat(margin.accountValue);
  const utilizationRate = (marginUsed / accountValue) * 100;

  return {
    healthy: utilizationRate < 80,
    utilizationRate: utilizationRate.toFixed(2),
    accountValue: accountValue,
    marginUsed: marginUsed,
    withdrawable: parseFloat(state.withdrawable)
  };
}

// Usage
const health = await checkAccountHealth('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
if (!health.healthy) {
  console.warn(`High margin usage: ${health.utilizationRate}%`);
}

2. Monitor Liquidation Risk

Track liquidation prices for all positions:

JavaScript

async function getLiquidationRisks(userAddress, currentPrices) {
  const state = await getClearinghouseState(userAddress);

  return state.assetPositions.map(pos => {
    const position = pos.position;
    const currentPrice = currentPrices[position.coin];
    const liquidationPrice = parseFloat(position.liquidationPx);
    const isLong = parseFloat(position.szi) > 0;

    const distance = isLong
      ? ((currentPrice - liquidationPrice) / currentPrice) * 100
      : ((liquidationPrice - currentPrice) / currentPrice) * 100;

    return {
      coin: position.coin,
      side: isLong ? 'LONG' : 'SHORT',
      currentPrice: currentPrice,
      liquidationPrice: liquidationPrice,
      distancePercent: distance.toFixed(2),
      risk: distance < 10 ? 'HIGH' : distance < 25 ? 'MEDIUM' : 'LOW'
    };
  });
}

3. Calculate Portfolio Metrics

Compute portfolio-wide metrics:

JavaScript

async function getPortfolioMetrics(userAddress) {
  const state = await getClearinghouseState(userAddress);

  const totalPnl = state.assetPositions.reduce((sum, pos) => {
    return sum + parseFloat(pos.position.unrealizedPnl);
  }, 0);

  const totalPositionValue = state.assetPositions.reduce((sum, pos) => {
    return sum + parseFloat(pos.position.positionValue);
  }, 0);

  const accountValue = parseFloat(state.marginSummary.accountValue);
  const pnlPercent = (totalPnl / accountValue) * 100;

  return {
    accountValue: accountValue,
    totalPnl: totalPnl,
    pnlPercent: pnlPercent.toFixed(2),
    positionCount: state.assetPositions.length,
    totalPositionValue: totalPositionValue,
    leverage: (totalPositionValue / accountValue).toFixed(2)
  };
}

4. Position Summary Report

Generate a detailed position summary:

JavaScript

async function getPositionSummary(userAddress) {
  const state = await getClearinghouseState(userAddress);

  console.log('\n=== Account Summary ===');
  console.log(`Account Value: $${state.marginSummary.accountValue}`);
  console.log(`Margin Used: $${state.marginSummary.totalMarginUsed}`);
  console.log(`Withdrawable: $${state.withdrawable}`);

  console.log('\n=== Open Positions ===');
  state.assetPositions.forEach(pos => {
    const p = pos.position;
    const side = parseFloat(p.szi) > 0 ? 'LONG' : 'SHORT';
    const size = Math.abs(parseFloat(p.szi));

    console.log(`\n${p.coin} ${side}`);
    console.log(`  Size: ${size}`);
    console.log(`  Entry Price: $${p.entryPx}`);
    console.log(`  Position Value: $${p.positionValue}`);
    console.log(`  Unrealized PnL: $${p.unrealizedPnl}`);
    console.log(`  Liquidation Price: $${p.liquidationPx}`);
    console.log(`  Leverage: ${p.leverage.value}x (${p.leverage.type})`);
  });
}

Best Practices

Poll responsibly — Don't poll more frequently than needed (every 5-10 seconds is usually sufficient)
Handle empty positions — Account may have no open positions
Validate addresses — Ensure user addresses are valid Ethereum addresses
Monitor liquidation risk — Set alerts when positions approach liquidation
Cache when appropriate — Cache data briefly to reduce API calls for dashboards

openOrders — Get user's open orders
userFees — Get user fee rates and volume
spotClearinghouseState — Get spot trading account state
meta — Get trading pair metadata for validation

Access real-time Hyperliquid account state with Dwellir's HyperCore Info Endpoint. Get your API key →

clearinghouseState - HyperCore Info Endpoint

When to Use This Endpoint

Common Use Cases

1. Check Account Health

2. Monitor Liquidation Risk

3. Calculate Portfolio Metrics

4. Position Summary Report

Best Practices

On this page