Skip to main content
The getBestRoute function finds the optimal trading route for a token swap through Fibrous’s liquidity pools.

​
Function Signature

/**
  * Fetches the best route from the API.
  * @param params Route parameters object.
  * @returns Route response.
  * @throws Error if the chain is not supported.
  */
getBestRoute(
    params: getBestRouteParams,
): Promise<RouteResponse>;

​
getBestRouteParams Type

type getBestRouteParams = {
  amount: AmountType;
  tokenInAddress: string;
  tokenOutAddress: string;
  chainId: number;
  options?: Partial<RouteOverrides>;
  integrationData?: IntegrationData;
};

​
IntegrationData Type

type IntegrationData = {
  integratorAddress: string;
  integratorFeePercentageBps?: number; // 0-500, maximum 5%
  integratorSurplusPercentageBps?: number; // 0-5000, maximum 50%
};

​
Parameters

ParameterTypeDescription
params.amountBigNumberAmount to swap, formatted according to token decimals
params.tokenInAddressstringToken address to swap from
params.tokenOutAddressstringToken address to swap to
params.chainIdnumberChain ID where the transaction will take place
params.optionsRouteOverridesOptional parameters for route customization
params.integrationDataIntegrationDataOptional integrator fee/surplus configuration

​
RouteOverrides Type

type RouteOverrides = {
  reverse: boolean;
  direct: boolean;
  excludeProtocols: number[];
};
  • excludeProtocols: This is where you list the IDs of the AMMs you don’t want to include. For example, if there are certain AMMs you prefer not to use due to high fees or other reasons, you simply put their unique IDs (numbers) in this list.
  • Use supportedProtocols(chainId) to get a list of supported AMMs and their IDs.

​
RouteResponse Type

type RouteResponse = {
  success: true;
  inputToken: Token;
  inputAmount: string;
  outputToken: Token;
  outputAmount: string;
  estimatedGasUsed: string;
  estimatedGasUsedInUsd?: number;
  route: FormattedRoute[];
  time: number;
  bestQuotesByProtocols: string[];
  initial?: boolean;
  routeSwapType?: RouteSwapType;
  integratorAddress?: string;
  integratorFeePercentage?: number;
  integratorSurplusPercentage?: number;
  meta: {
    apiVersion: string;
    timestamp: string;
  };
};

​
Example Usage

import { Router as FibrousRouter, getBestRouteParams } from "fibrous-router-sdk";
import { parseUnits } from "ethers";

// Create a new router instance with v2 API
const fibrous = new FibrousRouter({
    apiKey: "your-api-key", // optional, required for integrator features
    apiVersion: "v2", // optional, v2 is the latest version
});

// Refresh and get supported chains
const chains = await fibrous.refreshSupportedChains();
const chainId = chains.find(chain => chain.chain_name == "hyperevm")?.chain_id;
if (!chainId) {
    throw new Error("Chain not supported");
}

// Build route options
const tokens = await fibrous.supportedTokens(chainId);
// Get input token from tokens map
const inputToken = tokens.get("usdc");
if (!inputToken) {
    throw new Error("Input token not found");
}
// Get output token by address (for unverified tokens)
const outputToken = await fibrous.getToken(
    "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
    chainId,
);
if (!outputToken) {
    throw new Error("Output token not found");
}
const tokenInAddress = inputToken.address;
const tokenOutAddress = outputToken.address;
const tokenInDecimals = Number(inputToken.decimals);
const inputAmount = BigInt(parseUnits("4", tokenInDecimals)); // 4 USDC

const getBestRouteParams: getBestRouteParams = {
    amount: inputAmount,
    tokenInAddress: tokenInAddress,
    tokenOutAddress: tokenOutAddress,
    chainId: chainId,
    options: {
        reverse: false,
    },
};

const route = await fibrous.getBestRoute(getBestRouteParams);
// returns route type (src/types/route.ts)