Skip to main content

positions

This module provides utilities for working with trading positions in the GMX protocol. It includes functions for calculating position metrics, PnL, liquidation prices, leverage, and managing position keys.

Methods​

getPositionKey​

  • getPositionKey(account: string, marketAddress: string, collateralAddress: string, isLong: boolean): string

Generates a unique position key from position parameters.

import { getPositionKey } from "@gmx-ui/sdk/utils/positions";

const positionKey = getPositionKey(
  "0x1234567890123456789012345678901234567890",
  "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
  "0xfedcbafedcbafedcbafedcbafedcbafedcbafed",
  true
);
// Returns: "0x1234567890123456789012345678901234567890:0xabcdefabcdefabcdefabcdefabcdefabcdefabcd:0xfedcbafedcbafedcbafedcbafedcbafedcbafed:true"

parsePositionKey​

  • parsePositionKey(positionKey: string): { account: string; marketAddress: string; collateralAddress: string; isLong: boolean }

Parses a position key back into its component parts.

import { parsePositionKey } from "@gmx-ui/sdk/utils/positions";

const parsed = parsePositionKey(
  "0x1234567890123456789012345678901234567890:0xabcdefabcdefabcdefabcdefabcdefabcdefabcd:0xfedcbafedcbafedcbafedcbafedcbafedcbafed:true"
);
// Returns: {
//   account: "0x1234567890123456789012345678901234567890",
//   marketAddress: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
//   collateralAddress: "0xfedcbafedcbafedcbafedcbafedcbafedcbafed",
//   isLong: true
// }

getEntryPrice​

  • getEntryPrice(p: { sizeInUsd: bigint; sizeInTokens: bigint; indexToken: Token }): bigint | undefined

Parameters​

  • p: object - Parameters object containing position size information and index token

Calculates the entry price of a position based on its size in USD and tokens.

import { getEntryPrice } from "@gmx-ui/sdk/utils/positions";

const entryPrice = getEntryPrice({
  sizeInUsd: 1000000000000000000000n, // $1000 in wei
  sizeInTokens: 500000000000000000n, // 0.5 tokens in wei
  indexToken: {
    decimals: 18,
    // ... other token properties
  }
});

getPositionPnlUsd​

  • getPositionPnlUsd(p: { marketInfo: MarketInfo; sizeInUsd: bigint; sizeInTokens: bigint; markPrice: bigint; isLong: boolean }): bigint

Parameters​

  • p: object - Parameters object containing market info, position size, mark price, and direction

Calculates the unrealized PnL of a position in USD, accounting for pool caps.

import { getPositionPnlUsd } from "@gmx-ui/sdk/utils/positions";

const pnl = getPositionPnlUsd({
  marketInfo: marketInfo,
  sizeInUsd: 1000000000000000000000n,
  sizeInTokens: 500000000000000000n,
  markPrice: 2100000000000000000000n,
  isLong: true
});

getPositionValueUsd​

  • getPositionValueUsd(p: { indexToken: Token; sizeInTokens: bigint; markPrice: bigint }): bigint

Parameters​

  • p: object - Parameters object containing index token, position size in tokens, and mark price

Calculates the current USD value of a position based on mark price.

import { getPositionValueUsd } from "@gmx-ui/sdk/utils/positions";

const valueUsd = getPositionValueUsd({
  indexToken: {
    decimals: 18,
    // ... other token properties
  },
  sizeInTokens: 500000000000000000n,
  markPrice: 2100000000000000000000n
});

getPositionPendingFeesUsd​

  • getPositionPendingFeesUsd(p: { pendingFundingFeesUsd: bigint; pendingBorrowingFeesUsd: bigint }): bigint

Parameters​

  • p: object - Parameters object containing pending funding and borrowing fees

Calculates the total pending fees for a position.

import { getPositionPendingFeesUsd } from "@gmx-ui/sdk/utils/positions";

const pendingFees = getPositionPendingFeesUsd({
  pendingFundingFeesUsd: 1000000000000000000n,
  pendingBorrowingFeesUsd: 500000000000000000n
});
// Returns: 1500000000000000000n

getPositionNetValue​

  • getPositionNetValue(p: { totalPendingImpactDeltaUsd: bigint; priceImpactDiffUsd: bigint; collateralUsd: bigint; pendingFundingFeesUsd: bigint; pendingBorrowingFeesUsd: bigint; pnl: bigint; closingFeeUsd: bigint; uiFeeUsd: bigint }): bigint

Parameters​

  • p: object - Parameters object containing all position value components

Calculates the net value of a position after accounting for all fees, PnL, and impacts.

import { getPositionNetValue } from "@gmx-ui/sdk/utils/positions";

const netValue = getPositionNetValue({
  totalPendingImpactDeltaUsd: 0n,
  priceImpactDiffUsd: 0n,
  collateralUsd: 500000000000000000000n,
  pendingFundingFeesUsd: 1000000000000000000n,
  pendingBorrowingFeesUsd: 500000000000000000n,
  pnl: 50000000000000000000n,
  closingFeeUsd: 2000000000000000000n,
  uiFeeUsd: 1000000000000000000n
});

getPositionPnlAfterFees​

  • getPositionPnlAfterFees(params: { pnl: bigint; pendingBorrowingFeesUsd: bigint; pendingFundingFeesUsd: bigint; closingFeeUsd: bigint; uiFeeUsd: bigint; totalPendingImpactDeltaUsd: bigint; priceImpactDiffUsd: bigint }): bigint

Parameters​

  • params: object - Parameters object containing PnL and all fee components

Calculates the position PnL after deducting all fees and impacts.

import { getPositionPnlAfterFees } from "@gmx-ui/sdk/utils/positions";

const pnlAfterFees = getPositionPnlAfterFees({
  pnl: 100000000000000000000n,
  pendingBorrowingFeesUsd: 1000000000000000000n,
  pendingFundingFeesUsd: 500000000000000000n,
  closingFeeUsd: 2000000000000000000n,
  uiFeeUsd: 1000000000000000000n,
  totalPendingImpactDeltaUsd: 0n,
  priceImpactDiffUsd: 0n
});

getLeverage​

  • getLeverage(p: { sizeInUsd: bigint; collateralUsd: bigint; pnl: bigint | undefined; pendingFundingFeesUsd: bigint; pendingBorrowingFeesUsd: bigint }): bigint | undefined

Parameters​

  • p: object - Parameters object containing position size, collateral, PnL, and pending fees

Calculates the current leverage of a position.

import { getLeverage } from "@gmx-ui/sdk/utils/positions";

const leverage = getLeverage({
  sizeInUsd: 1000000000000000000000n,
  collateralUsd: 100000000000000000000n,
  pnl: 10000000000000000000n,
  pendingFundingFeesUsd: 1000000000000000000n,
  pendingBorrowingFeesUsd: 500000000000000000n
});

getLiquidationPrice​

  • getLiquidationPrice(p: { sizeInUsd: bigint; sizeInTokens: bigint; collateralAmount: bigint; collateralUsd: bigint; collateralToken: TokenData; marketInfo: MarketInfo; pendingFundingFeesUsd: bigint; pendingBorrowingFeesUsd: bigint; pendingImpactAmount: bigint; minCollateralUsd: bigint; isLong: boolean; useMaxPriceImpact?: boolean; userReferralInfo: UserReferralInfo | undefined }): bigint | undefined

Parameters​

  • p: object - Parameters object containing position details, market info, fees, and configuration

Calculates the liquidation price for a position.

import { getLiquidationPrice } from "@gmx-ui/sdk/utils/positions";

const liquidationPrice = getLiquidationPrice({
  sizeInUsd: 1000000000000000000000n,
  sizeInTokens: 500000000000000000n,
  collateralAmount: 50000000000000000000n,
  collateralUsd: 100000000000000000000n,
  collateralToken: tokenData,
  marketInfo: marketInfo,
  pendingFundingFeesUsd: 1000000000000000000n,
  pendingBorrowingFeesUsd: 500000000000000000n,
  pendingImpactAmount: 0n,
  minCollateralUsd: 10000000000000000000n,
  isLong: true,
  useMaxPriceImpact: false,
  userReferralInfo: undefined
});

getNetPriceImpactDeltaUsdForDecrease​

  • getNetPriceImpactDeltaUsdForDecrease(params: { marketInfo: MarketInfo; sizeInUsd: bigint; pendingImpactAmount: bigint; priceImpactDeltaUsd: bigint; sizeDeltaUsd: bigint }): { totalImpactDeltaUsd: bigint; proportionalPendingImpactDeltaUsd: bigint; priceImpactDiffUsd: bigint }

Parameters​

  • params: object - Parameters object containing market info, position size, pending impact, and price impact delta

Calculates the net price impact for decreasing a position.

import { getNetPriceImpactDeltaUsdForDecrease } from "@gmx-ui/sdk/utils/positions";

const impactResult = getNetPriceImpactDeltaUsdForDecrease({
  marketInfo: marketInfo,
  sizeInUsd: 1000000000000000000000n,
  pendingImpactAmount: 0n,
  priceImpactDeltaUsd: -5000000000000000000n,
  sizeDeltaUsd: 500000000000000000000n
});

getPriceImpactDiffUsd​

  • getPriceImpactDiffUsd(params: { totalImpactDeltaUsd: bigint; marketInfo: MarketInfo; sizeDeltaUsd: bigint }): bigint

Parameters​

  • params: object - Parameters object containing total impact delta, market info, and size delta

Calculates the price impact difference based on maximum negative impact limits.

import { getPriceImpactDiffUsd } from "@gmx-ui/sdk/utils/positions";

const priceImpactDiff = getPriceImpactDiffUsd({
  totalImpactDeltaUsd: -10000000000000000000n,
  marketInfo: marketInfo,
  sizeDeltaUsd: 500000000000000000000n
});

getMinCollateralFactorForPosition​

  • getMinCollateralFactorForPosition(position: PositionInfoLoaded, openInterestDelta: bigint): bigint

Parameters​

  • position: PositionInfoLoaded - The loaded position information
  • openInterestDelta: bigint - Change in open interest

Calculates the minimum collateral factor required for a position based on open interest.

import { getMinCollateralFactorForPosition } from "@gmx-ui/sdk/utils/positions";

const minCollateralFactor = getMinCollateralFactorForPosition(
  positionInfo,
  100000000000000000000n
);