The math behind a liquidation price calculator, in TypeScript

#typescript #javascript #webdev #tutorial

Most leverage calculators hide one small piece of algebra. Here it is, derived step by step, with a TypeScript function you can paste into a project.

Disclosure: I am the founder of copy.top. We publish a free leverage and liquidation calculator, and this post explains the math behind that kind of tool. The code below is a minimal version written for this article.

The setup

You post some margin, choose a leverage, and open a position at an entry price.

Position size in quote currency: notional = margin * leverage
Position size in coins: quantity = notional / entry

The exchange closes the position when your equity falls to the maintenance requirement. For an isolated position, with a maintenance margin rate m:

Equity at price P, long: margin + quantity * (P - entry)
Maintenance requirement at price P: m * quantity * P

Solving for the liquidation price

Set equity equal to the requirement for a long:

margin + quantity * (P - entry) = m * quantity * P

Divide by quantity and use margin / quantity = entry / leverage:

entry / leverage + P - entry = m * P
P * (1 - m) = entry * (1 - 1 / leverage)
P = entry * (1 - 1 / leverage) / (1 - m)

For a short the signs flip:

P = entry * (1 + 1 / leverage) / (1 + m)

Both cases fit in one formula with a direction of +1 for a long and -1 for a short.

The code

type Side = "long" | "short";

interface LeverageInput {
  margin: number;      // collateral you post, in quote currency
  leverage: number;    // 1 or more
  entry: number;       // entry price
  side: Side;
  maintenance: number; // maintenance margin rate, for example 0.005
}

interface LeverageResult {
  notional: number;    // position size in quote currency
  quantity: number;    // position size in coins
  liquidation: number; // estimated liquidation price
  pnlAt: (exit: number) => number;
}

export function leverage(i: LeverageInput): LeverageResult {
  if (i.margin <= 0 || i.entry <= 0) {
    throw new RangeError("margin and entry must be positive");
  }
  if (i.leverage < 1) {
    throw new RangeError("leverage must be 1 or more");
  }
  if (i.maintenance < 0 || i.maintenance >= 1 / i.leverage) {
    throw new RangeError("maintenance rate must be below 1 / leverage");
  }

  const notional = i.margin * i.leverage;
  const quantity = notional / i.entry;
  const dir = i.side === "long" ? 1 : -1;
  const liquidation =
    (i.entry * (1 - dir / i.leverage)) / (1 - dir * i.maintenance);

  return {
    notional,
    quantity,
    liquidation,
    pnlAt: (exit) => dir * quantity * (exit - i.entry),
  };
}

A worked example

const r = leverage({
  margin: 100,
  leverage: 10,
  entry: 2,
  side: "long",
  maintenance: 0.005,
});

r.notional;    // 1000
r.quantity;    // 500
r.liquidation; // 1.809045...
r.pnlAt(2.1);  // 50 (floating point gives 50.00000000000004)

The same inputs as a short give a liquidation price of about 2.189.

A quick way to test the function: at the liquidation price, margin + pnlAt(liquidation) must equal maintenance * quantity * liquidation. Here both sides are about 4.52.

Three things the formula ignores

Fees and funding. Both reduce equity over time, so the real liquidation price is closer to your entry than the estimate.
Cross margin. With cross margin the whole account backs the position, and the answer depends on your other positions.
Tiered maintenance rates. Many venues raise the maintenance rate with position size. A single m is an approximation.

That is why a calculator should label the result as an estimate.

Why the validation line matters

maintenance >= 1 / leverage means the position would be liquidated the moment it opens. Without that check the function returns a liquidation price on the wrong side of the entry, and a UI would show it as if it were valid. Reject it early.

If you only need the numbers, the hosted version is here, free and with no sign up. Leverage multiplies losses as well as gains, and nothing here is financial advice.

DEV Community