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

# Swap

Exchange tokens on Immutable Chain via QuickSwap.

<img src="https://mintcdn.com/immutable-b818fae7/a-_df05Z16XVB-P7/images/checkout/swap.webp?fit=max&auto=format&n=a-_df05Z16XVB-P7&q=85&s=42f3a559c88e740ba4e680c26944a346" alt="Swap Widget" noZoom style={{float: 'right', width: '200px', borderRadius: '8px', marginLeft: '24px', marginBottom: '16px'}} width="860" height="1300" data-path="images/checkout/swap.webp" />

**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](https://quickswap.exchange/), 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.

<Warning>
  **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](https://support.immutable.com/) for allowlisting inquiries and token standards information.
</Warning>

***

## Prerequisites

Install the Immutable SDK:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @imtbl/sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @imtbl/sdk
    ```
  </Tab>
</Tabs>

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

// 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 |
| `fromTokenAddress` | `string` | Optional. Token to swap from      |
| `toTokenAddress`   | `string` | Required. Token to swap to        |
| `amount`           | `string` | Optional. Amount to swap          |

### Events

| Event     | Description        | Payload                                                         |
| --------- | ------------------ | --------------------------------------------------------------- |
| `SUCCESS` | Swap completed     | `{ transactionHash, fromToken, toToken, fromAmount, toAmount }` |
| `FAILURE` | Swap failed        | `{ error }`                                                     |
| `CLOSE`   | User closed widget | —                                                               |

***

## Common tokens

| Token | Mainnet Address                              | Testnet Address                              |
| ----- | -------------------------------------------- | -------------------------------------------- |
| IMX   | `NATIVE`                                     | `NATIVE`                                     |
| USDC  | `0x6de8aCC0D406837030CE4dd28e7c08C5a96a30d2` | `0x3B2d8A1931736Fc321C24864BceEe981B11c3c57` |
| wETH  | `0x52a6c53869ce09a731cd772f245b97a4401d3348` | `0xe9E96d1aad82562b7588F03f49aD34186f996478` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Onramp" icon="credit-card" href="/docs/products/checkout/onramp">
    Buy tokens with fiat
  </Card>

  <Card title="Bridge" icon="bridge" href="/docs/products/checkout/bridge">
    Transfer from Ethereum
  </Card>

  <Card title="Primary Sales" icon="tag" href="/docs/products/checkout/primary-sales">
    Sell NFTs to players
  </Card>

  <Card title="Build a Marketplace" icon="store" href="/docs/guides/build-a-marketplace">
    Complete marketplace tutorial
  </Card>
</CardGroup>