fees

This module provides utilities for calculating various fees in the GMX protocol, including swap fees, position fees, funding fees, borrowing fees, and price impact calculations. It also includes helper functions for working with fee items and swap statistics.

Methods

The fees module exports fee calculation functions for three categories of on-chain costs: swap fees, position fees (including referral discounts), and holding costs (funding fee and borrow fee). It also exports helper utilities for working with FeeItem objects.

Swap and position fees

getSwapFee

getSwapFee(
  marketInfo: MarketInfo,
  swapAmount: bigint,
  balanceWasImproved: boolean,
  swapPricingType: SwapPricingType
): bigint

Calculates the swap fee for a token amount. The fee factor depends on swapPricingType:

• SwapPricingType.AtomicSwap — uses atomicSwapFeeFactor
• SwapPricingType.Withdrawal — uses withdrawalFeeFactorBalanceWasImproved or withdrawalFeeFactorBalanceWasNotImproved
• All other types (standard swaps) — uses swapFeeFactorForBalanceWasImproved or swapFeeFactorForBalanceWasNotImproved

note

The fourth parameter is swapPricingType: SwapPricingType (an enum), not isAtomicSwap: boolean as earlier documentation stated.

import { getSwapFee } from "@gmx-io/sdk/utils/fees";
import { SwapPricingType } from "@gmx-io/sdk/utils/orders";

const swapFee = getSwapFee(
  marketInfo,
  1000n * 10n ** 18n, // 1000 USDC (18 decimals)
  true, // swap improves pool balance
  SwapPricingType.Swap
);

getPositionFee

getPositionFee(
  marketInfo: MarketInfo,
  sizeDeltaUsd: bigint,
  balanceWasImproved: boolean,
  referralInfo: { totalRebateFactor: bigint; discountFactor: bigint } | undefined,
  uiFeeFactor?: bigint
): {
  positionFeeUsd: bigint;
  discountUsd: bigint;
  totalRebateUsd: bigint;
  uiFeeUsd: bigint;
}

Calculates the position fee for a size change. When referralInfo is provided, the rebate and discount are calculated and deducted from positionFeeUsd.

import { getPositionFee } from "@gmx-io/sdk/utils/fees";

const { positionFeeUsd, discountUsd, totalRebateUsd, uiFeeUsd } = getPositionFee(
  marketInfo,
  10000n * 10n ** 30n, // $10,000 size delta (30-decimal precision)
  false,
  { totalRebateFactor: 5000n, discountFactor: 3000n }, // rebate factors in basis points (PRECISION-scaled)
  100n // UI fee factor
);

Funding fee

getFundingFactorPerPeriod

getFundingFactorPerPeriod(marketInfo: MarketInfo, isLong: boolean, periodInSeconds: bigint): bigint

Returns the funding factor (PRECISION-scaled) accumulated over periodInSeconds. Negative values mean the position pays funding; positive values mean it receives funding.

The paying side is determined by marketInfo.longsPayShorts. The receiving side's factor is scaled by payingInterest / receivingInterest to maintain balance.

import { getFundingFactorPerPeriod } from "@gmx-io/sdk/utils/fees";

const factor = getFundingFactorPerPeriod(marketInfo, true, 3600n); // 1 hour in seconds (bigint)
// Negative: longs are paying funding this hour

getFundingFeeRateUsd

getFundingFeeRateUsd(marketInfo: MarketInfo, isLong: boolean, sizeInUsd: bigint, periodInSeconds: bigint): bigint

Returns the funding fee in USD for a position of sizeInUsd over periodInSeconds. Applies getFundingFactorPerPeriod to the size.

import { getFundingFeeRateUsd } from "@gmx-io/sdk/utils/fees";

const fundingFeeUsd = getFundingFeeRateUsd(
  marketInfo,
  true,
  10000n * 10n ** 30n, // $10,000 position
  86400n // 24 hours (bigint)
);

Borrow fee

getBorrowingFactorPerPeriod

getBorrowingFactorPerPeriod(marketInfo: MarketInfo, isLong: boolean, periodInSeconds: bigint): bigint

Returns the borrow factor (PRECISION-scaled) accumulated over periodInSeconds. Uses borrowingFactorPerSecondForLongs or borrowingFactorPerSecondForShorts from marketInfo.

import { getBorrowingFactorPerPeriod } from "@gmx-io/sdk/utils/fees";

const borrowFactor = getBorrowingFactorPerPeriod(marketInfo, false, 3600n); // short, 1 hour

getBorrowingFeeRateUsd

getBorrowingFeeRateUsd(marketInfo: MarketInfo, isLong: boolean, sizeInUsd: bigint, periodInSeconds: bigint): bigint

Returns the borrow fee in USD for a position of sizeInUsd over periodInSeconds.

import { getBorrowingFeeRateUsd } from "@gmx-io/sdk/utils/fees";

const borrowFeeUsd = getBorrowingFeeRateUsd(
  marketInfo,
  false,
  10000n * 10n ** 30n, // $10,000 position
  86400n // 24 hours
);

FeeItem helpers

getIsHighPriceImpact

getIsHighPriceImpact(positionPriceImpact?: FeeItem, swapPriceImpact?: FeeItem): boolean

Returns true when the combined price impact is negative and its absolute basis-point value is at or above HIGH_PRICE_IMPACT_BPS (80 bps = 0.8%).

import { getIsHighPriceImpact } from "@gmx-io/sdk/utils/fees";

const isHigh = getIsHighPriceImpact(positionPriceImpactFeeItem, swapPriceImpactFeeItem);
if (isHigh) {
  // warn the user before submitting
}

getFeeItem

getFeeItem(
  feeDeltaUsd?: bigint,
  basis?: bigint,
  opts?: { shouldRoundUp?: boolean }
): FeeItem | undefined

Creates a FeeItem from a USD delta and a USD basis. Returns undefined when feeDeltaUsd is undefined. When basis is undefined or 0, bps and precisePercentage are set to 0n.

import { getFeeItem } from "@gmx-io/sdk/utils/fees";

const feeItem = getFeeItem(
  -100n * 10n ** 30n, // -$100 impact
  10000n * 10n ** 30n // $10,000 basis
);
// feeItem.bps ≈ -100n (1%)
// feeItem.precisePercentage is PRECISION-scaled

getTotalFeeItem

getTotalFeeItem(feeItems: (FeeItem | undefined)[]): FeeItem

Sums a list of FeeItem objects. undefined entries are ignored. Always returns a FeeItem (never undefined), with all fields starting at 0n.

import { getTotalFeeItem } from "@gmx-io/sdk/utils/fees";

const total = getTotalFeeItem([positionFeeItem, swapFeeItem, undefined]);
// total.deltaUsd = sum of all non-undefined deltaUsd values

getTotalSwapVolumeFromSwapStats

getTotalSwapVolumeFromSwapStats(swapSteps?: SwapStats[]): bigint

Returns the sum of usdIn across all swap steps. Returns 0n when swapSteps is undefined or empty.

import { getTotalSwapVolumeFromSwapStats } from "@gmx-io/sdk/utils/fees";

const totalVolume = getTotalSwapVolumeFromSwapStats(swapPath);
// totalVolume: sum of usdIn for each hop in the swap path