Skip to main content

liquidatable

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

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

Request#

Endpoint#

POST https://api-hyperliquid-mainnet-info.n.dwellir.com/info

Headers#

HeaderValueRequired
Content-Typeapplication/jsonYes
X-Api-KeyYour API keyYes

Parameters#

ParameterTypeRequiredDescription
typestringYesMust be "liquidatable"
userstringYesUser's Ethereum wallet address

Example Request#

{
  "type": "liquidatable",
  "user": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66"
}

Response#

Success Response#

Returns liquidation status for the user's positions.

{
  "liquidatable": false
}

Response Fields#

FieldTypeDescription
liquidatablebooleanWhether the user's positions are currently liquidatable

Code Examples#

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "liquidatable",
    "user": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66"
  }'

Common Use Cases#

1. Liquidation Risk Monitor#

Monitor liquidation risk continuously:

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:

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:

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:

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:

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
);

Error Handling#

Common Errors#

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify your API key is correct
400 Bad RequestMissing or invalid user addressEnsure valid Ethereum address format
429 Too Many RequestsRate limit exceededImplement request throttling
500 Internal Server ErrorServer issueRetry with exponential backoff

Error Response Example#

{
  "error": "Missing required parameter: user",
  "code": "MISSING_PARAMETER"
}

Robust Error Handling#

async function safeCheckLiquidatable(userAddress, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await checkLiquidatable(userAddress);
    } catch (error) {
      if (error.response?.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else if (error.response?.status === 400) {
        throw new Error('Invalid user address');
      } else if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

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#

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 →