Skip to main content

Swap tokens

The Swap widget is a drop-in solution for web-based games and marketplaces that simplifies the process of swapping tokens.

Sections
Swap widgetSwap widget
💡Allowlisted tokens
Only tokens that have been allowlisted will be displayed on the widgets. To allowlist an ERC20 token contact our support team.
💡Geo-location restrictions
The swap UI may not be available in certain jurisdictions in development and production environments. This currently includes, United States, Australia and other jurisdictions subject to Immutable's compliance controls. Note the UI is available in all locations in a sandbox environment for testing purposes only.

Getting started​

Once you have completed the widget setup, use the WidgetsFactory to create a connect widget. In order to mount the widget, call the mount() function and pass in the id attribute of the target element you wish to mount it to.

import { useEffect } from 'react';
import { checkout } from '@imtbl/sdk';

// create Checkout SDK
const checkoutSDK = new checkout.Checkout();

export function App() {
  // Initialise widgets, create swap widget and mount
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const swap = widgets.create(checkout.WidgetType.SWAP)
      swap.mount("swap");
    })();
  }, []);

  return (<div id="swap" />);
}

Parameters​

The mount() function can also take in parameters to be passed into the widget.

Widget parameters

Parameters are treated as transient and will be reset after the widget is unmounted.

PropertyDescription
fromTokenAddressThe address of the ERC20 contract swapping from. Use NATIVE to set the swapping from token to IMX. This will prefill the token field in the form.
toTokenAddressThe address of the ERC20 contract swapping to. Use NATIVE to set the swapping to token to IMX. This will prefill the token field in the form.
amountThe ERC20 token amount to swap.
walletProviderNameThe wallet provider name to use for the swap widget.
import { checkout } from "@imtbl/sdk";

// @ts-ignore
const swap = widgets.create(checkout.WidgetType.SWAP, 
  { config: { theme: checkout.WidgetTheme.DARK }}
);

// When calling the mount function, pass in the parameters to use
swap.mount('swap', { fromTokenAddress: '0x123', toTokenAddress: '0x999', amount: '10' })

Configuration​

When you first create the widget, you can pass an optional configuration object to set it up. For example, passing in the theme will create the widget with that theme. If this is not passed the configuration will be set by default.

Widget configuration

Configuration will persist after the widget is unmounted. You can always update a widget's configuration later by calling the update() method.

PropertyDescription
SwapWidgetConfigurationThe configuration type to be used with the Swap Widget.
import { checkout } from "@imtbl/sdk";

//@ts-ignore When creating the widget, pass in the configuration
const swap = widgets.create(checkout.WidgetType.SWAP, 
  { config: { theme: checkout.WidgetTheme.DARK }}
);

// Update the widget config by calling update()
swap.update({config: {theme: checkout.WidgetTheme.LIGHT}});

For more information on the configurations across all the Checkout Widgets (e.g. theme) review the Configuration section in our Setup page.

Events​

Swap widget events are emitted when critical actions have been taken by the user or key states have been reached. Below is a table of the possible events for the Swap Widget.

Event TypeDescriptionEvent Payload
SwapEventType.SUCCESSA user successfully connected their wallet.SwapSuccess
SwapEventType.FAILUREThere was a problem when swapping tokens.SwapFailed
SwapEventType.REJECTEDThe swap transaction was rejected.SwapRejected
SwapEventType.CLOSE_WIDGETThe user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function.

All the widget events are emitted with type IMTBL_SWAP_WIDGET_EVENT.

Access the event types via the key (e.g. checkoutWidgets.SwapEventType.SUCCESS, checkoutWidgets.SwapEventType.CLOSE_WIDGET).

import { checkout } from "@imtbl/sdk";

// @ts-ignore
const swap = widgets.create(checkout.WidgetType.SWAP, 
  { config: { theme: checkout.WidgetTheme.DARK }}
);

// add event listeners for the swap widget
swap.addListener(checkout.SwapEventType.SUCCESS, (data: checkout.SwapSuccess) => {
  console.log("success", data);
});

swap.addListener(checkout.SwapEventType.FAILURE, (data: checkout.SwapFailed) => {
  console.log("failure", data);
});

swap.addListener(checkout.SwapEventType.REJECTED, (data: checkout.SwapRejected) => {
  console.log("failure", data);
});

swap.addListener(checkout.SwapEventType.CLOSE_WIDGET, () => {
  swap.unmount();
});

// remove event listeners for the swap widget
swap.removeListener(checkout.SwapEventType.SUCCESS);

swap.removeListener(checkout.SwapEventType.FAILURE);

swap.removeListener(checkout.SwapEventType.REJECTED);

swap.removeListener(checkout.SwapEventType.CLOSE_WIDGET);

Sample code​

This sample code gives you a good starting point for integrating the connect widget into your application and listening to its events.

import { useEffect, useState } from 'react';
import { checkout } from '@imtbl/sdk';

 // create Checkout SDK
 const checkoutSDK = new checkout.Checkout();

export function App() {
 const [swap, setSwap] =
 useState<checkout.Widget<typeof checkout.WidgetType.SWAP>>();
  
 // Initialise widgets, create swap widget
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const swap = widgets.create(checkout.WidgetType.SWAP, { config: { theme: checkout.WidgetTheme.DARK }})
      setSwap(swap)     
    })();
  }, []);

  // mount swap widget and add event listeners
  useEffect(() => {
    if(!swap) return;

    swap.mount("swap");

    swap.addListener(checkout.SwapEventType.SUCCESS, (data: checkout.SwapSuccess) => {
      console.log("success", data);
    });
    swap.addListener(checkout.SwapEventType.FAILURE, (data: checkout.SwapFailed) => {
      console.log("failure", data);
    });
    swap.addListener(checkout.SwapEventType.REJECTED, (data: checkout.SwapRejected) => {
      console.log("rejected", data);
    });
    swap.addListener(checkout.SwapEventType.CLOSE_WIDGET, () => {
      swap.unmount();
    });
  }, [swap])


  return (<div id="swap" />);
}