swapStats

This module provides utilities for calculating swap statistics, capacity, and liquidity for token swaps within GMX markets. It includes functions for analyzing swap paths, calculating fees and price impacts, and determining available liquidity.

Methods

The swapStats module exports functions for computing pool capacity, simulating swap paths, and calculating per-step swap statistics. Import any function directly from @gmx-io/sdk/utils/swap. When passing swapPricingType, use the SwapPricingType enum imported from @gmx-io/sdk/utils/orders.

getSwapCapacityUsd

getSwapCapacityUsd(marketInfo: MarketInfo, isLong: boolean): bigint

Returns the remaining swap capacity in USD for the specified pool side: convertToUsd(maxPoolAmount - poolAmount, token.decimals, getMidPrice(token.prices)).

import { getSwapCapacityUsd } from "@gmx-io/sdk/utils/swap";

const longCapacity = getSwapCapacityUsd(marketInfo, true); // long pool remaining capacity
const shortCapacity = getSwapCapacityUsd(marketInfo, false); // short pool remaining capacity

getSwapPathOutputAddresses

getSwapPathOutputAddresses(p: {
  marketsInfoData: MarketsInfoData;
  initialCollateralAddress: string;
  swapPath: string[];
  wrappedNativeTokenAddress: string;
  shouldUnwrapNativeToken: boolean;
  isIncrease: boolean;
}): { outTokenAddress: string | undefined; outMarketAddress: string | undefined }

Determines the output token and market addresses for a given swap path by walking the path and following opposite-collateral pointers at each step.

When swapPath is empty: for increase operations the initialCollateralAddress is returned as-is (increase targets are always ERC-20); for decrease operations the address is returned, or NATIVE_TOKEN_ADDRESS if shouldUnwrapNativeToken and the token is the wrapped native token.

When any market in the path is not found, both fields are undefined.

import { getSwapPathOutputAddresses } from "@gmx-io/sdk/utils/swap";

const { outTokenAddress, outMarketAddress } = getSwapPathOutputAddresses({
  marketsInfoData,
  initialCollateralAddress: wethAddress,
  swapPath: [ethUsdcMarketAddress],
  wrappedNativeTokenAddress: wethAddress,
  shouldUnwrapNativeToken: true,
  isIncrease: false,
});
// outTokenAddress: NATIVE_TOKEN_ADDRESS (unwrapped ETH for decrease)
// outMarketAddress: ethUsdcMarketAddress

getSwapPathStats

getSwapPathStats(p: {
  marketsInfoData: MarketsInfoData;
  swapPath: string[];
  initialCollateralAddress: string;
  wrappedNativeTokenAddress: string;
  usdIn: bigint;
  shouldUnwrapNativeToken: boolean;
  shouldApplyPriceImpact: boolean;
  swapPricingType: SwapPricingType;
}): SwapPathStats | undefined

Simulates a multi-step swap along swapPath and returns aggregate statistics. Returns undefined when swapPath is empty or any market in the path is not found.

The SwapPathStats return type:

Field	Type	Description
swapPath	string[]	Market addresses traversed
swapSteps	SwapStats[]	Per-step statistics
targetMarketAddress	string | undefined	Last market in path
tokenInAddress	string	Initial collateral address
tokenOutAddress	string	Final output token address
usdOut	bigint	Output value in USD (30-decimal)
amountOut	bigint	Output token amount (token decimals)
totalSwapFeeUsd	bigint	Sum of fees across all steps
totalSwapPriceImpactDeltaUsd	bigint	Sum of price impacts across all steps
totalFeesDeltaUsd	bigint	totalSwapPriceImpactDeltaUsd - totalSwapFeeUsd

import { getSwapPathStats } from "@gmx-io/sdk/utils/swap";
import { SwapPricingType } from "@gmx-io/sdk/utils/orders";

const pathStats = getSwapPathStats({
  marketsInfoData,
  swapPath: [ethUsdcMarketAddress],
  initialCollateralAddress: wethAddress,
  wrappedNativeTokenAddress: wethAddress,
  usdIn: 1000n * 10n ** 30n, // $1000 (30-decimal)
  shouldUnwrapNativeToken: false,
  shouldApplyPriceImpact: true,
  swapPricingType: SwapPricingType.Swap,
});

if (pathStats) {
  console.log("Total fee USD:", pathStats.totalSwapFeeUsd);
  console.log("Amount out:", pathStats.amountOut);
  console.log("USD out:", pathStats.usdOut);
}

getSwapStats

getSwapStats(p: {
  marketInfo: MarketInfo;
  tokenInAddress: string;
  tokenOutAddress: string;
  usdIn: bigint;
  shouldApplyPriceImpact: boolean;
  swapPricingType: SwapPricingType;
}): SwapStats

Computes detailed statistics for a single swap step. Uses tokenIn.prices.minPrice for amountIn conversion and tokenOut.prices.maxPrice for amountOut conversion.

When getPriceImpactForSwap throws (market out of capacity), returns a zero-output SwapStats with isOutLiquidity: true and isOutCapacity set based on whether the pool capacity is exceeded.

The SwapStats return type:

Field	Type	Description
marketAddress	string	Market being swapped through
tokenInAddress	string	Input token address
tokenOutAddress	string	Output token address
isWrap	boolean	tokenInAddress === NATIVE_TOKEN_ADDRESS
isUnwrap	boolean	tokenOutAddress === NATIVE_TOKEN_ADDRESS
isOutLiquidity	boolean | undefined	Output exceeds available liquidity
isOutCapacity	boolean | undefined	Input exceeds pool capacity
amountIn	bigint	Input token amount
amountInAfterFees	bigint	Input amount after fee deduction
usdIn	bigint	Input USD value (30-decimal)
swapFeeAmount	bigint	Fee in input token units
swapFeeUsd	bigint	Fee in USD (30-decimal)
priceImpactDeltaUsd	bigint	Capped price impact (30-decimal)
amountOut	bigint	Output token amount
usdOut	bigint	Output USD value (30-decimal)

import { getSwapStats } from "@gmx-io/sdk/utils/swap";
import { SwapPricingType } from "@gmx-io/sdk/utils/orders";

const swapStats = getSwapStats({
  marketInfo,
  tokenInAddress: wethAddress,
  tokenOutAddress: usdcAddress,
  usdIn: 1000n * 10n ** 30n, // $1000 (30-decimal)
  shouldApplyPriceImpact: true,
  swapPricingType: SwapPricingType.Swap,
});

console.log("Swap fee:", swapStats.swapFeeUsd);
console.log("Price impact:", swapStats.priceImpactDeltaUsd);
console.log("Amount out:", swapStats.amountOut);
console.log("Out of liquidity:", swapStats.isOutLiquidity);

getMaxSwapPathLiquidity

getMaxSwapPathLiquidity(p: {
  marketsInfoData: MarketsInfoData;
  swapPath: string[];
  initialCollateralAddress: string;
}): bigint

Returns the minimum available output liquidity across all steps in the swap path — the bottleneck that limits the maximum swap size. Returns 0n when swapPath is empty or any market in the path is not found.

import { getMaxSwapPathLiquidity } from "@gmx-io/sdk/utils/swap";

const maxLiquidity = getMaxSwapPathLiquidity({
  marketsInfoData,
  swapPath: [ethUsdcMarketAddress],
  initialCollateralAddress: wethAddress,
});

// Compare against desired swap size before submitting
if (maxLiquidity < desiredUsdIn) {
  console.warn("Swap exceeds available liquidity");
}