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.
Swap
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
Overview
The swap widget, powered by QuickSwap , facilitates token exchanges on Immutable zkEVM. QuickSwap is a decentralized exchange (DEX) that provides liquidity for token swaps on Immutable Chain.
Any allowlisted token with liquidity on QuickSwap is supported. The widget automatically routes swaps through the most efficient liquidity pools to minimize slippage and transaction costs.
Token Allowlisting Required: Only verified/allowlisted ERC-20 tokens will display on the swap and bridge widgets. Tokens must complete the Asset Verification procedure before they can be swapped or bridged.Contact Developer Support for allowlisting inquiries and token standards information.
Prerequisites
Install the Immutable 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 ;
// Basic swap: swap to USDC
export async function openSwap ( elementId : string ) {
const widgets = await checkoutSDK . widgets ({ config: { theme: WidgetTheme . DARK } });
const widget = widgets . create ( WidgetType . IMMUTABLE_COMMERCE );
widget . mount ( elementId , {
flow: CommerceFlowType . SWAP ,
toTokenAddress: '0x3B2d8A1931736Fc321C24864BceEe981B11c3c57' , // USDC testnet
});
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 fromTokenAddressstringOptional. Token to swap from toTokenAddressstringRequired. Token to swap to amountstringOptional. Amount to swap
Events
Event Description Payload SUCCESSSwap completed { transactionHash, fromToken, toToken, fromAmount, toAmount }FAILURESwap failed { error }CLOSEUser closed widget —
Common tokens
Token Mainnet Address Testnet Address IMX NATIVENATIVEUSDC 0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d20x3B2d8A1931736Fc321C24864BceEe981B11c3c57wETH 0x52a6c53869ce09a731cd772f245b97a4401d33480xe9E96d1aad82562b7588F03f49aD34186f996478
Next Steps
Onramp Buy tokens with fiat
Bridge Transfer from Ethereum
Primary Sales Sell NFTs to players
Build a Marketplace Complete marketplace tutorial