# XY Finance Widget (iframe)

XY Finance team has been wracking our brains just to come up with a powerful engagement tool to help strengthen your user retention, making them want to come back more for a satisfying user experience that this widget provides for your website and reducing friction by letting them fast-forward into your app's/site's key functionality. Note that this Widget will be constantly renewed as we're also gathering more resources and collecting feedback from users along the way. 

## Get Started

Place the `<iframe>` tag where you want the widget to appear, and you’re all set!

```tsx
export default function App() {
  // You can change the iframe size. Recommended settings: width 480, height 700.
  return (
    <>
      <iframe width={480} height={700} src="https://widget.xy.finance" />
    </>
  )
}
```

{% hint style="info" %}
List of environments we've tested so far:

* React ([Example](https://github.com/XY-Finance/examples/tree/main/widget-iframe/v1/vite-react))
* Vue ([Example](https://github.com/XY-Finance/examples/tree/main/widget-iframe/v1/vite-vue))
* Next.js ([Example](https://github.com/XY-Finance/examples/tree/main/widget-iframe/v1/nextjs))

For more detailed examples, please refer to our [example repository](https://github.com/XY-Finance/examples/?tab=readme-ov-file) where you can find additional information.
{% endhint %}

***

## Configuring Default Settings for the Widget

If you’d like to set default values for the widget, simply add search parameters to the URL.&#x20;

For example:

```
https://widget.xy.finance/?amount=1&fromTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&lockmode=none&referrer=0x856ebdc948afFCc6E24FCe08458051B19de652F6&commissionRate=2000&slippage=1&sourceChainId=1&targetChainId=1&theme=light&toTokenAddress=0x77777777772cf0455fB38eE0e75f38034dFa50DE
```

```tsx
import queryString from 'query-string'

export default function App() {
  const config = {
    // The address '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' stands for the native token.
    fromTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
    sourceChainId: '1',
    toTokenAddress: '0x77777777772cf0455fB38eE0e75f38034dFa50DE',
    targetChainId: '1',
    amount: 1,
    slippage: '1',
    theme: 'dark',
    lockmode: 'none',
    referrer: '0x856ebdc948afFCc6E24FCe08458051B19de652F6',
    commissionRate: 2000
  }
  const searchParams = queryString.stringify(config)
  // amount=1&fromTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&lockmode=none&referrer&slippage=1&sourceChainId=1&targetChainId=1&theme=dark&toTokenAddress=0x77777777772cf0455fB38eE0e75f38034dFa50DE

  return (
    <div>
      <iframe
        width={480}
        height={700}
        src={`https://widget.xy.finance/?${searchParams}`}
      />
    </div>
  )
}
```

## Configuration

<table><thead><tr><th width="196">Key</th><th width="179">Type</th><th width="140">Default</th><th>Note</th></tr></thead><tbody><tr><td>fromTokenAddress</td><td>String</td><td>'0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'</td><td>Use <code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code> as the address for a native token in your configuration.</td></tr><tr><td>sourceChainId</td><td>String</td><td>'1'</td><td>Please check <a data-mention href="../supported-blockchains-bridges-dexs">supported-blockchains-bridges-dexs</a></td></tr><tr><td>toTokenAddress</td><td>String</td><td>'0x77777777772cf0455fB38eE0e75f38034dFa50DE'</td><td></td></tr><tr><td>targetChainId</td><td>String</td><td>'1'</td><td>Please check <a data-mention href="../supported-blockchains-bridges-dexs">supported-blockchains-bridges-dexs</a></td></tr><tr><td>amount</td><td>Number</td><td>1</td><td></td></tr><tr><td>slippage</td><td>String</td><td>'1'</td><td>If the difference between the estimated quote and execution price exceeds the rate (default rate 1%), the tx will be revoked.</td></tr><tr><td>theme</td><td><code>dark</code> | <code>light</code></td><td><code>dark</code></td><td></td></tr><tr><td>lockmode</td><td><code>none</code> or <code>both</code> or <code>fromToken</code> or <code>toToken</code></td><td><code>none</code></td><td>Disable user select Token </td></tr><tr><td>referrer</td><td>String or null</td><td>null</td><td>For the details, please check <a data-mention href="#how-do-referrer-and-commissionrate-work">#how-do-referrer-and-commissionrate-work</a></td></tr><tr><td>commissionRate</td><td>Number</td><td>0</td><td><p>min: <code>0</code><br>max: <code>20000</code></p><p></p><p>For the details, please check <a data-mention href="#how-do-referrer-and-commissionrate-work">#how-do-referrer-and-commissionrate-work</a></p></td></tr></tbody></table>

## How do referrer and commissionRate work?

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.**

{% tabs %}
{% tab title="Theme: Dark" %}
![](https://3694085950-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mcs9EhDrgbKHodtcAT6%2Fuploads%2FjxCci2sOpKX2jcmCkXCL%2Fiframe-dark.png?alt=media\&token=6e83991d-75f3-41ee-a574-623166ec504e)
{% endtab %}

{% tab title="Theme: Light" %}

<figure><img src="https://3694085950-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mcs9EhDrgbKHodtcAT6%2Fuploads%2Fufx7oGRXDkLGU7ThO9eq%2Fiframe-light.png?alt=media&#x26;token=4e15bdf0-7099-47f6-bbc2-37866e52ad2a" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}