Liquidation-Price Calculation

Install and import#

npm install fintech-algorithms

import { liquidationPrice } from "fintech-algorithms/digital-assets-and-on-chain-finance/liquidity-and-liquidation/liquidation-price-calculation";

Signature#

liquidationPrice(data, config)

The collateral price at which a position becomes liquidatable. The number a borrower actually needs — a health factor is abstract, a price is something you can set an alert on.

Parameters#

Returns#

{ status, value, components, diagnostics }

The result with every component, so a position's state can be reconciled against the protocol's own interface.

Errors#

• When a required protocol parameter is missing — reported as a status rather than thrown

Complexity: time O(assets), space O(assets).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

{
  "collateral": [
    {
      "asset": "WETH",
      "quantity": 2,
      "price": 2000,
      "liquidation_threshold": 0.8,
      "eligible": true
    }
  ],
  "debts": [
    {
      "asset": "USDC",
      "quantity": 2500,
      "price": 1
    }
  ],
  "selected_asset": "WETH"
}

{
  "debt_multiplier": 1,
  "threshold_shift": 0
}

Call#

liquidationPrice(data, config)

Returns#

object with 11 fields: selected_asset, selected_quantity, current_selected_price, effective_selected_liquidation_threshold, total_debt_value, other_adjusted_collateral_value, liquidation_price, distance_to_liquidation_fraction, …

{
  "selected_asset": "WETH",
  "selected_quantity": 2,
  "current_selected_price": 2000,
  "effective_selected_liquidation_threshold": 0.8,
  "total_debt_value": 2500,
  "other_adjusted_collateral_value": 0,
  "liquidation_price": 1562.5,
  "distance_to_liquidation_fraction": 0.21875,
  "current_health_factor": 1.28,
  "reason": "finite break-even price",
  "trace": [
    {
      "price_multiplier": 0.4,
      "selected_price": 800,
      "health_factor": 0.512
    },
    {
      "price_multiplier": 0.4041666667,
      "selected_price": 808.3333333333,
      "health_factor": 0.5173333333
    },
    {
      "price_multiplier": 0.4083333333,
      "selected_price": 816.6666666667,
      "health_factor": 0.5226666667
    }
  ]
}

Other exports#

This module also exports impermanentLoss, feeApr, healthFactor, liquidationWaterfall, runTopic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Calculation flow#

flowchart LR
    A["Identify protocol, version, chain, and valuation time"] --> B["Validate finite inputs and common units"]
    B --> C["Set health factor to one and solve selected price"]
    C --> D["Return value plus state/reason"]
    D --> E["Check equality, zero, and unsupported states"]
    E --> F["Compare sensitivity profiles"]
    F --> G{"Operational evidence complete?"}
    G -->|No| H["Keep as synthetic or descriptive calculation"]
    G -->|Yes| I["Add live source, oracle, execution, and finality controls"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Health Factor & Liquidations — Aave; Aave Labs documentation team
• Aave V3 Risk Parameters — Aave; Aave risk contributors
• Aave V3 LiquidationLogic.sol — Aave; Aave protocol contributors
• Evidence boundary

The rest of the Liquidity and Liquidation family#

• Impermanent-Loss CalculationValue lost by providing liquidity rather than simply holding the two assets.
• Liquidity-Provider Fee APRAnnualised fee return for a liquidity position.
• Collateral-Health FactorThe ratio of weighted collateral to debt in a lending position.
• Liquidation WaterfallThe order in which collateral is seized and debt repaid, including liquidation bonus and any protocol fee.