Skip to main content
Guide users to add specific tokens to their wallet, combining swap, bridge, and onramp options in one interface. Fund Widget When to use:
  • User needs a specific token for a purchase
  • Pre-transaction funding when balance is insufficient
  • Helping users get the right currency for your game

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',
  },
});

// Fund flow - get specific tokens via swap, bridge, or onramp
export async function fundToken(
  elementId: string,
  options: {
    toTokenAddress: string;
    toAmount: string;
  }
) {
  const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
  const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);

  widget.mount(elementId, {
    flow: CommerceFlowType.ADD_TOKENS,
    toTokenAddress: options.toTokenAddress,
    toAmount: options.toAmount,
  });

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

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

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

  return widget;
}

Parameters

ParameterTypeDescription
flow'ADD_TOKENS'Required. Specifies the fund flow
toTokenAddressstringTarget token to acquire
toAmountstringAmount of target token needed
showBackButtonbooleanShow back button

How It Works

The Fund flow analyzes the user’s current balances and presents the best options:
User needs 100 USDC

Check wallet balances

┌─────────────────────────────────────────┐
│ Options presented to user:              │
│ • Swap 150 IMX → 100 USDC (if has IMX)  │
│ • Bridge USDC from Ethereum (if has)    │
│ • Buy 100 USDC with card                │
└─────────────────────────────────────────┘

User completes preferred flow

Events

EventDescriptionPayload
SUCCESSTokens acquired{ method, token, amount }
FAILUREAcquisition failed{ error }
CLOSEUser closed widget
The method field indicates how tokens were acquired: 'swap', 'bridge', or 'onramp'.

Use Case: Insufficient Balance

A common pattern is triggering the Fund flow when a user tries to make a purchase but lacks sufficient tokens. See the PurchaseWithFunding component in the code snippets above.

Next Steps