Configuration

Configuration object is consumed by Symphony SDK. You can partially or completely modify it to your needs.

TypeScript Types

// Import for viem
import type { SymphonyConfig, FeeParams } from 'symphony-sdk/types/viem';
import type { TokenList, TokenMetadata, Address } from 'symphony-sdk/types/viem';
 
// Import for ethersV5
import type { SymphonyConfig, FeeParams } from 'symphony-sdk/types/ethersV5';
import type { TokenList, TokenMetadata, Address } from 'symphony-sdk/types/ethersV5';
 
// Import for ethers v6
import type { SymphonyConfig, FeeParams } from 'symphony-sdk/types/ethers';
import type { TokenList, TokenMetadata, Address } from 'symphony-sdk/types/ethers';
 
interface SymphonyConfig {
  apiUrl?: string;
  timeout?: number;
  chainId?: number;
  chainName?: string;
  rpcUrl?: string;
  nativeAddress?: Address;
  wrappedNativeAddress?: Address;
  slippage?: string;
  additionalTokens?: TokenList;
  overrideDefaultTokens?: boolean;
  feeParams?: FeeParams;
  publicClient?: any;        // viem PublicClient
  provider?: any;            // ethers Provider
  tokens?: TokenList;
}
 
interface FeeParams {
  paramFee: string;
  feeAddress: Address;
  feeSharePercentage: string;
}
 
interface TokenList {
  [tokenAddress: string]: TokenMetadata;
}
 
interface TokenMetadata {
  id: string;
  attributes: {
    address: Address;
    name: string;
    symbol: string;
    decimals: number;
    initialSupply: string;
    logoUrl: string;
  };
}
 
type Address = `0x${string}`;

Overview

const defaultConfig = {
  timeout: 10000,
  chainId: 1329,
  chainName: "sei",
  rpcUrl: "https://sei-rpc.publicnode.com",
  nativeAddress: "0x0",
  wrappedNativeAddress: "0xe30fedd158a2e3b13e9badaeabafc5516e95e8c7",
  slippage: "0.5",
  publicClient: publicClient,
  tokens: TokenListByAddress,
  additionalTokens: {},
  overrideDefaultTokens: false,
  feeParams: {
    paramFee: "0",
    feeAddress: "0x0000000000000000000000000000000000000000",
    feeSharePercentage: "0",
  },
};

Parameters

timeout

  number

Timeout time for route calls

chainId

  string

Chain Id that Symphony operates on.

chainName

  string

Chain Name that Symphony operates on.

rpcUrl

  string

Rpc Url that Symphony uses to create public provider/client.

nativeAddress

  string

Address for Symphony to refer native token internally. Default is '0x0'.

slippage

  string | number

Slippage percentage Symphony uses internally. You can always override slippage amount while using 'swap'. Refer to 'slippage' section for details.

provider / publicClient

  string

Public Client / Provider Symphony uses to do read calls, transaction simulations

tokens

  array

Token list of Symphony Aggregator. Returns tokens depending on chainId.

additionalTokens

  object

An object where keys are token addresses and values are token data objects. This allows you to add custom tokens to the default token list. Symphony will merge these tokens with its default list. Each token object must adhere to the required structure, including id, attributes (with address, name, symbol, decimals, and logoUrl). All token addresses are automatically normalized to lowercase.

Example:

additionalTokens: {
  "0x1234567890abcdef1234567890abcdef12345678": {
    id: "sei_0x1234567890abcdef1234567890abcdef12345678", // has to be in sei_[address] format
    attributes: {
      address: "0x1234567890abcdef1234567890abcdef12345678",
      name: "Custom Token 1",
      symbol: "CTK1",
      decimals: 18,
      logoUrl: "https://example.com/ctk1.png"
    }
  }
}

overrideDefaultTokens

  boolean

When set to true, Symphony will use only the tokens provided in additionalTokens, completely ignoring its default token list. If additionalTokens is not provided or is empty, and overrideDefaultTokens is true, the token list will be empty. Defaults to false.

Example (using only custom tokens):

overrideDefaultTokens: true,
additionalTokens: {
  "0xabcdef1234567890abcdef1234567890abcdef12": {
    id: "my_exclusive_token",
    attributes: {
      address: "0xabcdef1234567890abcdef1234567890abcdef12",
      name: "My Exclusive Token",
      symbol: "MET",
      decimals: 6,
      logoUrl: "https://example.com/met.png"
    }
  }
}

feeParams

  object

feeParams structure for executeSwaps function of Symphony contract. Used for split fees. Deactive by default.

• paramFee - Custom fee amount that will override platform fees. Represents a percentage in bps and should be between 1 and 10000. 100% = 10000.
• feeAddress - Receiver address of custom fee.
• feeSharePercentage - Percentage of fee split, between Symphony and user.

feeAddress being zero address disables custom fee behavior.

Example: 0.01% Fee with a 80-20% Split

Here’s how to configure feeParams for a 0.1% swap fee, where 20% of the collected fee is shared with Symphony.

feeParams: {
  paramFee: "1", // 1 bps = 0.1%
  feeAddress: feeReceiverAddress, // Your fee-receiving address
  feeSharePercentage: "8000", // 8000 / 10000 = 80%
}

• Total Fee: The total fee is calculated based on paramFee.

   Total Fee = finalTokenAmount * (paramFee / 10000)
 
   Total Fee = finalTokenAmount * (1 / 10000) = 0.01% of the final amount

• Fee Split: The feeSharePercentage determines how the fee is divided. Note that split calculations are based on Total Fee which is 0.01% of finalTokenAmount.

  • Your Share (80%):

    Your Share = Total Fee * (1 - feeSharePercentage / 10000)
   
    Your Share = Total Fee * (1 - (8000 / 10000)) = 80% of Total Fee

  • Symphony Share (20%):

    Symphony Share = Total Fee - Your Share = 20% of Total Fee
   
    Symphony Share = 10000 - 8000 = 2000 bps
   
    Symphony Share = Total Fee * (1 - (2000 / 10000)) = 20% of Total Fee

We kindly suggest a 20% feeSharePercentage, but this is not enforced and is up to you to decide.