Skip to main content


This guide will walk you through how to install and setup the Checkout widgets for your application.

Install Checkout

The Checkout Widgets can be included in your application by first installing the SDK in one of two different ways:

  1. Install the npm module and import the Checkout SDK
  • or...
  1. Load the SDK via a CDN by pasting a script tag into your application.

The Checkout Widgets will be loaded dynamically as a separate bundle into your application when you create the Checkout instance and call the widgets() function.


Node Version 20 or later
Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

To install nvm follow these instructions. Once installed, run:

nvm install --lts
  • (Optional) To enable Code Splitting (importing only the SDK modules you need) there are additional prerequisites.

Install the Immutable SDK

Run the following command in your project root directory.

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node

The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:

rm -Rf node_modules
npm cache clean --force
npm i


Checkout widgets are designed to be used on the client-side only. The window and document objects are required.

The following code snippet shows the recommened way to intiaise and create the widgets:

  1. You must create an instance of the Checkout SDK first
  2. We recommend initialising the widgets at the beginning of your application
  3. We recommend creating all of the widgets that you need in your app at the beginning of your application

This ensures that all widgets are correctly synced with the provider once the user connects their wallet.

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

// Create an instance of the Checkout SDK and configure the environment SANDBOX / PRODUCTION
const checkoutSDK = new checkout.Checkout({
baseConfig: {environment: config.Environment.SANDBOX },
bridge: { enable: true },
swap: { enable: true },
onRamp: { enable: true }

export const App = () => {
useEffect(() => {
(async () => {
// Get an instance of the widgets factory to be able to create widgets
const widgets = await checkoutSDK.widgets({
config: { theme: checkout.WidgetTheme.DARK },

// RECOMMENDED - create all of the widgets once at the start of your application
// use the created widgets throughout your application to mount and unmount in specific parts of your application
const connect = widgets.create(checkout.WidgetType.CONNECT);
const wallet = widgets.create(checkout.WidgetType.WALLET); // you can optionally pass in additional config per widget
const swap = widgets.create(checkout.WidgetType.SWAP);
const bridge = widgets.create(checkout.WidgetType.BRIDGE);
const onramp = widgets.create(checkout.WidgetType.ONRAMP);

// Mount the wallet widget passing the element id of where to mount the widget
}, []);

return (<div id="wallet" />);

Widget configuration & versioning

The checkout.widgets() function can be provided config and a version, which can be used to configure the theme and the specific version to use.

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

const checkoutSDK = new checkout.Checkout();

// @ts-ignore
const widgets = await checkoutSDK.widgets({
config: {
theme: checkout.WidgetTheme.DARK
version: {
major: 1,
minor: 2,
patch: 3,
configThe config object can be used to configure the widgets. This is currently used to set the theme.
versionThe Checkout Widgets follow the Semantic Versioning as per the Immutable SDK package. The SDK automatically downloads the latest version of the widgets library. A different version can be optionally provided than the one loaded as part of the NPM package.

Bundle loading

The Checkout Widgets are built and released with every new Immutable SDK release following the Immutable SDK versioning. Minor patches are automatically applied to ensure continued and seamless improvements to the product for our partners, as our SDK will load the widgets bundle from when checkout.widgets() is called. If a specific version is required then the version can be set when calling checkout.widgets().


Only minor and patch versions are seamlessly applied to prevent disruptions in your application.

Widget factory

The checkout.widgets() function returns a widget factory object that can be used to create any widget or update the provider.

create(type, props)type: the widget type to instantiate
props: the widget configurations and provider to create the widget
To create a specific widget
updateProvider(provider)provider: the Web3Provider object to update all the widgetsTo update the wallet provider. This will be reflected on all created widgets
import { Web3Provider } from "@ethersproject/providers";
import { checkout } from "@imtbl/sdk";

const checkoutSDK = new checkout.Checkout();

// @ts-ignore
const widgets = await checkoutSDK.widgets({config: {theme: checkout.WidgetTheme.DARK}});
// Create a wallet widget using the factory
const wallet = widgets.create(checkout.WidgetType.WALLET);

// @ts-ignore - Update provider
widgets.updateProvider(new Web3Provider(provider));

Widget interface

mount(id, params)id: ID of the DOM element where the widget will be mounted
params: the specific widget parameters
Mount a widget to a DOM reference element
unmount()Unmount a widget and reset parameters
update(props)props: the widget specific properties including configuration and provider to be updatedUpdate the widget configuration
addListener(type, callback)type: the widget specific event name
callback:(data): function to execute when the event is received
Add a listener for a widget event
removeListener(type)type: the widget specific event nameRemoves an event listener for a widget event

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us