Skip to main content
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

Installation

npm install @imtbl/sdk

Quick Start

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

const { Checkout, WidgetType, WidgetTheme, CommerceFlowType, CommerceEventType } = checkout;

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

// Common token addresses
export const TOKENS = {
  mainnet: {
    IMX: 'NATIVE',
    USDC: '0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d2',
    ETH: '0x52a6c53869ce09a731cd772f245b97a4401d3348',
  },
  testnet: {
    IMX: 'NATIVE',
    USDC: '0x3B2d8A1931736Fc321C24864BceEe981B11c3c57',
    ETH: '0xe9E96d1aad82562b7588F03f49aD34186f996478',
  },
} as const;

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

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

  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
amountstringPre-fill swap amount
fromTokenAddressstringToken to swap from ('NATIVE' for IMX)
toTokenAddressstringToken to swap to ('NATIVE' for IMX)
direction'FROM' | 'TO'Whether amount is “from” or “to” value
autoProceedbooleanSkip form and proceed directly
showBackButtonbooleanShow back button (triggers REQUEST_GO_BACK)

Events

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

Supported Tokens

Swaps are powered by QuickSwap. Any token with liquidity on QuickSwap is supported.
Common tokens on Immutable Chain:
TokenMainnet AddressTestnet Address
IMXNativeNative
USDC0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d20x3B2d8A1931736Fc321C24864BceEe981B11c3c57
ETH (wrapped)0x52a6c53869ce09a731cd772f245b97a4401d33480xe9E96d1aad82562b7588F03f49aD34186f996478
If a token doesn’t appear in the swap widget, it may not have sufficient liquidity on QuickSwap. Request token listing.

Next Steps