Docs

liquidatable - HyperCore Info Endpoint

Check if a user's positions are liquidatable on Hyperliquid. Monitor liquidation risk, margin health, and position safety.

Check if a user's positions are at risk of liquidation, providing critical risk management information.

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 liquidatable endpoint is essential for:

  • Risk Monitoring — Check liquidation risk for positions
  • Margin Management — Monitor account health and safety
  • Liquidation Alerts — Build alert systems for position risk
  • Portfolio Safety — Ensure positions are within safe margins

Common Use Cases

1. Liquidation Risk Monitor

Monitor liquidation risk continuously:

JavaScript
async function monitorLiquidationRisk(userAddress) {
  const status = await checkLiquidatable(userAddress);

  console.log('=== Liquidation Risk Monitor ===\n');

  if (status.liquidatable) {
    console.error('⚠️  CRITICAL: Positions are liquidatable!');
    console.error('Action required: Add margin or reduce position size');
  } else {
    console.log('✓ Positions are safe from liquidation');
  }

  return status.liquidatable;
}

// Usage
const atRisk = await monitorLiquidationRisk('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');

2. Build Liquidation Alert System

Create automated liquidation alerts:

JavaScript
class LiquidationAlertSystem {
  constructor(userAddress, checkIntervalMs = 30000) {
    this.userAddress = userAddress;
    this.checkIntervalMs = checkIntervalMs;
    this.wasLiquidatable = false;
  }

  async start(onAlert) {
    while (true) {
      try {
        const status = await checkLiquidatable(this.userAddress);

        if (status.liquidatable && !this.wasLiquidatable) {
          // Just became liquidatable - send alert
          onAlert({
            severity: 'critical',
            message: 'Positions now liquidatable!',
            timestamp: new Date().toISOString()
          });
        } else if (!status.liquidatable && this.wasLiquidatable) {
          // No longer liquidatable - send recovery alert
          onAlert({
            severity: 'info',
            message: 'Positions no longer liquidatable',
            timestamp: new Date().toISOString()
          });
        }

        this.wasLiquidatable = status.liquidatable;
      } catch (error) {
        console.error('Alert system error:', error);
      }

      await new Promise(r => setTimeout(r, this.checkIntervalMs));
    }
  }
}

// Usage
const alertSystem = new LiquidationAlertSystem('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
alertSystem.start((alert) => {
  console.log(`[${alert.severity.toUpperCase()}] ${alert.message}`);
  // Send notification via email, SMS, etc.
});

3. Risk Dashboard

Create a risk management dashboard:

JavaScript
async function getRiskDashboard(userAddress) {
  try {
    const status = await checkLiquidatable(userAddress);

    return {
      status: 'success',
      liquidationRisk: status.liquidatable ? 'HIGH' : 'LOW',
      isLiquidatable: status.liquidatable,
      recommendation: status.liquidatable
        ? 'Immediate action required: Add margin or close positions'
        : 'Positions are within safe margins',
      lastChecked: new Date().toISOString()
    };
  } catch (error) {
    return {
      status: 'error',
      error: error.message
    };
  }
}

// Usage
const dashboard = await getRiskDashboard('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
console.log('Risk Dashboard:', dashboard);

4. Pre-Trade Risk Check

Check liquidation risk before opening new positions:

JavaScript
async function preTradeRiskCheck(userAddress) {
  const status = await checkLiquidatable(userAddress);

  if (status.liquidatable) {
    return {
      canTrade: false,
      reason: 'Existing positions are liquidatable',
      recommendation: 'Resolve liquidation risk before opening new positions'
    };
  }

  return {
    canTrade: true,
    reason: 'Account health is good',
    recommendation: 'Safe to proceed with new trades'
  };
}

// Usage
const riskCheck = await preTradeRiskCheck('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
if (riskCheck.canTrade) {
  console.log('✓ Safe to open new positions');
} else {
  console.error(`✗ Cannot trade: ${riskCheck.reason}`);
}

5. Continuous Risk Monitoring

Monitor risk with logging:

JavaScript
async function continuousRiskMonitoring(userAddress, logInterval = 60000) {
  const riskLog = [];

  const monitor = async () => {
    const status = await checkLiquidatable(userAddress);

    const logEntry = {
      timestamp: new Date().toISOString(),
      liquidatable: status.liquidatable,
      riskLevel: status.liquidatable ? 'CRITICAL' : 'SAFE'
    };

    riskLog.push(logEntry);
    console.log(`[${logEntry.timestamp}] Risk: ${logEntry.riskLevel}`);

    if (status.liquidatable) {
      console.error('⚠️  ALERT: Liquidation risk detected!');
    }
  };

  // Run immediately and then at intervals
  await monitor();
  setInterval(monitor, logInterval);

  return riskLog;
}

// Usage
const riskLog = await continuousRiskMonitoring(
  '0x420a4ed7b6bb361da586868adec2f2bb9ab75e66',
  60000 // Check every minute
);

Best Practices

  1. Check frequently — Monitor every 30-60 seconds for active positions
  2. Set up alerts — Implement immediate notifications for liquidation risk
  3. Act quickly — Respond immediately when positions become liquidatable
  4. Combine with margin data — Use with clearinghouseState for full context
  5. Log history — Track risk over time for pattern analysis

Performance Considerations

Efficient Risk Monitoring

JavaScript
class EfficientRiskMonitor {
  constructor(userAddress) {
    this.userAddress = userAddress;
    this.cache = null;
    this.cacheTime = 0;
    this.cacheDuration = 10000; // 10 seconds
  }

  async check(forceRefresh = false) {
    const now = Date.now();

    if (!forceRefresh && this.cache && (now - this.cacheTime) < this.cacheDuration) {
      return this.cache;
    }

    const status = await checkLiquidatable(this.userAddress);
    this.cache = status;
    this.cacheTime = now;

    return status;
  }
}
  • clearinghouseState — Get detailed margin and position data
  • openOrders — View orders that may affect liquidation risk
  • userFees — Understand fee impact on margin
  • meta — Get liquidation price calculations

Protect your positions with real-time liquidation monitoring via Dwellir's HyperCore Info Endpoint. Get your API key →