Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.immutable.com/llms.txt

Use this file to discover all available pages before exploring further.

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