Skip to main content

​
Bridge

Move tokens from Ethereum mainnet to Immutable Chain. Bridge Widget When to use:
  • Bringing ETH or ERC-20 tokens to Immutable Chain
  • Players have assets on Ethereum they want to use in-game
  • L1 to L2 asset migration

​
Overview

The bridge widget enables players to transfer tokens between Ethereum L1 and Immutable zkEVM L2. The widget uses different bridge providers based on optimal routes: The widget automatically selects the best bridge provider based on the token being transferred and current network conditions.
Token Allowlisting Required: Only verified/allowlisted ERC-20 tokens will display on the swap and bridge widgets. Tokens must complete the Asset Verification procedure before they can be swapped or bridged.Contact Developer Support for allowlisting inquiries and token standards information.

​
Prerequisites

Install the Immutable SDK: 
npm install @imtbl/sdk

​
Quick Start

import { checkout } from '@imtbl/sdk';
import { Environment } from '@imtbl/sdk/config';

const { Checkout, WidgetType, WidgetTheme } = checkout;

const checkoutSDK = new Checkout({
  baseConfig: {
    environment: Environment.SANDBOX, // or Environment.PRODUCTION
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  },
});

const { CommerceFlowType, CommerceEventType } = checkout;

// Basic bridge flow
export async function openBridge(elementId: string) {
  const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
  const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);

  widget.mount(elementId, { flow: CommerceFlowType.BRIDGE });

  widget.addListener(CommerceEventType.SUCCESS, (data) => {
    console.log('Bridge initiated:', data);
    widget.unmount();
  });

  widget.addListener(CommerceEventType.FAILURE, (data) => {
    console.error('Bridge failed:', data);
    widget.unmount();
  });

  widget.addListener(CommerceEventType.CLOSE, () => {
    widget.unmount();
  });

  return widget;
}

// Bridge with pre-filled token and amount
export async function bridgeWithAmount(
  elementId: string,
  options: {
    tokenAddress: string;
    amount: string;
  }
) {
  const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
  const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);

  widget.mount(elementId, {
    flow: CommerceFlowType.BRIDGE,
    tokenAddress: options.tokenAddress,
    amount: options.amount,
  });

  return widget;
}

​
Parameters

ParameterTypeDescription
flow'BRIDGE'Required. Specifies the bridge flow
tokenAddressstringOptional. Token to bridge (Ethereum address)
amountstringOptional. Amount to bridge

​
Events

EventDescriptionPayload
SUCCESSBridge initiated{ transactionHash, fromToken, toToken, fromAmount, toAmount }
FAILUREBridge failed{ error }
CLOSEUser closed widget—

​
Next Steps

Swap

Exchange tokens after bridging

Onramp

Buy crypto with fiat

Primary Sales

Sell NFTs to players

Build a Marketplace

Complete marketplace tutorial