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 } = checkout;

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

const { CommerceFlowType, CommerceEventType } = checkout;

// 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

Primary Sales

Combine funding with NFT purchases

Swap

Direct token swaps