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
Position size in AMM_RESERVE_PRECISION
Initial margin fraction factor
Precision to use for calculations
Whether to bound the result to the base liability weight
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
Position size in AMM_RESERVE_PRECISION
Initial margin fraction factor
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
market
PerpMarketAccount
required
The perpetual market account
Oracle price data including confidence interval
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
oraclePriceData
Pick<OraclePriceData, 'price'>
required
Oracle price data
Whether to include open orders in calculation
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
perpMarket
PerpMarketAccount
required
The perpetual market account
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 }
perpMarket
PerpMarketAccount
required
The perpetual market account
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
Whether this is a prediction market
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
The Drift client instance
Market index for the trade
User’s maximum margin ratio
Whether user is in high leverage mode
Expected entry price (uses oracle price if not provided)
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
The Drift client instance
Market index for the trade
Spot market index for the collateral asset
User’s maximum margin ratio
Whether user is in high leverage mode
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
The Drift client instance
Spot market index for the collateral
Amount to deposit in base units
Collateral value in QUOTE_PRECISION
Liquidation Price Functions
calculateLiquidationPrice
Calculates the liquidation price for a position.
calculateLiquidationPrice(
freeCollateral: BN,
freeCollateralDelta: BN,
oraclePrice: BN
): BN
Change in free collateral per price change
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 }
The Drift client instance
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
Margin ratio before size adjustment
Size-adjusted margin ratio
Default margin ratio for the market
Calculated initial margin ratio for high leverage mode