> ## 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.
**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
```bash theme={null}
npm install @imtbl/sdk
```
```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
Combine funding with NFT purchases
Direct token swaps