Margin Calculations

Functions for calculating margin requirements, collateral values, and liquidation prices

The margin calculation utilities provide functions for determining margin requirements, calculating collateral values, and computing liquidation prices for positions.

Margin Weight Functions

calculateSizePremiumLiabilityWeight

Calculates the size-adjusted liability weight for a position.

calculateSizePremiumLiabilityWeight(
  size: BN,
  imfFactor: BN,
  liabilityWeight: BN,
  precision: BN,
  isBounded?: boolean
): BN

size · BN · required

Position size in AMM_RESERVE_PRECISION

imfFactor · BN · required

Initial margin fraction factor

liabilityWeight · BN · required

Base liability weight

precision · BN · required

Precision to use for calculations

isBounded · boolean · default: "true"

Whether to bound the result to the base liability weight

return · BN

Size-adjusted liability weight

Usage Example

import { calculateSizePremiumLiabilityWeight } from '@drift-labs/sdk';
import { AMM_RESERVE_PRECISION } from '@drift-labs/sdk';

const size = new BN(1000).mul(AMM_RESERVE_PRECISION);
const imfFactor = market.imfFactor;
const liabilityWeight = market.marginRatioInitial;

const adjustedWeight = calculateSizePremiumLiabilityWeight(
  size,
  imfFactor,
  liabilityWeight,
  AMM_RESERVE_PRECISION,
  true
);

calculateSizeDiscountAssetWeight

Calculates the size-adjusted asset weight for a position.

calculateSizeDiscountAssetWeight(
  size: BN,
  imfFactor: BN,
  assetWeight: BN
): BN

size · BN · required

Position size in AMM_RESERVE_PRECISION

imfFactor · BN · required

Initial margin fraction factor

assetWeight · BN · required

Base asset weight

return · BN

Size-adjusted asset weight (minimum of base weight and calculated discount weight)

Oracle Price Functions

calculateOraclePriceForPerpMargin

Calculates the oracle price adjusted for margin calculations with spread and confidence intervals.

calculateOraclePriceForPerpMargin(
  perpPosition: PerpPosition,
  market: PerpMarketAccount,
  oraclePriceData: OraclePriceData
): BN

perpPosition · PerpPosition · required

The perpetual position

market · PerpMarketAccount · required

The perpetual market account

oraclePriceData · OraclePriceData · required

Oracle price data including confidence interval

return · BN

Adjusted oracle price for margin calculations

Usage Example

import { calculateOraclePriceForPerpMargin } from '@drift-labs/sdk';

const position = user.getPerpPosition(0);
const market = driftClient.getPerpMarketAccount(0);
const oracleData = driftClient.getOracleDataForPerpMarket(0);

const marginPrice = calculateOraclePriceForPerpMargin(
  position,
  market,
  oracleData
);

console.log('Margin price:', convertToNumber(marginPrice, PRICE_PRECISION));

Base Asset Value Functions

calculateBaseAssetValueWithOracle

Calculates the base asset value using oracle price. For prediction markets, this differs from liability value.

calculateBaseAssetValueWithOracle(
  market: PerpMarketAccount,
  perpPosition: PerpPosition,
  oraclePriceData: Pick<OraclePriceData, 'price'>,
  includeOpenOrders?: boolean
): BN

market · PerpMarketAccount · required

The perpetual market account

perpPosition · PerpPosition · required

The perpetual position

oraclePriceData · Pick<OraclePriceData, 'price'> · required

Oracle price data

includeOpenOrders · boolean · default: "false"

Whether to include open orders in calculation

return · BN

Base asset value in quote precision

Usage Example

import { calculateBaseAssetValueWithOracle } from '@drift-labs/sdk';

const market = driftClient.getPerpMarketAccount(0);
const position = user.getPerpPosition(0);
const oracleData = driftClient.getOracleDataForPerpMarket(0);

// Without open orders
const value = calculateBaseAssetValueWithOracle(
  market,
  position,
  oracleData
);

// With open orders
const worstCaseValue = calculateBaseAssetValueWithOracle(
  market,
  position,
  oracleData,
  true
);

calculateWorstCaseBaseAssetAmount

Calculates the worst-case base asset amount including open orders.

calculateWorstCaseBaseAssetAmount(
  perpPosition: PerpPosition,
  perpMarket: PerpMarketAccount,
  oraclePrice: BN
): BN

perpPosition · PerpPosition · required

The perpetual position

perpMarket · PerpMarketAccount · required

The perpetual market account

oraclePrice · BN · required

Oracle price

return · BN

Worst-case base asset amount

calculateWorstCasePerpLiabilityValue

Calculates the worst-case liability value for a position.

calculateWorstCasePerpLiabilityValue(
  perpPosition: PerpPosition,
  perpMarket: PerpMarketAccount,
  oraclePrice: BN,
  includeOpenOrders?: boolean
): { worstCaseBaseAssetAmount: BN; worstCaseLiabilityValue: BN }

perpPosition · PerpPosition · required

The perpetual position

perpMarket · PerpMarketAccount · required

The perpetual market account

oraclePrice · BN · required

Oracle price

includeOpenOrders · boolean · default: "true"

Whether to include open orders

return · { worstCaseBaseAssetAmount: BN; worstCaseLiabilityValue: BN }

Object containing worst-case base asset amount and liability value

calculatePerpLiabilityValue

Calculates the liability value for a given base asset amount.

calculatePerpLiabilityValue(
  baseAssetAmount: BN,
  price: BN,
  isPredictionMarket: boolean
): BN

baseAssetAmount · BN · required

Base asset amount

price · BN · required

Oracle price

isPredictionMarket · boolean · required

Whether this is a prediction market

return · BN

Liability value. For prediction markets, shorts use (1 - price) * base

Margin Requirement Functions

calculateMarginUSDCRequiredForTrade

Calculates the margin required to open a trade in USDC.

calculateMarginUSDCRequiredForTrade(
  driftClient: DriftClient,
  targetMarketIndex: number,
  baseSize: BN,
  userMaxMarginRatio?: number,
  userHighLeverageMode?: boolean,
  entryPrice?: BN
): BN

driftClient · DriftClient · required

The Drift client instance

targetMarketIndex · number · required

Market index for the trade

baseSize · BN · required

Size of the trade

userMaxMarginRatio · number

User’s maximum margin ratio

userHighLeverageMode · boolean

Whether user is in high leverage mode

entryPrice · BN

Expected entry price (uses oracle price if not provided)

return · BN

Margin required in USDC

Usage Example

import { calculateMarginUSDCRequiredForTrade } from '@drift-labs/sdk';
import { BASE_PRECISION } from '@drift-labs/sdk';

const marketIndex = 0; // SOL-PERP
const baseSize = new BN(10).mul(BASE_PRECISION); // 10 SOL

const marginRequired = calculateMarginUSDCRequiredForTrade(
  driftClient,
  marketIndex,
  baseSize
);

console.log('Margin required:', convertToNumber(marginRequired, QUOTE_PRECISION), 'USDC');

calculateCollateralDepositRequiredForTrade

Calculates the collateral deposit required for a trade in a specific collateral asset.

calculateCollateralDepositRequiredForTrade(
  driftClient: DriftClient,
  targetMarketIndex: number,
  baseSize: BN,
  collateralIndex: number,
  userMaxMarginRatio?: number,
  userHighLeverageMode?: boolean,
  estEntryPrice?: BN
): BN

driftClient · DriftClient · required

The Drift client instance

targetMarketIndex · number · required

Market index for the trade

baseSize · BN · required

Size of the trade

collateralIndex · number · required

Spot market index for the collateral asset

userMaxMarginRatio · number

User’s maximum margin ratio

userHighLeverageMode · boolean

Whether user is in high leverage mode

estEntryPrice · BN

Estimated entry price

return · BN

Collateral required in the precision of the target collateral market

calculateCollateralValueOfDeposit

Calculates the collateral value of a deposit.

calculateCollateralValueOfDeposit(
  driftClient: DriftClient,
  collateralIndex: number,
  baseSize: BN
): BN

driftClient · DriftClient · required

The Drift client instance

collateralIndex · number · required

Spot market index for the collateral

baseSize · BN · required

Amount to deposit in base units

return · BN

Collateral value in QUOTE_PRECISION

Liquidation Price Functions

calculateLiquidationPrice

Calculates the liquidation price for a position.

calculateLiquidationPrice(
  freeCollateral: BN,
  freeCollateralDelta: BN,
  oraclePrice: BN
): BN

freeCollateral · BN · required

Current free collateral

freeCollateralDelta · BN · required

Change in free collateral per price change

oraclePrice · BN · required

Current oracle price

return · BN

Liquidation price. Returns -1 if calculated price is negative

Usage Example

import { calculateLiquidationPrice } from '@drift-labs/sdk';

const freeCollateral = user.getFreeCollateral();
const freeCollateralDelta = calculateFreeCollateralDelta(user, position);
const oraclePrice = driftClient.getOracleDataForPerpMarket(0).price;

const liqPrice = calculateLiquidationPrice(
  freeCollateral,
  freeCollateralDelta,
  oraclePrice
);

if (liqPrice.gt(new BN(0))) {
  console.log('Liquidation price:', convertToNumber(liqPrice, PRICE_PRECISION));
} else {
  console.log('No liquidation risk');
}

User Position Functions

calculateUserMaxPerpOrderSize

Calculates the maximum order size a user can place.

calculateUserMaxPerpOrderSize(
  driftClient: DriftClient,
  userAccountKey: PublicKey,
  userAccount: UserAccount,
  targetMarketIndex: number,
  tradeSide: PositionDirection
): { tradeSize: BN; oppositeSideTradeSize: BN }

driftClient · DriftClient · required

The Drift client instance

userAccountKey · PublicKey · required

User account public key

userAccount · UserAccount · required

User account data

targetMarketIndex · number · required

Market index for the trade

tradeSide · PositionDirection · required

Direction of the trade (LONG or SHORT)

return · { tradeSize: BN; oppositeSideTradeSize: BN }

Object containing max trade size for requested side and opposite side

calcHighLeverageModeInitialMarginRatioFromSize

Calculates the initial margin ratio for high leverage mode based on position size.

calcHighLeverageModeInitialMarginRatioFromSize(
  preSizeAdjMarginRatio: BN,
  sizeAdjMarginRatio: BN,
  defaultMarginRatio: BN
): BN

preSizeAdjMarginRatio · BN · required

Margin ratio before size adjustment

sizeAdjMarginRatio · BN · required

Size-adjusted margin ratio

defaultMarginRatio · BN · required

Default margin ratio for the market

return · BN

Calculated initial margin ratio for high leverage mode