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>

TypeScript Types

// Import for viem
import { Symphony, Route } from "symphony-sdk/viem";
import { RoutePayload } from "symphony-sdk/types/viem";
 
// Import for ethersV5
import { Symphony, Route } from "symphony-sdk/ethersV5";
import { RoutePayload } from "symphony-sdk/types/ethersV5";
 
// Import for ethers v6
import { Symphony, Route } from "symphony-sdk/ethers";
import { RoutePayload } from "symphony-sdk/types/ethers";

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.transactionHash}`);
 
// 3. Execute the swap
const { swapReceipt } = await route.swap();
console.log(`Swap executed: ${swapReceipt.transactionHash}`);

TypeScript Example

import { Symphony, Route } from 'symphony-sdk/ethers';
import { SwapResult } from 'symphony-sdk/types/ethers';
 
const symphony = new Symphony();
 
// Get route with type safety
const route: Route = await symphony.getRoute(
  "0x0", // Native token
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  "1.0",
  { isRaw: false }
);
 
// Execute swap with typed result
const result: SwapResult = await route.swap({
  signer: ethersSigner,
  options: {
    skipApproval: false,
    wait: 2
  }
});
 
console.log(`Swap hash: ${result.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