Skip to main content
Deprecation Notice

As of v1.61.0, Wallet widget has been moved into the Commerce Widget. Please visit the new wallet page for details.

View balances

The Wallet widget is a drop-in solution for web-based games and marketplaces that simplifies the process of checking wallet balances on the Immutable zkEVM and Ethereum networks as well as accessing the bridging and swapping features.

Sections
Wallet widgetWallet widget
💡Allowlisted tokens
Only tokens that have been verified will be displayed on the widgets. To allowlist an ERC20 token please follow our Asset Verification procedure.
For additional questions, please contact our support team on Discord.

Getting started​

Once you have completed the widget setup, use the WidgetsFactory to create a wallet widget. In order to mount the widget, call the mount() function and pass in the id attribute of the target element you wish 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 wallet widget and mount
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const wallet = widgets.create(checkout.WidgetType.WALLET)
      wallet.mount("wallet");
    })();
  }, []);

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

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.

ParameterDescription
walletProviderNameThe name of the wallet provider to use.

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
WalletWidgetConfigurationThe configuration type to be used with the Wallet Widget.
import { checkout } from "@imtbl/sdk";

// @ts-ignore When creating the widget, pass in the configuration
const wallet = widgets.create(checkout.WidgetType.WALLET, { 
  config: { 
    theme: checkout.WidgetTheme.DARK
  },
  walletConfig: {
    showNetworkButton: true,
    showDisconnectButton: true
  }
});

// Update the widget config by calling update()
wallet.update({
  config: {
    theme: checkout.WidgetTheme.LIGHT
  },
  walletConfig: {
    showNetworkButton: false,
    showDisconnectButton: false
  }
});

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

Events​

Wallet 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 Wallet Widget.

Event TypeDescriptionEvent Payload
WalletEventType.NETWORK_SWITCHA user switched their network from the wallet.WalletNetworkSwitch
WalletEventType.DISCONNECT_WALLETThe user disconnected their wallet.WalletDisconnect
WalletEventType.CLOSE_WIDGETThe user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function.

You can use the addListener() function to tap into the events and provider handlers. Use the removeListener() function to stop listening to that event.

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

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

// add event listeners for the wallet widget
wallet.addListener(checkout.WalletEventType.NETWORK_SWITCH, (data: checkout.WalletNetworkSwitch) => {
  console.log("network switch", data);
});

wallet.addListener(checkout.WalletEventType.DISCONNECT_WALLET, (data: checkout.WalletDisconnect) => {
  console.log("wallet disconnected", data);
});

wallet.addListener(checkout.WalletEventType.CLOSE_WIDGET, () => {
  wallet.unmount();
});

// remove event listeners for the wallet widget
wallet.removeListener(checkout.WalletEventType.NETWORK_SWITCH);

wallet.removeListener(checkout.WalletEventType.DISCONNECT_WALLET);

wallet.removeListener(checkout.WalletEventType.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 [wallet, setWallet] =
 useState<checkout.Widget<typeof checkout.WidgetType.WALLET>>();
  
 // Initialise widgets, create wallet widget
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const wallet = widgets.create(checkout.WidgetType.WALLET, {config: {theme: checkout.WidgetTheme.DARK}})
      setWallet(wallet)     
    })();
  }, []);

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

    wallet.mount("wallet");

    wallet.addListener(checkout.WalletEventType.NETWORK_SWITCH, (data: checkout.WalletNetworkSwitch) => {
      console.log("network switch", data);
    });
    
    wallet.addListener(checkout.WalletEventType.DISCONNECT_WALLET, (data: checkout.WalletDisconnect) => {
      console.log("wallet disconnected", data);
    });
    
    wallet.addListener(checkout.WalletEventType.CLOSE_WIDGET, () => {
      wallet.unmount();
    });

  }, [wallet])

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

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us