swapPath

This module provides utilities for finding optimal swap paths between tokens in the GMX protocol. It handles path discovery, liquidity analysis, and gas cost estimation to determine the most efficient routes for token swaps.

Methods

The swapPath module exports a utility for address normalization and the main factory for building swap-path finders. Import any function directly from @gmx-io/sdk/utils/swap.

getWrappedAddress

getWrappedAddress(chainId: number, address: string | undefined): string | undefined

Converts a token address to its wrapped equivalent for the chain (for example, native ETH → WETH). Returns undefined when address is undefined.

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

const wrappedAddress = getWrappedAddress(42161, nativeTokenAddress);
// Returns WETH address for Arbitrum

createFindSwapPath

createFindSwapPath(params: {
  chainId: number;
  fromTokenAddress: string | undefined;
  toTokenAddress: string | undefined;
  marketsInfoData: MarketsInfoData | undefined;
  gasEstimationParams?: {
    gasPrice: bigint;
    gasLimits: GasLimitsConfig;
    tokensData: TokensData;
  };
  swapPricingType: SwapPricingType | undefined;
  disabledMarkets?: string[];
  manualPath?: string[];
}): FindSwapPath

Creates a closure that finds the best swap path between two tokens. Call it once with the current market data, then call the returned FindSwapPath function for each input amount or sorting preference you want to evaluate.

The returned FindSwapPath function has the signature:

(usdIn: bigint, opts?: { order?: ("liquidity" | "length")[] }) => SwapPathStats | undefined;

Results are cached per (usdIn, order) combination.

Routing logic:

• When manualPath is provided, the closure uses it directly and skips automatic routing.
• When opts.order is provided or usdIn === 0n, the closure uses the max-liquidity path (optionally filtered to shortest paths when order[0] === "length").
• Otherwise, the closure runs the full two-phase routing: naive pre-selection followed by accurate scoring via getBestSwapPath.

When marketsInfoData is undefined, the returned function always returns undefined.

When swapPricingType is SwapPricingType.AtomicSwap, markets unavailable for Express Trading are automatically added to disabledMarkets.

note

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

The returned SwapPathStats contains:

Field	Type	Description
swapPath	string[]	Market addresses in hop order
swapSteps	SwapStats[]	Per-hop stats (fees, price impact, amounts)
tokenInAddress	string	Input token address
tokenOutAddress	string	Output token address
usdOut	bigint	Estimated USD output (30-decimal)
amountOut	bigint	Estimated output token amount
totalSwapFeeUsd	bigint	Total fees in USD across all hops
totalSwapPriceImpactDeltaUsd	bigint	Total price impact in USD
totalFeesDeltaUsd	bigint	Combined fees and price impact

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

const findSwapPath = createFindSwapPath({
  chainId: 42161,
  fromTokenAddress: wethAddress,
  toTokenAddress: usdcAddress,
  marketsInfoData,
  gasEstimationParams: {
    gasPrice: 1000000000n,
    gasLimits,
    tokensData,
  },
  swapPricingType: SwapPricingType.Swap,
});

// Find best path for a $1000 swap
const result = findSwapPath(1000n * 10n ** 30n);

if (result) {
  console.log("Market path:", result.swapPath);
  console.log("USD out:", result.usdOut);
  console.log("Total fees:", result.totalFeesDeltaUsd);
}

// Find highest-liquidity path (useful for showing available capacity)
const liquidityPath = findSwapPath(0n, { order: ["liquidity"] });