1. Setting up your ERC‑20 token on Immutable zkEVM

This guide will walk you through the required steps to enable using your existing ERC‑20 token on Immutable zkEVM.

If you haven’t already launched your project’s ERC‑20 token on another blockchain, you should read our guide on Launching a new ERC‑20 token on zkEVM instead.

💡Who is this guide for?

Developers who have an existing ERC-20 token on another compatible blockchain and want it to be usable on Immutable zkEVM.

The process of moving tokens between blockchain networks is called bridging. Currently, Immutable offers a Bridge Widget, that developers can integrate in their applications which allows players to transfer tokens between Ethereum and Immutable zkEVM.

How does bridging work?

Immutable's bridge works by locking tokens sent to it on Ethereum in escrow, and then minting the corresponding amount on Immutable zkEVM to the requested address. Inversely, when moving from Immutable zkEVM to Ethereum, the tokens that are sent to the bridge are burned on Immutable zkEVM and then unlocked on Ethereum.

💡Don't manually deploy your token

The representation of your ERC-20 token on Immutable zkEVM must be deployed using the steps outlined in this guide which also links the Immutable zkEVM token to your existing token on it's original chain. Do NOT deploy your own token with the same metadata on Immutable zkEVM, ensure you follow these instructions instead.

Recommended mapping with ITS

It is now possible to enable bridging of ERC-20 tokens from Ethereum or non-Ethereum chains directly to Immutable zkEVM, using Axelar's Interchain Token Service (ITS). This service takes any ERC-20 token on a supported blockchain and allows you to deploy it across multiple chains (in this case, Immutable zkEVM), which then enables your users to bridge the token with Squid.

ITS is permissionless and takes a maximum of 20 minutes, but is usually much faster.

💡EVM compatible and Cosmos based chains

Axelar's ITS portal is available for tokens originating on EVM compatible and Cosmos based blockchains.

Eligibility

This approach to bridging is applicable to game tokens where:

• The token originates on one of the 60+ chains supported by Axelar, including Ethereum.
• The token is launched on the chain's Mainnet and is actively traded with a public market price.
• The token being registered is the original token, and not a bridged, wrapped or synthetic representation of the token.
• The token is not already deployed to Immutable zkEVM by some other form (i.e. through Immutable's Bridge contract). This would result in fragmented liquidity and duplicate representations of your token on Immutable zkEVM.

How to enable bridging with ITS

Before any tokens can be bridged, Axelar's ITS service needs to deploy the ERC‑20 equivalent of your token onto Immutable zkEVM and any other blockchains you select.

This ensures the contracts on each chain can interact with the ITS service and have the required functionality to facilitate interchain token transfers.

To get started, navigate to Axelar's ITS Portal and follow the steps below.

💡Deploy a new ERC-20 token

If you do not already have an ERC-20 token, Axelar's ITS service allows you to create and deploy a new ERC-20 token on multiple chains. Please refer to Axelar's documentation for this feature.

1. Connect your wallet

Click "Connect Wallet" and select your wallet provider (eg. Metamask). Follow any approval prompts. You may be required to switch networks, in which case you should switch to the network where your ERC-20 token originates.

2. Search for your token

Search for your ERC-20 token using its contract address. Ensure you have selected the correct chain (the origin chain of your ERC-20 token).

Confirm details such as the name, symbol, decimals and token address. Once you have done this, click "Register interchain token".

3. Select chains to bridge

Choose all the chains you want to bridge your ERC-20 token to. Ensure you select Immutable.

4. Deploy your ERC-20 token

Deploy your ERC-20 token to the selected chains by clicking "Register & Deploy on 2 chains" at the bottom of the page. You will be asked to confirm this with a pop-up from your Browser wallet and will need to pay gas fees.

5. Review and confirm

Your ERC-20 token has now been bridged to Immutable zkEVM. After initialization, deployment to Immutable zkEVM could take up to 20 minutes.

6. Add to Squid

Finally, to enable users to bridge your ERC-20 token from its origin chain to Immutable zkEVM, you must add your token to Squid in order for it to show up on a user interface.

Alternative mapping from Ethereum

If mapping with ITS is not possible and your ERC-20 token originates on Ethereum, you are also able to map your token to Immutable zkEVM by deploying Immutable's Bridge contract.

Before any tokens can be bridged, Immutable's Bridge contract needs to deploy the ERC‑20 equivalent of your token onto Immutable zkEVM and link (or map) the token pair together. This ensures the bridge knows which token should be issued on the destination chain when it receives a token on the origin chain.

💡Don't deploy multiple tokens

Please ensure that your token is not already deployed on Immutable zkEVM by some other form (eg. through Axelar's Interchain Token Service (ITS)).

To enable bridging you will need to follow these steps;

1. Call the mapToken method on our Ethereum bridge contract, this will deploy and link your token on Immutable zkEVM. The mapToken method takes the following parameters;

Parameters	Type	Description	Examples
rootToken	address	This is the address of your ERC‑20 token contract on Ethereum.
payableAmount	ether	This is the amount of ETH you will be paying to execute this action on the bridge.

• The easiest way to call this method is through Etherscan's write proxy, but it will require a web wallet, like metamask, with some balance to connect then pay the fees and gas.

• We suggest setting payableAmount to 0.001 ETH to ensure the mapping is processed. Any over payment will be refunded once the process is complete.

• Once you've confirmed the mapToken transaction through your web wallet, you can look the transaction ID up on Axelarscan to watch the progress of the bridge transaction.

• Once the transaction has gone through all the stages and shows Executed the zkEVM token should be deployed and the mapping complete.

2. Once your token is mapped, you will need to fetch the contract address of your newly created token on Immutable zkEVM by calling the Bridge method rootTokenToChildToken which takes the following parameters;

Parameters	Type	Description	Examples
input	address	This is the address of your ERC‑20 token contract on Ethereum.

• Again, the easiest way to call this method is through Etherscan's read proxy and there are no fees required to do this.

• The rootTokenToChildToken method returns the address the bridge gave to your token on Immutable zkEVM. You should be able to look it up on Blockscout to confirm it exists and the metadata are correct.

Your token can now technically be bridged from Ethereum to Immutable zkEVM. However it still needs to be added to the Commerce Widget Bridge Flow so it will appear in the list of available tokens for players to bridge.

💡What's upcoming

Soon we will be releasing an application form for this inside Immutable Hub, but for now you will need to reach out to support on Discord if you would like your token added to the Bridge Flow.

Mapping from Immutable X

If your token is being mapped from ImmutableX (StarkEx), these tokens originate from Ethereum. All tokens on ImmutableX need to be withdrawn by the game and/or token holders then bridged to Immutable zkEVM by following one of the processes above.

Mapping from non-EVM compatible blockchains

Mapping from other blockchains which are not EVM compatible is not currently supported.

💡Next steps

Next, you'll need to link your ERC-20 token in Immutable Hub by following the next guide in this section.