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;
  signer?: Signer; // ethers/ethersV5
  walletClient?: WalletClient; // viem
  options?: {
    skipApproval?: boolean;
    skipCheckApproval?: boolean;
    wait?: number;
    isRaw?: boolean;
    outTokenDecimals?: number;
  };
  slippage?: {
    slippageAmount?: string | number;
    isBps?: boolean;
  }
}): Promise<{
  swapReceipt: TransactionReceipt;
  approveReceipt?: TransactionReceipt | undefined;
}>

TypeScript Types

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

Parameters

route: The route object (defaults to this.route)
- Contains the path and amounts for the swap
- Optional when called on a Route instance
includesNative: Whether the swap involves a native token (defaults to this.includesNative)
- Set to true if swapping from/to native token
- Affects how the wrapped native token is handled
signer/walletClient: Transaction signer
- signer for ethers/ethersV5 implementations
- walletClient for viem implementation
- Defaults to the signer/client provided during Route creation
options: Configuration for the swap and transaction
- skipApproval: If true, skips the approval transaction even if needed (default: true)
- skipCheckApproval: If true, skips checking if approval is needed (default: false)
- wait: Number of confirmations to wait for (default: 1)
- isRaw: If true, amounts are in wei units (default: true)
- outTokenDecimals: Decimals of the output token (optional)
slippage: Custom slippage settings for this swap
- slippageAmount: Slippage tolerance amount (defaults to config.slippage)
- isBps: If true, slippage is in basis points where 10000 = 100% (default: false)

Returns

Returns a Promise that resolves to a SwapResult object containing:

swapReceipt: Transaction receipt of swap (already waited for confirmations)
approveReceipt: Transaction receipt of the approval (if approval was needed)

Example Usage

Basic Swap

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();
 
// swapReceipt is already a TransactionReceipt (no need to call .wait())
console.log("Transaction hash:", swapReceipt.transactionHash);

Applying Custom Settings on 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 signer for ethers
  options: {
    // Check if approval needed
    skipCheckApproval: false,
    // Propose approval transaction before swap if needed
    skipApproval: false,
    // Wait for 3 confirmations
    wait: 3,
    // Amount formatting options
    isRaw: true,
    outTokenDecimals: 18,
  },
  slippage: {
    // Defaults to slippage value set in config if not explicitly given
    slippageAmount: 100, // 1% (with BPS scale 10000 = 100%)
    isBps: true,
  },
});

TypeScript Example

import { Route, Symphony } from "symphony-sdk/ethers";
import { SwapResult } from "symphony-sdk/types/ethers";
 
const symphony = new Symphony();
const route = await symphony.getRoute(tokenIn, tokenOut, "1.0");
 
const result: SwapResult = await route.swap({
  signer: ethersSigner,
  options: {
    wait: 2, // Wait for 2 confirmations
    isRaw: false, // Using formatted amounts
    outTokenDecimals: 6, // USDC has 6 decimals
  },
  slippage: {
    slippageAmount: "0.5", // 0.5% as percentage
    isBps: false,
  },
});
 
// No need to await result.swapReceipt.wait() - already waited!
console.log("Swap completed:", result.swapReceipt.transactionHash);

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
You can partially provide options, unmodified values 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)
Default behavior:
- Waits for 1 confirmation (wait: 1)
- Skips approval transaction (skipApproval: true)
- Doesn't check approval (skipCheckApproval: false)
- Uses raw amounts (isRaw: true)
- Uses percentage for slippage (isBps: false)
If you don't specify slippage, it uses the default from Symphony configuration

Error Handling

The method will throw an error if:

No wallet client/signer is connected
Token approval fails (if needed)
Transaction simulation fails (viem only)
Swap transaction fails
Slippage settings are invalid
includesNative flag doesn't match the tokens included in route parameter
Network issues or RPC errors occur