# 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. {% hint style="info" %} These two properties are optional. If not provided, they will default to predefined values. {% endhint %} Here's an example of how to use these properties in `TypeScript`: ```tsx import { Widget, 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 (
) } ``` ## Theme ```tsx 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**](https://www.w3schools.com/cssref/pr_font_font-family.php). ```tsx 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: ```html ... ``` ### `borderRadius` * type: `IBorderRadius` ```tsx interface IBorderRadius { container?: string inner?: string button?: string } ``` * default: ```typescript { 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` ```tsx interface IColors { primary?: string gradient?: [string?, string?] } ``` * default: ```tsx { 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. {% hint style="info" %} **`gradient[0]`** represents the initial color, while **`gradient[1]`** signifies the final color in the gradient. {% endhint %} ### `components` * type: `IComponents` ```tsx interface IComponents { button?: IButton } interface IButton { variant?: 'gradient' | 'neutral' | 'filled' | 'grey' } ``` * default: ```tsx { button: { variant: 'gradient' } } ``` This option controls the behavior and appearance of the components. {% hint style="info" %} This option will be expanded over time as we extend our support. {% endhint %} ## C**onfig** ```tsx 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` * default: `[]` You can hide chains that you don't want to display. Here's our current list of [supported chains](https://docs.xy.finance/supported-blockchains-bridges-dexs). For example, if you wish to disable `BNB` and `Polygon` from appearing in your widget, you can set: ```jsx const config = { ..., disabledChains: ['56', '137'] } ``` {% hint style="info" %} For security purposes, **`Ethereum`** cannot be disabled. {% endhint %} ### **`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. ```jsx const config = { ..., slippage: '2' } ``` {% hint style="warning" %} If the difference between the estimated quote and execution price exceeds the default rate of 1%, the transaction will be cancelled. {% endhint %} ### **`referrer`** * type: `string` * default: `'0xFD19727868A8197F42e7a52d024374598F62953B'` This option requires you to provide a web3 wallet address or smart contract address. Please complete the [form](https://docs.google.com/forms/d/e/1FAIpQLSeJamZPxZm2oDyMGUFcEqlSHfy_WjIpuAYEqwu98rPg5xAedA/viewform). If the `commissionRate` is not configured, the referrer parameter will solely be utilized for tracking the traffic linked to your account. ```jsx 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.** ```jsx 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: ```jsx 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: ```jsx 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: ```jsx 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: ```jsx 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: ```jsx const config = { ..., featuredTokens: [ { address: '0xdac17f958d2ee523a2206206994597c13d831ec7', chainId: '1' }, { address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', chainId: '137' } ] } ``` {% hint style="info" %} Please remember to fill out the [form](https://docs.google.com/forms/d/e/1FAIpQLSeJamZPxZm2oDyMGUFcEqlSHfy_WjIpuAYEqwu98rPg5xAedA/viewform) 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. {% endhint %} ### **`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: ```jsx const config = { ..., disabledTokens: [ { address: '0xdac17f958d2ee523a2206206994597c13d831ec7', chainId: '1' }, { address: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', chainId: '137' } ] } ``` {% hint style="info" %} 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. {% endhint %} ### **`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. ```jsx 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. ```jsx const config = { ..., enableReport: true } ``` ### **Examples** Check out our [**examples repository**](https://github.com/XY-Finance/examples).