Skip to main content

Fund user wallets

Sections

Funding methods​

In order for users to fully participate in a game economy, such as by purchasing items, paying for transactions or trading with other users, they need to have the game's native currency, or other game-accepted currencies, in the wallets they have connected to the game. We have developed the Commerce Widget as an easy to use tool designed to facilitate this process.

FlowUse case
Add tokensThe ADD TOKENS flow is ideal for users who have funds on other chains and are looking to move some of the funds to zkEVM. This flow also includes an onramp option, to fund their zkEVM wallets using fiat (e.g. EUR).

💡Example
An item is sold on zkEVM for 2 USDC and I have 2 USDC in Polygon PoS that I'd love to use for purchasing the item. I can use the Commerce widget to add 2 USDC tokens from Polygon PoS to my zkEVM wallet.
BridgeThe BRIDGE flow is ideal for users who have funds on L1 (e.g. Ethereum) and are looking to move some of the funds to zkEVM.

💡Example
An item is sold on zkEVM for 0.2 USDC and I have 3 USDC in my L1 wallet that I'd love to use for purchasing the item. I can use the Checkout widget to bridge my L1 USDC tokens to L2 and complete the purchase.
SwapThe SWAP flow is ideal for users who have funds on zkEVM and are looking to swap tokens (e.g. USDC for IMX).

💡Example
An item is sold on zkEVM for 0.2 USDC and I already have 4 ETH in my zkEVM wallet that I'd love to use for purchasing the item. I can use the Checkout widget to swap my ETH tokens for USDC tokens and complete the purchase.
On‑rampThe ONRAMP flow is idea for users who want to funds their zkEVM wallets using fiat (e.g. EUR).

💡Example
An item is sold on zkEVM for 0.2 USDC and I do not have any funds on zkEVM on L1 (e.g. Ethereum). I can use the Checkout widget to purchase USDC tokens using my Credit Card/Apple Pay/Google Pay and complete the purchase.

Setup​

note

The Commerce Widget is designed to be used client-side only and can be installed via CDN or package manager.

Prerequisites​

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
Troubleshooting

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

Add tokens​

The ADD TOKENS flow is ideal for users who have funds on other chains and are looking to move some of the funds to zkEVM. The sample code code below gives a starting point for integrating the widget into your application.

add tokens widgetadd tokens widget
import { useEffect } from 'react';
import { checkout } from '@imtbl/sdk';

// Create a Checkout SDK instance
const checkoutSDK = new checkout.Checkout();

export function App() {
  // Initialise the Commerce Widget
  useEffect(() => {
    (async () => {
      // Create a factory
      const factory = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK, language: 'en' },
      });

      // Create a widget
      const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE);

      // Mount a ADD TOKENS flow, optionally pass any AddTokensWidgetParams
      widget.mount('mount-point', {
        flow: checkout.CommerceFlowType.ADD_TOKENS,
      });
    })();
  }, []);

  return <div id="mount-point" />;
}

To learn more about this widget explore the Add Tokens documentation.


Bridge​

Bridges facilitate communication between blockchains through the transfer of information and assets. The sample code code below gives a starting point for integrating the widget into your application.

💡Test ETH
Obtain test ETH from the Sepolia Faucet to test the BRIDGE flow.

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

// Create a Checkout SDK instance
const checkoutSDK = new checkout.Checkout();

export function App() {
  // Initialise the Commerce Widget
  useEffect(() => {
    (async () => {
      // Create a factory
      const factory = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK, language: 'en' },
      });

      // Create a widget
      const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE);

      // Mount a bridge flow, optionally pass any BridgeWidgetParams
      widget.mount('mount-point', {
        flow: checkout.CommerceFlowType.BRIDGE,
      });
    })();
  }, []);

  return <div id="mount-point" />;
}

To learn more about this widget explore the Bridge tokens documentation.


Swap​

A token swap refers to exchanging one cryptocurrency token directly for another without using fiat money (e.g. USD). The sample code code below gives a starting point for integrating the widget into your application.

💡Test-IMX
Obtain Test-IMX from the Immutable Faucet to test the SWAP flow.

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

// Create a Checkout SDK instance
const checkoutSDK = new checkout.Checkout();

export function App() {
  // Initialise the Commerce Widget
  useEffect(() => {
    (async () => {
      // Create a factory
      const factory = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK, language: 'en' },
      });

      // Create a widget
      const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE);

      // Mount a SWAP flow, optionally pass any SwapWidgetParams
      widget.mount('mount-point', {
        flow: checkout.CommerceFlowType.SWAP,
      });
    })();
  }, []);

  return <div id="mount-point" />;
}

To learn more about this widget explore the Swap Tokens documentation.


On-ramp​

On-ramping tokens refers to exchanging fiat currency (e.g. USD) directly to buy cryptocurrency. The sample code code below gives a starting point for integrating the ONRAMP flow into your application.

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

// Create a Checkout SDK instance
const checkoutSDK = new checkout.Checkout();

export function App() {
    // Initialise the Commerce Widget
    useEffect(() => {
        (async () => {
            // Create a factory
            const factory = await checkoutSDK.widgets({
                config: { theme: checkout.WidgetTheme.DARK, language: 'en' },
            });

            // Create a widget
            const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE);

            // Mount an onramp flow, optionally pass any OnrampWidgetParams
            widget.mount('mount-point', {
                flow: checkout.CommerceFlowType.ONRAMP,
            });
        })();
    }, []);

    return <div id="mount-point" />;
}

To learn more about this widget explore the On-ramp tokens documentation.

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