clearinghouseState - HyperCore Info Endpoint
Get comprehensive perpetual account state including margin summary, positions, unrealized PnL, and liquidation prices for any user on Hyperliquid.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
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 by including your Dwellir API key in the URL path: https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/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
curl -X POST "https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info" \
-H "content-type: application/json" \
-d '{
"type": "clearinghouseState",
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f"
}'The dex Parameter
By default, clearinghouseState returns state for the main Hyperliquid perpetuals DEX. To query a specific HIP-3 (permissionless perpetuals) market instead, include the dex field:
curl -X POST "https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info" \
-H "content-type: application/json" \
-d '{
"type": "clearinghouseState",
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
"dex": "xyz"
}'dex value | Returns |
|---|---|
| (omitted) | Main Hyperliquid perpetuals DEX |
"xyz" | State for the specified HIP-3 market |
"ALL_DEXES" | State for the main Hyperliquid DEX plus all operational HIP-3 DEXs |
ALL_DEXES Support
Use dex: "ALL_DEXES" to fan out a single-user clearinghouseState request across the native DEX and every operational HIP-3 DEX. The response shape changes from a single state object to an object keyed by DEX name.
ALL_DEXES Request
curl -X POST "https://api-hyperliquid-mainnet-info.n.dwellir.com/YOUR_API_KEY/info" \
-H "content-type: application/json" \
-d '{
"type": "clearinghouseState",
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
"dex": "ALL_DEXES"
}'ALL_DEXES Response Shape
When dex is set to "ALL_DEXES", the response becomes a DEX map instead of a single clearinghouse state:
{
"native": {
"marginSummary": {
"accountValue": "555.13644",
"totalMarginUsed": "0.0",
"totalNtlPos": "0.0",
"totalRawUsd": "555.13644"
},
"crossMarginSummary": {
"accountValue": "555.13644",
"totalMarginUsed": "0.0",
"totalNtlPos": "0.0",
"totalRawUsd": "555.13644"
},
"crossMaintenanceMarginUsed": "0.0",
"withdrawable": "555.13644",
"assetPositions": [],
"time": 1776448114549
},
"xyz": {
"marginSummary": {
"accountValue": "0.0",
"totalMarginUsed": "0.0",
"totalNtlPos": "0.0",
"totalRawUsd": "0.0"
},
"crossMarginSummary": {
"accountValue": "0.0",
"totalMarginUsed": "0.0",
"totalNtlPos": "0.0",
"totalRawUsd": "0.0"
},
"crossMaintenanceMarginUsed": "0.0",
"withdrawable": "0.0",
"assetPositions": [],
"time": 1776448114649
}
}The native DEX always appears under the "native" key. Additional keys correspond to operational HIP-3 DEX names from perpDexs.
Common Use Cases
1. Check Account Health
Monitor account health and margin utilization:
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:
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:
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:
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
Related Endpoints
- openOrders — Get user's open orders
- userFees — Get user fee rates and volume
- spotClearinghouseState — Get spot trading account state
- portfolioState — Get perp state, spot balances, and user abstraction in one request
- meta — Get trading pair metadata for validation
Access real-time Hyperliquid account state with Dwellir's HyperCore Info Endpoint. Get your API key →
batchSpotClearinghouseState
Batch query spot account balances for multiple users in a single request. Custom Dwellir endpoint that fans out spotClearinghouseState calls concurrently.
delegations
Get detailed staking delegation information for a user on Hyperliquid. Track validators, amounts, rewards, and delegation history.