getRoute

The getRoute method is used to find the best swap route for a token pair. It returns a Route object that contains all the necessary information about the swap and methods to execute it.

Signature

async getRoute(
  tokenIn: string, 
  tokenOut: string, 
  amountIn: string | number | bigint,
  options?: { isRaw?: boolean }
): Promise<Route>

Parameters

• tokenIn: Address of the input token
  • Use native token address (e.g., "0x0") for the chain's native token, you can always set a native token alias in configuration while creating Symphony object or use setConfig to later modify it.
  • Use ERC20 token address for other tokens
• tokenOut: Address of the output token
  • Same rules as tokenIn apply
• amountIn: Amount of input token to swap
  • If isRaw=false (default): Use formatted units (e.g., "1.0")
  • If isRaw=true: Use raw units (wei)
• options: Optional configuration
  • isRaw: If true, amounts are treated as raw units (wei)
    • Note: When amountIn is bigint, isRaw is automatically set to true

Returns

Returns a Route object containing:

• route: Raw route data from API
• amountIn: Input amount in raw units
• amountInFormatted: Input amount formatted
• amountOut: Output amount in raw units
• amountOutFormatted: Output amount formatted
• pathPercentages: Split between paths
• pathCount: Number of paths
• includesNative: Whether route includes native token
• tokenIn: Input token address
• tokenOut: Output token address

Examples

Basic Usage

// Get route for swapping 1 SEI to USDC
const route = await symphony.getRoute(
  "0x0",  // SEI (native token)
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  "1.0"   // 1 SEI
);
 
console.log(`Expected output: ${route.amountOutFormatted} USDC`);

Using Raw Amounts

// Get route using raw amount (wei)
const route = await symphony.getRoute(
  "0xe30fedd158a2e3b13e9badaeabafc5516e95e8c7", // WSEI
  "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT
  1000000000000000000n, // or '1000000000000000000' - 1 WSEI in wei
  { isRaw: true }
);

Complete Swap Flow

// 1. Get the route
const route = await symphony.getRoute(tokenIn, tokenOut, "1.0");
 
// 2. Check if approval is needed
const approvalTx = await route.giveApproval();
console.log(`Approval tx: ${approvalTx}`);
  
// 3. Execute the swap
const { swapReceipt } = await route.swap();
console.log(`Swap executed: ${swapReceipt.transactionHash}`);

Alternative Swap Flow

This way, swap function first requests an approval transaction if token is not approved. Then chains a swap transaction. It is your decision to combine approval and swap transactions to be requested by Symphony. Refer to swap for detailed information.

// 1. Get the route
const route = await symphony.getRoute(tokenIn, tokenOut, "1.0");
  
// 2. Execute the swap
const { swapReceipt } = await route.swap({options:{
    skipApproval:false
}});
console.log(`Swap executed: ${swapReceipt.transactionHash}`);

Error Handling

The method throws an error if:

• Required parameters are missing
• API request fails
• Token addresses are invalid
• Amount is invalid or zero