Skip to main content

Introduction

This page contains a list of frequently asked developer questions. The best way to use it is to search for a keyword.

info

Can't find your question? Visit dev-forum in Discord.

Useful Links

Platform

What is Immutable X (IMX)?​

Immutable X (later: IMX) is an L2 ZK Rollup solution for trading Ethereum NFTs. It features instant trades, massive scalability and no gas fees.

What's a Zero Knowledge (ZK) Rollup?​

Zero Knowledge Rollups are a Layer 2 scheme that moves computation off-chain, but provides L1 security by rolling up multiple transactions into a single one and submitting a validity proof back to L1. ZK Rollups only require a validity proof of the final state (instead of all transaction data) which makes them more private and storage-efficient. IMX uses StarkWare's ZK Rollup engine called StarkEx

What's StarkWare, StarkEx and Immutable zkEVM?

StarkWare - company behind STARK-based solutions

StarkEx - a managed SaaS scalability engine powered by STARK validity proof

Immutable zkEVM - a general purpose decentralized rollup which support independent smart contract deployment and composability

More information: Homepage - Starkware

What are the fees associated with using Immutable X?​

IMX has no fixed costs or fees. All fees are associated with successful trades. Current fees are:

  • Protocol fees - 2%
  • Maker fee - set by a marketplace
  • Taker fee - set by a marketplace
  • Royalty fee - set by the collection owner

More information:

How is asset custody managed in Immutable X?​

Immutable X is a self-custodial protocol, meaning all users are responsible for their own security. Users can manage their own private keys and maintain full control of their own assets, or opt for a custodial wallet flow. Users can deposit and withdraw their assets to and from the protocol at any time. Every transaction requires a signature from the user, and Immutable can’t authorise any actions on behalf of the user.

Contract

How do I deploy a contract to Immutable X?​

You do not deploy a contract to IMX, you can only register your L1 contract with IMX. Immutable X (on StarkEx) does not currently support general computation and you do not interface with your L1 contract through IMX.

This is something that will be possible on Immutable zkEVM.

More information on Immutable zkEVM: Immutable zkEVM

How do I interact with my contract on Immutable X?​

You do not. You interact with predefined Immutable APIs. These handle minting, transfers, deposits, withdrawals and more.

How do I get approved to launch on Immutable X?​

IMX is a permissionless protocol, anyone can launch a collection on it. You do not need to go through any approval processes or vetting - only our self-serve onboarding. More information: Immutable Documentation

What are the fees/costs associated with deploying on Immutable X?​

The only mandatory cost is deploying an L1 contract. This depends on the complexity of your contract, optimizations and current state of the (L1) network. All L2 actions which do not interact with the L1 (all, excl. withdrawals and deposits) are gas-free and free from any fixed costs.

What token standards are supported? Is ERC1155 supported?​

Immutable currently supports ERC721 and ERC20 token standards. There are no estimates or set plans when it comes to supporting other standards, but we are always looking into providing the most popular and efficient solutions for our users.

What are the contract-level requirements? How do I make my contract compatible?​

If you do not plan to mint on L2, any ERC721 or ERC20 contract with an owner is automatically supported by IMX. You will have to register it. If you wish to mint on L2, you will need to implement mintFor and owner methods.

More information and example contracts:

How do I deploy an ERC20 token?​

Self-serve registration of ERC20 tokens is coming soon.

Can I query L2 state from L1? There is no "traditional" way of querying L2 state from your L1 contract. A workaround would be to use Oracles in order to query our API.

More information: Oracles | ethereum.org

​

Onboarding

How do I register my project/collection after deploying a contract?​

After deploying your contract to L1, you will need to register it with IMX. In order to do this you will need to create a project and a collection by following the below steps.

Guide, steps and documentation:

Are there any onboarding limits?​

  • One (1) wallet can own multiple projects.
  • One (1) project can own multiple collections.
  • All projects are limited to 5 collections and 50,000 mint requests by default. This limit resets every 4 weeks and can be increased - if your project meets our criteria - by contacting support .

More information: Immutable Documentation

How do I delete my collection from Immutable X?​

As is the case with L1, you cannot delete a collection from IMX. You can ask for it to be blocklisted on our official marketplace, but that doesn't prevent 3rd party marketplaces from showing it. Make sure you test all flows thoroughly before deploying on mainnet.

​

Metadata

What's the difference between blueprints and dynamic metadata?​

There are two ways of storing token metadata on Immutable X: Providing a metadata_api_url when creating a collection and providing a blueprint string when minting a token on L2.

The blueprint cannot be changed: When a token which has been minted on L2 with a blueprint string is withdrawn to L1, the L1 smart contract is updated with this value, thus making it immutable. Immutable X does not allow updates to a token's blueprint value on L2.

The metadata_api_url can be updated: Updating the metadata_api_url of a collection can be done via our API.

More information:

Can I use OpenSea metadata on Immutable X?​

OpenSea metadata is partially supported by Immutable X. Your metadata will be fetched, but any attributes inside the attributes object will not be indexable nor shown on the official marketplace. In order for your metadata to be fully compatible, you will need to "flatten" it, meaning your attributes are stored as top-level values.

More information and examples:

How do I refresh dynamic metadata?​

Metadata refresh can be initiated via our APIs. Currently, our metadata crawler only runs once at the time of minting so if you make changes to the off-chain metadata that we retrieve from your endpoint, you need to trigger a metadata refresh so it can be updated on Immutable X.

The entire guide can be found here -

​

Minting & Royalties

How do I mint a token after registering a collection?​

Minting is executed by sending a signed POST request to our mints endpoint. The easiest way of doing so is by using the Core-SDK. Each mint request can only be executed by the collection owner and needs to be signed by them. You can mint multiple tokens per mint request and are encouraged to do so in order to achieve higher throughput. If you wish to call the mint API directly, you can use the below Python and Javascript implementations to understand the workings of it (impl. in other languages are coming soon).

Code, examples and documentation:

Are there any minting limits?​

Default limits are 5 collections per project and 50,000 mint requests. This limit reset every 4 weeks. Limits can be increased for projects meeting our criteria by contacting support .

What's the difference between mint and mintv2 methods in the SDK?

Mint method is soon going to be deprecated; it was used before royalties were added - new projects should not use it. mintv2 is the only way to set royalties to your collection and assets.

More information:

How do I set royalties for my collection?​

Royalties are being set during minting and they are enforced on the protocol level. L2 royalties are not applied on L1 transfers or transactions, as of right now.

More information:

How do I require money for mints?​

Minting on Immutable X takes a different approach and you cannot just add a "value" field to require money for mints to be executed. You will have to choose an approach and create the payment infrastructure yourself. Most often taken approaches and pros/cons to each can be found here: incomplete-guide-to-imx/guides/contract_and_registration at main · 8bNFT/incomplete-guide-to-imx

Can I call the mint method from the frontend?​

You will NOT use the mint method in your frontend, ever. Each request requires the collection owner's signature and doing so in the frontend would expose your private key in plain text.

​

Asset management L1 to L2 bridge

Can assets be withdrawn from L2?​

L2 assets can be withdrawn back to L1. This process usually takes 24h, the time it takes for your transaction to be included and submitted back to L1. This process incurs a gas cost.

Can assets be deposited back to L2?

Assets can be deposited back to L2. This process is almost instantaneous since we do not have to wait for the L1 proof to be confirmed. This process incurs a gas cost.

Can L1 minted tokens/L1 collections be deposited to L2?

Yes. L1 collections can register their contracts with Immutable. If they do not have the mintFor method, they won't be able to mint tokens on L2, but they will be able to take advantage of gas-free instantaneous transactions.

How long do deposits and withdrawals take?​

L2 proof needs to be submitted and verified on L1 before withdrawals can be finalized, this usually takes 24 hours. Deposits are almost instant because we do not have to wait for L1 proof to be verified.

How do I burn a token?

You burn a token by transferring it to a 0x0000000000000000000000000000000000000000 address. This will place it in a burned state and no one will be able to recover it.

More information and examples:

​

Building/Integrating with Immutable X?

What's the cost of integrating with Immutable X?​

Immutable X APIs and SDK are completely free.

How do I use Web3.js with Immutable X?​

You do not use Web3.js or any alternative to communicate with Immutable X, instead you use our REST API and our SDK. IMX-SDK is a set of helpers which makes interacting with Immutable X easy and simple for both developers and end users.

More information:

Is there a testnet?​

Yes. Test endpoints on Sandbox are:

Marketplace -https://market.sandbox.immutable.com/

API -https://api.sandbox.x.immutable.com/v1

Link -https://link.sandbox.x.immutable.com/

Is there a block explorer?​

Immutascan is a community-built block explorer for IMX.

API

Do I need to get an API key?​

FOR MANAGED PARTNERS ONLY

API keys are only issued to managed partners. If you are a managed partner and want to obtain an API key, reach out to the Immutable team and quote your project id.

You do not need an API key to use our API. If you frequently hit our rate limits, refer to our best practices or chat with the community in our #dev-discussion channel on Discord to learn how you can optimize your API calls.

More information: Rate limits | Immutable Documentation

What are the rate limits?​

Our current rate limit without an API key is 5 requests/second (subject to change).

More information: Rate limits | Immutable Documentation

Are there webhooks/websockets I can subscribe to?​

No, we currently do not provide webhooks or websockets. In order to stay sync'd up with the state of L2, you should poll our API endpoints in sane intervals. Going crazy with your polling interval will only use up your limit and you will get rate limited. More information: Immutable Documentation

What's a stark_key? What's an ethers_key?​

These are property names you might come across when using our API or SDK. ethers_key - L1 wallet address stark_key - L2 public address

How do I get a stark_signature?​

This is currently being handled by our SDKs, specifically Link in the frontend and Core SDK in the backend. You can check the implementation in our open sourced Core SDK.

More information and examples:

Why do I only get 100 results? How do I get all the results?​

We currently return 100 results by default (max. 200), this can be configured using the page_size query param. Our pagination is cursor-based. Each response that contains results also returns a cursor property. Appending the value of cursor as a query parameter cursor=value will go to the "next" page (next set of results).

More information and examples:

How do I get a list of assets (/assets) owned by the user?​

You do this by appending a user property to your URL query. https://api.sandbox.x.immutable.com/v1/assets?user=WALLET\_ADDRESS\_HERE

More information: Immutable Documentation

How do I get a list of assets (/assets) from a collection?​

You do this by appending a collection property to your URL query. https://api.sandbox.x.immutable.com/v1/assets?collection=COLLECTION\_ADDRESS\_HERE

More information: Immutable Documentation

How do I query assets (/assets) by metadata?​

You do this by appending a metadata property to your URL query. Metadata value has to be a JSON string formatted, where value is an array of values you wish to search for (i.e. {"key1":["value", "value2"], "key2": ["value", "value2"]}). This string has to be URI encoded. https://api.x.immutable.com/v1/assets/?collection=0xacb3c6a43d15b907e8433077b6d38ae40936fe2c&metadata=%7B%22set%22%3A%5B%22trial%22%5D%2C%22rarity%22%3A%5B%22legendary%22%5D%7D

More information:

How do I get transactions (/transfers) sent to a wallet?​

You do this by appending a receiver property to your URL query. https://api.sandbox.x.immutable.com/v1/transfers?receiver=WALLET\_ADDRESS\_HERE

More information: Immutable Documentation

How do I get transactions (/transfers) sent from a wallet?​

You do this by appending a user property to your URL query. https://api.sandbox.x.immutable.com/v1/transfers?user=WALLET\_ADDRESS\_HERE

Orders​

Does Immutable X automatically match buy and sell orders for NFTs of the same value?

There is currently no automatic matching of orders as Immutable X only supports the maker/taker model at present. An NFT will be listed for sale for a specified price by the maker, and the trade occurs when this order is accepted by the taker. This will change in the future as we are working on implementing metadata orders where you can place buy orders on metadata properties (e.g. name = Demogorgon), which will bring more liquidity to functionally identical NFTs