swap

The swap method executes the token swap based on the route. It handles all types of swaps (token-to-token, native-to-token, token-to-native) and manages token approvals automatically.

Signature

async swap(params: {
  route: Route;
  includesNative?: boolean;
  options?: {
    skipApproval?: boolean;
    skipCheckApproval?: boolean;
  };
  slippage?: {
    slippageAmount: string | number;
    isRaw?: boolean;
    isBps?: boolean;
    outTokenDecimals?: number;
  }
}): Promise<{
  swapReceipt: TransactionReceipt,
  approveReceipt?: TransactionReceipt
}>

Parameters

• route: The route object returned from getRoute

  • Contains the path and amounts for the swap
  • Required for executing the swap

• includesNative: Whether the swap involves a native token (e.g., SEI)

  • Set to true if swapping from/to native token
  • Affects how the wrapped native token is handled
  • Required when swapping with native token

• options: Optional configuration for the swap

  • skipApproval: If true, skips the approval transaction even if needed (default: true)
  • skipCheckApproval: If true, skips checking if approval is needed (default: false)

• slippage: Custom slippage settings for this swap

  • slippageAmount: Slippage tolerance amount
  • isRaw: If true, slippage is in raw units (default: true)
  • isBps: If true, slippage is in basis points (e.g., 5000 = 0.5%) (default: false)
  • outTokenDecimals: Decimals of the output token (optional)

Returns

Returns a Promise that resolves to an object containing:

• swapReceipt: Transaction receipt of swap
• approveReceipt: Transaction receipt of the approval (if approval was needed)

Example Usage

const symphony = new Symphony();
 
// Get a route
const route = await symphony.getRoute(tokenIn, tokenOut, "1.0");
 
// Execute the swap
// This swap will get necessary values from the Route object and Symphony config
const { swapReceipt, approveReceipt } = await route.swap();

// Get a route
const route = await symphony.getRoute(tokenIn, tokenOut, "1.0");
 
// Swap with custom settings
const { swapReceipt, approveReceipt } = await route.swap({
  walletClient = viemWalletClient // or ethersSigner
  options: {
    // Check if approval needed   
    skipCheckApproval: false 
    // Propose approval transaction before swap if needed
    skipApproval: false,  
  },
  slippage: {
    // Defaults to slippage value set in config if not explicitly given
    slippageAmount: 5000, // 0.5%, 
    isBps: true
  }
});

Notes

• A valid wallet client / signer must be connected to execute swaps
• Route.swap() gets all necessary values from Route object created by getRoute function of Symphony if not given any custom options
• You can partially provide options, the options or arguments you do not modify will be taken from Route object
• The method automatically handles different swap types:
  • Token to token swaps (includesNative: false)
  • Native token to token swaps (e.g., SEI to USDC, includesNative: true)
  • Token to native token swaps (e.g., USDC to SEI, includesNative: true)
• By default, the method will:
  • Check if approval is needed (skipCheckApproval: false)
  • Skip the approval transaction (skipApproval: true)
• If you don't specify slippage, it uses the default from Symphony configuration
• The method simulates the transaction before execution to catch potential errors

Error Handling

The method will throw an error if:

• No wallet client is connected
• Token approval fails (if needed)
• Transaction simulation fails
• Swap transaction fails
• Slippage settings are invalid
• includesNative flag doesn't match the tokens included in route parameter