trade

This module provides utility functions for trade operations including slippage calculations, swap counting, and trade flag creation for the GMX protocol.

Methods

This module exports four utility functions used in trade calculations.

applySlippageToPrice

applySlippageToPrice(allowedSlippage: number, price: bigint, isIncrease: boolean, isLong: boolean): bigint

Adjusts an acceptable price by the given slippage in basis points. For operations that use maxPrice (long increases and short decreases), slippage is added — resulting in a higher acceptable price. For operations that use minPrice (short increases and long decreases), slippage is subtracted.

import { applySlippageToPrice } from "@gmx-io/sdk/utils/trade";

// Long increase: acceptable price is 0.5% above mark price
const acceptablePrice = applySlippageToPrice(
  50, // 50 bps = 0.5%
  1800n * 10n ** 30n, // mark price
  true, // isIncrease
  true // isLong
);
// acceptablePrice ≈ 1800 × 1.005 = 1809

applySlippageToMinOut

applySlippageToMinOut(allowedSlippage: number, minOutputAmount: bigint): bigint

Reduces minOutputAmount by the given slippage in basis points. Always reduces the minimum — use this to set the minOut parameter in swap orders.

import { applySlippageToMinOut } from "@gmx-io/sdk/utils/trade";

const minOut = applySlippageToMinOut(
  100, // 100 bps = 1%
  1000n * 10n ** 6n // 1000 USDC (6 decimals)
);
// minOut = 990 USDC — accept up to 1% slippage

getSwapCount

getSwapCount(params: {
  isSwap: boolean;
  isIncrease: boolean;
  swapAmounts?: SwapAmounts;
  increaseAmounts?: IncreasePositionAmounts;
  decreaseAmounts?: DecreasePositionAmounts;
}): number | undefined

Returns the number of market swaps in the current trade. Returns undefined when the required amounts object is not provided.

• For swaps: returns swapAmounts.swapStrategy.swapPathStats?.swapPath.length ?? 0
• For increase orders: returns increaseAmounts.swapStrategy.swapPathStats?.swapPath.length ?? 0
• For decrease orders: returns 1 when decreaseSwapType !== NoSwap, otherwise 0

import { getSwapCount } from "@gmx-io/sdk/utils/trade";

// 2-hop swap path
const swapCount = getSwapCount({
  isSwap: true,
  isIncrease: false,
  swapAmounts,
});
// swapCount = swapAmounts.swapStrategy.swapPathStats?.swapPath.length ?? 0

createTradeFlags

createTradeFlags(tradeType: TradeType, tradeMode: TradeMode): TradeFlags

Creates a TradeFlags object that derives all boolean flags from a (TradeType, TradeMode) pair. The derivation rules are:

Flag	Rule
isLong	tradeType === TradeType.Long
isShort	tradeType === TradeType.Short
isSwap	tradeType === TradeType.Swap
isPosition	isLong || isShort
isMarket	tradeMode === TradeMode.Market
isLimit	tradeMode === TradeMode.Limit || tradeMode === TradeMode.StopMarket
isTrigger	tradeMode === TradeMode.Trigger
isTwap	tradeMode === TradeMode.Twap
isIncrease	isPosition && (isMarket || isLimit || isTwap)

note

Both TradeMode.Limit and TradeMode.StopMarket produce isLimit: true. A Trigger decrease (TradeMode.Trigger) produces isIncrease: false.

import { createTradeFlags } from "@gmx-io/sdk/utils/trade";
import { TradeType, TradeMode } from "@gmx-io/sdk/utils/trade";

const flags = createTradeFlags(TradeType.Long, TradeMode.Market);
// { isLong: true, isShort: false, isSwap: false, isPosition: true,
//   isIncrease: true, isMarket: true, isLimit: false, isTrigger: false, isTwap: false }

const triggerFlags = createTradeFlags(TradeType.Long, TradeMode.Trigger);
// isIncrease: false — trigger decrease, not an increase