Exchange tokens on Immutable Chain via QuickSwap.
When to use:
- Players need a specific token for in-game purchases
- Converting between game currencies
- Exchanging tokens before marketplace transactions
Installation
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',
},
});
// Common token addresses
export const TOKENS = {
mainnet: {
IMX: 'NATIVE',
USDC: '0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d2',
ETH: '0x52a6c53869ce09a731cd772f245b97a4401d3348',
},
testnet: {
IMX: 'NATIVE',
USDC: '0x3B2d8A1931736Fc321C24864BceEe981B11c3c57',
ETH: '0xe9E96d1aad82562b7588F03f49aD34186f996478',
},
} as const;
// Basic swap flow
export async function openSwap(elementId: string, toTokenAddress: string) {
const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);
widget.mount(elementId, {
flow: CommerceFlowType.SWAP,
toTokenAddress,
});
widget.addListener(CommerceEventType.SUCCESS, (data) => {
console.log('Swap complete:', data);
widget.unmount();
});
widget.addListener(CommerceEventType.FAILURE, (data) => {
console.error('Swap failed:', data);
widget.unmount();
});
widget.addListener(CommerceEventType.CLOSE, () => {
widget.unmount();
});
return widget;
}
// Swap with pre-filled values
export async function swapWithAmount(
elementId: string,
options: {
fromTokenAddress?: string;
toTokenAddress: string;
amount: string;
}
) {
const widgets = await checkoutSDK.widgets({ config: { theme: WidgetTheme.DARK } });
const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);
widget.mount(elementId, {
flow: CommerceFlowType.SWAP,
fromTokenAddress: options.fromTokenAddress || 'NATIVE',
toTokenAddress: options.toTokenAddress,
amount: options.amount,
});
return widget;
}
Parameters
| Parameter | Type | Description |
|---|
flow | 'SWAP' | Required. Specifies the swap flow |
amount | string | Pre-fill swap amount |
fromTokenAddress | string | Token to swap from ('NATIVE' for IMX) |
toTokenAddress | string | Token to swap to ('NATIVE' for IMX) |
direction | 'FROM' | 'TO' | Whether amount is “from” or “to” value |
autoProceed | boolean | Skip form and proceed directly |
showBackButton | boolean | Show back button (triggers REQUEST_GO_BACK) |
Events
| Event | Description | Payload |
|---|
SUCCESS | Swap completed | { transactionHash, fromToken, toToken, fromAmount, toAmount } |
FAILURE | Swap failed | { error } |
CLOSE | User closed widget | — |
Supported Tokens
Swaps are powered by QuickSwap. Any token with liquidity on QuickSwap is supported.
Common tokens on Immutable Chain:
| Token | Mainnet Address | Testnet Address |
|---|
| IMX | Native | Native |
| USDC | 0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d2 | 0x3B2d8A1931736Fc321C24864BceEe981B11c3c57 |
| ETH (wrapped) | 0x52a6c53869ce09a731cd772f245b97a4401d3348 | 0xe9E96d1aad82562b7588F03f49aD34186f996478 |
If a token doesn’t appear in the swap widget, it may not have sufficient liquidity on QuickSwap. Request token listing.
Next Steps