Skip to main content

Swap

Exchange tokens on Immutable Chain via QuickSwap. Swap Widget When to use:
  • Players need a specific token for in-game purchases
  • Converting between game currencies
  • Exchanging tokens before marketplace transactions

Overview

The swap widget, powered by QuickSwap, facilitates token exchanges on Immutable zkEVM. QuickSwap is a decentralized exchange (DEX) that provides liquidity for token swaps on Immutable Chain. Any allowlisted token with liquidity on QuickSwap is supported. The widget automatically routes swaps through the most efficient liquidity pools to minimize slippage and transaction costs.
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 swap: swap to USDC
export async function openSwap(elementId: string) {
  const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
  const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);

  widget.mount(elementId, {
    flow: CommerceFlowType.SWAP,
    toTokenAddress: '0x3B2d8A1931736Fc321C24864BceEe981B11c3c57', // USDC testnet
  });

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

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

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

  return widget;
}

// Swap with pre-filled values
export async function swapWithAmount(
  elementId: string,
  options: {
    fromTokenAddress?: string;
    toTokenAddress: string;
    amount: string;
  }
) {
  const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
  const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);

  widget.mount(elementId, {
    flow: CommerceFlowType.SWAP,
    fromTokenAddress: options.fromTokenAddress || 'NATIVE',
    toTokenAddress: options.toTokenAddress,
    amount: options.amount,
  });

  return widget;
}

Parameters

ParameterTypeDescription
flow'SWAP'Required. Specifies the swap flow
fromTokenAddressstringOptional. Token to swap from
toTokenAddressstringRequired. Token to swap to
amountstringOptional. Amount to swap

Events

EventDescriptionPayload
SUCCESSSwap completed{ transactionHash, fromToken, toToken, fromAmount, toAmount }
FAILURESwap failed{ error }
CLOSEUser closed widget

Common tokens

TokenMainnet AddressTestnet Address
IMXNATIVENATIVE
USDC0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d20x3B2d8A1931736Fc321C24864BceEe981B11c3c57
wETH0x52a6c53869ce09a731cd772f245b97a4401d33480xe9E96d1aad82562b7588F03f49aD34186f996478

Next Steps