swapValues

This module provides utilities for calculating swap amounts and values for token exchanges in the GMX protocol. It handles both internal GMX swaps and external swap integrations, supporting limit orders and market orders with various optimization strategies.

Methods

The module exports three functions for computing swap amounts and sorting swap routes.

getSwapAmountsByFromValue

getSwapAmountsByFromValue(p: {
  tokenIn: TokenData;
  tokenOut: TokenData;
  amountIn: bigint;
  triggerRatio?: TokensRatio;
  isLimit: boolean;
  swapOptimizationOrder?: SwapOptimizationOrderArray;
  allowedSwapSlippageBps?: bigint;
  uiFeeFactor: bigint;
  marketsInfoData: MarketsInfoData | undefined;
  chainId: number;
  externalSwapQuoteParams: ExternalSwapQuoteParams | undefined;
  findSwapPath: FindSwapPath;
  allowSameTokenSwap: boolean;
}): SwapAmounts

Calculates SwapAmounts for a given input token amount. The returned SwapAmounts contains:

Field	Type	Description
amountIn	bigint	Input token amount
usdIn	bigint	Input value in USD (30-decimal)
amountOut	bigint	Expected output token amount
usdOut	bigint	Expected output value in USD
priceIn	bigint	Input token price used
priceOut	bigint	Output token price used
minOutputAmount	bigint	Minimum acceptable output amount
swapStrategy	SwapStrategyForIncreaseOrders	Internal/external swap strategy details

For limit orders (isLimit: true), triggerRatio is required to compute the target output; without it the function returns zero-output amounts.

For wrap/unwrap operations, no swap path is needed and amounts are returned directly.

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

const swapAmounts = getSwapAmountsByFromValue({
  tokenIn: wethToken,
  tokenOut: usdcToken,
  amountIn: 1n * 10n ** 18n, // 1 WETH
  isLimit: false,
  uiFeeFactor: 0n,
  marketsInfoData,
  chainId: 42161,
  externalSwapQuoteParams: undefined,
  findSwapPath: myFindSwapPath,
  allowSameTokenSwap: false,
});

console.log(swapAmounts.amountOut); // Expected USDC output
console.log(swapAmounts.minOutputAmount); // Minimum USDC (after fees)

getSwapAmountsByToValue

getSwapAmountsByToValue(p: {
  tokenIn: TokenData;
  tokenOut: TokenData;
  amountOut: bigint;
  triggerRatio?: TokensRatio;
  isLimit: boolean;
  swapOptimizationOrder?: SwapOptimizationOrderArray;
  allowedSwapSlippageBps?: bigint;
  uiFeeFactor: bigint;
  marketsInfoData: MarketsInfoData | undefined;
  chainId: number;
  externalSwapQuoteParams: ExternalSwapQuoteParams | undefined;
  findSwapPath: FindSwapPath;
  allowSameTokenSwap: boolean;
}): SwapAmounts

Calculates SwapAmounts for a desired output token amount. Determines how much input is required to receive amountOut. Returns the same SwapAmounts structure as getSwapAmountsByFromValue.

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

const swapAmounts = getSwapAmountsByToValue({
  tokenIn: wethToken,
  tokenOut: usdcToken,
  amountOut: 2000n * 10n ** 6n, // 2000 USDC
  isLimit: false,
  uiFeeFactor: 0n,
  marketsInfoData,
  chainId: 42161,
  externalSwapQuoteParams: undefined,
  findSwapPath: myFindSwapPath,
  allowSameTokenSwap: false,
});

console.log(swapAmounts.amountIn); // Required WETH input

getSwapPathComparator

getSwapPathComparator(order?: SwapOptimizationOrderArray): (a: SwapRoute, b: SwapRoute) => number

Returns a comparator function for sorting SwapRoute objects. The sort criteria are applied in order:

• "liquidity" — sort by route.liquidity descending (higher is better)
• "length" — sort by route.path.length ascending (shorter is better)

When order is undefined or empty, the comparator returns 0 for all pairs (stable, no-op sort).

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

const comparator = getSwapPathComparator(["liquidity", "length"]);
const sorted = swapRoutes.sort(comparator);
// sorted[0] — highest liquidity; ties broken by shortest path