fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Impermanent-Loss Calculation

Install and import#

bash
npm install fintech-algorithms
ts
import { impermanentLoss } from "fintech-algorithms/digital-assets-and-on-chain-finance/liquidity-and-liquidation/impermanent-loss-calculation";

Signature#

impermanentLoss(data, config)

Value lost by providing liquidity rather than simply holding the two assets. Called impermanent because it reverses if the price returns — which it frequently does not, and the loss is realised on withdrawal.

Parameters#

NameTypeNotes
dataPositionInputPosition state — balances, prices, and the protocol parameters the calculation depends on.
configProtocolConfigProtocol-specific thresholds and factors. These differ per protocol and per asset, so a figure computed under the wrong config is confidently wrong.

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#

data
{
  "initial_pool_value": 10000,
  "price_ratio": 2
}
config
{
  "fee_return_fraction": 0
}

Call#

impermanentLoss(data, config)

Returns#

object with 10 fields: initial_pool_value, price_ratio, hold_value, pool_value_excluding_fees, impermanent_loss_fraction, impermanent_loss_amount, fee_income, net_pool_value, …

{
  "initial_pool_value": 10000,
  "price_ratio": 2,
  "hold_value": 15000,
  "pool_value_excluding_fees": 14142.135623731,
  "impermanent_loss_fraction": -0.0571909584,
  "impermanent_loss_amount": -857.864376269,
  "fee_income": 0,
  "net_pool_value": 14142.135623731,
  "net_vs_hold_fraction": -0.0571909584,
  "trace": [
    {
      "price_ratio": 0.2,
      "impermanent_loss": -0.2546440075,
      "hold_value": 6000,
      "pool_value": 4472.1359549996,
      "net_pool_value": 4472.1359549996
    },
    {
      "price_ratio": 0.2027004653,
      "impermanent_loss": -0.2513136942,
      "hold_value": 6013.5023266882,
      "pool_value": 4502.2268416601,
      "net_pool_value": 4502.2268416601
    },
    {
      "price_ratio": 0.2054373932,
      "impermanent_loss": -0.2479874573,
      "hold_value": 6027.1869662025,
      "pool_value": 4532.5201956582,
      "net_pool_value": 4532.5201956582
    }
  ]
}

Other exports#

This module also exports feeApr, healthFactor, liquidationPrice, 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#

Impermanent-Loss Calculation — boundary audit
Impermanent-Loss Calculation — calculation map
Impermanent-Loss Calculation — diagnostic deep dive
Impermanent-Loss Calculation — family handoff
Impermanent-Loss Calculation — parameter sensitivity
Impermanent-Loss Calculation — scenario suite

Calculation flow#

Impermanent-Loss Calculation — Calculation and Decision Flow 
flowchart LR
    A["Identify protocol, version, chain, and valuation time"] --> B["Validate finite inputs and common units"]
    B --> C["Compare constant-product LP value with initial-token hold"]
    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#

The rest of the Liquidity and Liquidation family#