Overview
The position management module provides functions for calculating position metrics, unrealized PnL, funding payments, and other position-related data.
Position Calculation Functions
calculatePositionPNL
Calculates the unrealized PnL for a perpetual position.
Formula: BaseAssetAmount × (Avg Exit Price - Avg Entry Price)
import { calculatePositionPNL } from '@drift-labs/sdk';
const pnl = calculatePositionPNL(
perpMarket,
perpPosition,
true, // include funding
oraclePriceData
);
console.log('Position PnL:', pnl.toString());
market
PerpMarketAccount
required
The perpetual market account.
The user’s perpetual position.
Whether to include unrealized funding payment PnL in the result.
Oracle price data containing the current price.
calculateBaseAssetValue
Calculates the market value of closing the entire position.
import { calculateBaseAssetValue } from '@drift-labs/sdk';
const positionValue = calculateBaseAssetValue(
perpMarket,
perpPosition,
mmOraclePriceData,
true, // use spread
false, // don't skip AMM update
latestSlot
);
market
PerpMarketAccount
required
The perpetual market account.
mmOraclePriceData
MMOraclePriceData
required
Market maker oracle price data.
Whether to apply AMM spread to the calculation.
Whether to skip AMM updates before calculation.
Latest slot for accurate AMM state.
calculateClaimablePnl
Calculates the claimable (settleable) PnL for a position, accounting for pool limitations.
import { calculateClaimablePnl } from '@drift-labs/sdk';
const claimable = calculateClaimablePnl(
perpMarket,
spotMarket, // quote spot market
perpPosition,
oraclePriceData
);
market
PerpMarketAccount
required
The perpetual market account.
spotMarket
SpotMarketAccount
required
The quote spot market account (usually USDC).
The user’s perpetual position.
Funding Calculations
calculateUnsettledFundingPnl
Calculates the unsettled funding payment PnL for a position.
import { calculateUnsettledFundingPnl } from '@drift-labs/sdk';
const fundingPnl = calculateUnsettledFundingPnl(
perpMarket,
perpPosition
);
console.log('Unsettled funding:', fundingPnl.toString());
market
PerpMarketAccount
required
The perpetual market account.
The user’s perpetual position.
calculateFeesAndFundingPnl
Returns total fees and funding PnL for a position.
import { calculateFeesAndFundingPnl } from '@drift-labs/sdk';
const totalFeesFunding = calculateFeesAndFundingPnl(
perpMarket,
perpPosition,
true // include unsettled funding
);
market
PerpMarketAccount
required
The perpetual market account.
The user’s perpetual position.
Whether to include unsettled funding in the result.
Price Calculations
calculateBreakEvenPrice
Calculates the break-even price for a position (entry price + fees + funding).
import { calculateBreakEvenPrice } from '@drift-labs/sdk';
const breakEven = calculateBreakEvenPrice(perpPosition);
console.log('Break-even price:', breakEven.toString());
The user’s perpetual position.
calculateEntryPrice
Calculates the average entry price for a position.
import { calculateEntryPrice } from '@drift-labs/sdk';
const entryPrice = calculateEntryPrice(perpPosition);
console.log('Entry price:', entryPrice.toString());
The user’s perpetual position.
calculateCostBasis
Calculates the cost basis of a position.
import { calculateCostBasis } from '@drift-labs/sdk';
const costBasis = calculateCostBasis(
perpPosition,
true // include settled PnL
);
The user’s perpetual position.
Whether to include settled PnL in the calculation.
Position State Functions
findDirectionToClose
Determines the direction needed to close a position.
import { findDirectionToClose, PositionDirection } from '@drift-labs/sdk';
const closeDirection = findDirectionToClose(perpPosition);
// Returns PositionDirection.SHORT for long positions
// Returns PositionDirection.LONG for short positions
The user’s perpetual position.
positionCurrentDirection
Returns the current direction of a position.
import { positionCurrentDirection } from '@drift-labs/sdk';
const direction = positionCurrentDirection(perpPosition);
The user’s perpetual position.
positionIsAvailable
Checks if a position slot is available (no position or orders).
import { positionIsAvailable } from '@drift-labs/sdk';
const isAvailable = positionIsAvailable(perpPosition);
if (isAvailable) {
console.log('Position slot is available');
}
The perpetual position to check.
positionIsBeingLiquidated
Checks if a position is currently being liquidated.
import { positionIsBeingLiquidated } from '@drift-labs/sdk';
const isLiquidating = positionIsBeingLiquidated(perpPosition);
if (isLiquidating) {
console.log('Position is being liquidated!');
}
The perpetual position to check.
isEmptyPosition
Checks if a position is empty (no base asset and no open orders).
import { isEmptyPosition } from '@drift-labs/sdk';
const isEmpty = isEmptyPosition(perpPosition);
The user’s perpetual position.
hasOpenOrders
Checks if a position has any open orders.
import { hasOpenOrders } from '@drift-labs/sdk';
const hasOrders = hasOpenOrders(perpPosition);
if (hasOrders) {
console.log('Position has open orders');
}
PerpPosition Type
The PerpPosition type contains all data for a perpetual position:
Current base asset amount held (positive for long, negative for short).
lastCumulativeFundingRate
Last cumulative funding rate when position was updated.
Index of the perpetual market.
Current quote asset amount (cost basis).
Quote amount at entry (before fees and funding).
Quote amount including fees and funding (break-even point).
Number of open orders for this position.
Total size of open bid orders.
Total size of open ask orders.
Settled PnL for this position.
LP shares if user is providing liquidity.
Maximum margin ratio for this position.
lastQuoteAssetAmountPerLp
Last quote asset amount per LP share.
Position status flags.PositionFlag values:
PositionFlag.IsolatedPosition (1) - Isolated margin positionPositionFlag.BeingLiquidated (2) - Position is being liquidatedPositionFlag.Bankruptcy (4) - Position is bankrupt
isolatedPositionScaledBalance
Scaled balance for isolated positions.
Example: Position Dashboard
import {
calculatePositionPNL,
calculateBreakEvenPrice,
calculateEntryPrice,
calculateUnsettledFundingPnl,
convertToNumber,
PRICE_PRECISION,
QUOTE_PRECISION,
} from '@drift-labs/sdk';
function displayPositionMetrics(
perpMarket: PerpMarketAccount,
position: PerpPosition,
oraclePriceData: OraclePriceData
) {
const pnl = calculatePositionPNL(
perpMarket,
position,
true,
oraclePriceData
);
const entryPrice = calculateEntryPrice(position);
const breakEvenPrice = calculateBreakEvenPrice(position);
const fundingPnl = calculateUnsettledFundingPnl(perpMarket, position);
console.log('Position Metrics:');
console.log(' Entry Price:', convertToNumber(entryPrice, PRICE_PRECISION));
console.log(' Break-Even:', convertToNumber(breakEvenPrice, PRICE_PRECISION));
console.log(' Unrealized PnL:', convertToNumber(pnl, QUOTE_PRECISION));
console.log(' Funding PnL:', convertToNumber(fundingPnl, QUOTE_PRECISION));
console.log(' Position Size:', position.baseAssetAmount.toString());
}
See Also
- OrderParams - Configure and place orders
- DLOB - Decentralized Limit Order Book