> ## 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.

# Fund

Guide users to add specific tokens to their wallet, combining swap, bridge, and onramp options in one interface.

![Fund Widget](https://mintcdn.com/immutable-b818fae7/a-_df05Z16XVB-P7/images/checkout/top-up.webp?fit=max\&auto=format\&n=a-_df05Z16XVB-P7\&q=85\&s=99e049a265f21349c9eac68fdee62de8)

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

> [tab] npm
>
> ```bash theme={null}
> npm install @imtbl/sdk
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add @imtbl/sdk
> ```

## Quick Start

```typescript theme={null}
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',
  },
});
```

```typescript theme={null}
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

| Parameter | Type | Description |
| - | - | - |
| `flow` | `'ADD_TOKENS'` | Required. Specifies the fund flow |
| `toTokenAddress` | `string` | Target token to acquire |
| `toAmount` | `string` | Amount of target token needed |
| `showBackButton` | `boolean` | Show 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

| Event | Description | Payload |
| - | - | - |
| `SUCCESS` | Tokens acquired | `{ method, token, amount }` |
| `FAILURE` | Acquisition failed | `{ error }` |
| `CLOSE` | User 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

> [card] [Primary Sales](https://docs.immutable.com/docs/products/checkout/sale.md)
>
> Combine funding with NFT purchases

> [card] [Swap](https://docs.immutable.com/docs/products/checkout/swap.md)
>
> Direct token swaps


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.