📘Widget API Reference

There are two props you can pass to XY Finance Widget:

  1. config: This property allows you to specify the configuration for the widget. It must be an object that follows the structure of the Config interface.

  2. theme: This property lets you specify a custom UI theme for the widget. It must be an object that follows the structure of the Theme interface.

These two properties are optional. If not provided, they will default to predefined values.

Here's an example of how to use these properties in TypeScript:

import { XSwapWidget, Config, Theme } from '@xyfinance/widget'

const config: Config = {
  disabledChains: ['137', '42161'],
  slippage: '1',
  fromInput: '0.1',
  ...
}

const theme: Theme = {
  mode: 'light',
  fontFamily: 'proxima-nove, ui-sans-serif, system-ui, -apple-system',
  borderRadius: {
    container: '12px',
    inner: '8px',
    button: '32px'
  },
  colors: {
    primary: '#277EEC',
    gradient: ['#277EEC', '#1499E4']
  },
  components: {
    button: {
      variant: 'gradient'
    }
  }
}

function App() {
  return (
    <div>
      <XSwapWidget theme={theme} config={config} />
    </div>
  )
}

Theme

interface Theme {
  mode?: 'light' | 'dark'

  fontFamily?: string

  borderRadius?: {
    container?: string
    inner?: string
    button?: string
  }

  colors?: {
    primary?: string
    gradient?: [string?, string?]
  }

  components?: {
    button?: {
      variant?: 'gradient' | 'neutral' | 'filled' | 'grey'
    }
  }
}

mode

  • type: 'light' | 'dark'

  • default: 'light'

This option allows you to toggle the widget's mode between light and dark, depending on your preference.

fontFamily

  • type: string

  • default: 'ui-sans-serif, system-ui, -apple-system'

This option sets the font display for the widget, and works in compatibility with css font-family property.

const theme = {
  ...,
  fontFamily: 'ui-sans-serif, system-ui, -apple-system'
}

Please note that you need to install the font that you want to use in your frontend project by yourself, such as:

<head>
  ...
  <link rel="stylesheet" href="https://use.typekit.net/pws4fmb.css" />
</head>

borderRadius

  • type: IBorderRadius

interface IBorderRadius {
  container?: string
  inner?: string
  button?: string
}

  • default:

{
  container: '12px',
  inner: '8px',
  button: '32px'
}

This option controls the border radius of certain components. You can specify the radius in pixels.

colors

  • type: IColors

interface IColors {
  primary?: string
  gradient?: [string?, string?]
}

  • default:

{
  primary: '#277EEC',
  gradient: ['#277EEC', '#1499E4']
}

This option defines the colors used in this widget. You can specify the color using valid color strings such as RGBA, Hex, or HSL values.

gradient[0] represents the initial color, while gradient[1] signifies the final color in the gradient.

components

  • type: IComponents

interface IComponents {
  button?: IButton
}

interface IButton {
  variant?: 'gradient' | 'neutral' | 'filled' | 'grey'
}

  • default:

{
  button: {
    variant: 'gradient'
  }
}

This option controls the behavior and appearance of the components.

This option will be expanded over time as we extend our support.

Config

interface Config {
  disabledChains?: string[]

  fromToken?: UserToken | null
  toToken?: UserToken | null

  fromInput?: string

  slippage?: string
  referrer?: string

  featuredTokens?: UserToken[]
  disabledTokens?: UserToken[]

  disableTokenSelection?: 'from' | 'to' | 'both' | 'none'

  enableReport?: boolean
}

interface UserToken {
  chainId: string
  address: string
}

disabledChains

  • type: Array<string>

  • default: []

You can hide chains that you don't want to display. Here's our current list of supported chains.

For example, if you wish to disable BNB and Polygon from appearing in your widget, you can set:

const config = {
  ...,
  disabledChains: ['56', '137']
}

For security purposes, Ethereum cannot be disabled.

slippage

  • type: string

  • default: '1'

This option allows you to set the slippage rate for swapping, which can only be set to values with two decimal places between 0.01 and 49.99.

const config = {
  ...,
  slippage: '2'
}

If the difference between the estimated quote and execution price exceeds the default rate of 1%, the transaction will be cancelled.

referrer

  • type: string

  • default: '0xFD19727868A8197F42e7a52d024374598F62953B'

This option requires you to provide a web3 wallet address or smart contract address. Please complete the form. If the commissionRate is not configured, the referrer parameter will solely be utilized for tracking the traffic linked to your account.

const config = {
  ...,
  referrer: '0xFD19727868A8197F42e7a52d024374598F62953B'
}

commissionRate

  • type: number

  • default: 0

  • min: 0

  • max: 20000

Setting the commissionRate will collect a fee percentage from the user's swap amount, which is then directly distributed to the specified wallet address. XY Finance will receive a share of these fees, varying according to the use case and transaction volume.

  • commissionRate represents the fee you wish to collect. It is an integer between 0 and 20,000. In this range, 20,000 corresponds to 2%, 1,000 represents 0.1%, and so on in a similar fashion.

  • referrer parameter represents the address where you want to receive the fees. The collected fee in every transaction will be directly transferred to this address. Before proceeding, please ensure that the provided address is under your management and capable of receiving assets correctly.

const config = {
  ...,
  referrer: '0xFD19727868A8197F42e7a52d024374598F62953B',
  commissionRate: 1000
}

fromInput

  • type: string

  • default: ''

This option sets the initial value in your widget's source chain input.

For example, if you want to set the initial value to be 100.99, you can use the following code snippet:

const config = {
  ...,
  fromInput: '100.99'
}

fromToken

  • type: { chainId: string, address: string } | null

  • default: null

This option allows you to set the initial token for the source chain section of your widget.

For example, if you want to set your source chain token as ETH on the Ethereum network, you can use the following code snippet:

const config = {
  ...,
  fromToken: {
    chainId: '1',
    address: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
  }
}

You should use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE as the address for a native token in your configuration. Alternatively, you can also import NATIVE_TOKEN_ADDRESS from the widget package and use it as follows:

import { NATIVE_TOKEN_ADDRESS } from '@xyfinance/widget';

const config = {
  ...,
  fromToken: {
    chainId: '1',
    address: NATIVE_TOKEN_ADDRESS
  }
}

This allows you to use a constant value for the native token address in your code, which can make it easier to manage and modify in the future.

toToken

  • type: { chainId: string, address: string } | null

  • default: null

This option allows you to set the initial token for the destination chain section of your widget.

For example, if you want to set your destination chain token as BNB on the BNB chain, you can use the following code snippet:

const config = {
  ...,
  toToken: {
    chainId: '56',
    address: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
  }
}

featuredTokens

  • type: Array<{ chainId: string, address: string }>

  • default: []

This option highlights the tokens that you provide in the token selection page.

For example, if you want to highlight USDT on Ethereum and USDC on Polygon, you can use the following code snippet:

const config = {
  ...,
  featuredTokens: [
    {
      address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
      chainId: '1'
    },
    {
      address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174',
      chainId: '137'
    }
  ]
}

Please remember to fill out the form provided if you would like to highlight a token that is not listed in our token list. This will allow us to add it and ensure that the token icon is displayed correctly.

disabledTokens

  • type: Array<{ chainId: string, address: string }>

  • default: []

This option allows you to hide specific tokens from the token selection page. This can be useful if you want to limit the number of tokens available to the user.

For example, if you want to hide USDT on Ethereum and USDC on Polygon, you can use the following code snippet:

const config = {
  ...,
  disabledTokens: [
    {
      address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
      chainId: '1'
    },
    {
      address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174',
      chainId: '137'
    }
  ]
}

It's important to note that for safety reasons, native tokens cannot be disabled. Furthermore, please keep in mind that the disabledTokens option takes priority over the featuredTokens option. If a token is listed in both options, it will be hidden.

disableTokenSelection

  • type: 'from' | 'to' | 'both' | 'none'

  • default: 'none'

This option allows you to disable the swap token selection, which can be helpful if you want to limit your users to swapping tokens with a specific token.

const config = {
  ...,
  disableTokenSelection: 'to'
}

enableReport

  • type: boolean

  • default: true

Enabling the enableReport feature allows us to collect and analyze error messages from users on our server. This helps us to identify and resolve potential issues with the widget, ensuring a better user experience.

const config = {
  ...,
  enableReport: true
}

Examples

Check out our examples repository.

PreviousCustomize the ThemeNextChange Log

Last updated