Immutable X

Immutable X Docs

Here you'll find comprehensive guides and documentation to help you start building scalable and secure NFT applications.

Get Started

Immutable X Concepts

Immutable X Architecture

There are three core components to the Immutable X stack: the ZK-Rollup scaling engine, Link and the APIs.

These components work together to lower the barriers of entry in the NFT space for developers and users, and enable instant trade confirmation, massive scalability, gas-free minting and trading, all without compromising user custody.

There are three distinctions to make when referring to Immutable X:

  • The Immutable X platform is the core infrastructure that allows for the minting, depositing, withdrawing and trading of assets in Layer 2 blockchain
  • The Immutable X token known as IMX, is the ERC-20 utility token of the Immutable X protocol, used to reward users for their contribution to the platform
  • The Immutable X Marketplace is the first exchange venue for gas-free minting and trading of NFTs, developed by Immutable and powered by Immutable X

The Immutable X APIs

The Immutable X APIs wrap the logic of the Immutable X Exchange Engine. Developers do not need to interact directly with smart contracts via custom logic to build on the Immutable X platform.

On Immutable X, every interaction, from minting to trading to transferring, is performed via simple API calls. The Immutable X APIs contain both the Read and the Write functionality required to build applications without ever building a backend, meaning Immutable X abstracts the complexity of the blockchain to function as a backend.

The Immutable X APIs Read functionality also offers various filtering options. This includes filters that can present a list of all orders submitted by a specific user, or more complete filters like metadata filters.

This means using the Immutable X APIs Read function we can give developers:

  • A list of mints
  • A list of trades
  • A list of withdrawals & deposits
  • A list of assets minted
  • A list of orders. (e.g. display all the orders made).

In Layer 1 blockchains, there are no API’s so any elements that require tracking are tracked individually, then recorded and stored in your own records.

Our API reference documentation is available here.


Immutable X combines NFT-specific exchange and proof logic with the cutting edge rollup technology developed by StarkWare to create one of the most advanced tools for trading NFTs ever built. Rollups allow for world-class scalability and user experience while retaining the underlying security of Ethereum.

ZK-STARKs (Zero-Knowledge Scalable Transparent ARguments of Knowledge) are a type of cryptographic proof technology that enables users to share validated data or perform computations with a third party without the data or computation being revealed to the third-party, also known as a zero-knowledge proof, in a way that is publicly verifiable.

Prior to the creation of ZK-STARKs, ZK-SNARKs were used to create ZK proof systems, but required a trusted party or parties to initially setup the ZK proof system which introduced the vulnerability of those trusted parties compromising the privacy of the entire system. ZK-STARKs improve upon this technology by removing the need for a trusted setup.

A ZK-Rollup requires an “operator”. The operator is responsible for linearising transactions. Linearising transactions means putting them into a consistent global incremental order with no gaps. In this instance Immutable X is the operator.

A state transition is when a user sends a transaction to Immutable X, which immutable X linearises (that is, we put it into a big long sequence) to then perform the batching and proofing. State transitions can be of any kind that is valid, however there must be an operator who orders these state transitions.
Valid state transitions include:

  • Trades
  • Transfers
  • Mints
  • Deposits
  • Withdrawals

Immutable X’s rollup technology allows for more than 9,000 NFT transfers, trades and mints per second, meeting and exceeding the scale required by mainstream NFT projects.

For more information on rollups, check out Vitalik's article An Incomplete Guide to Rollups.


The Link is the conduit that we use to connect users to the Immutable X protocol. This allows Immutable X to support a thriving third-party marketplace ecosystem, without presenting a security risk.

Unlike other blockchains or sidechains, Immutable X currently supports all desktop Ethereum wallets without forcing the user to switch networks. However, all new Immutable X users are required to set up a Layer 2 wallet via Link, which will register and associate the Layer 1 wallet public key under a newly generated STARK Key.

Immutable X delegates all the security and recovery functionality to the users underlying Ethereum wallet. This all takes place inside the Link, meaning the Link signs transfers, trades, cancellations, and any/all of the authenticated assets that need to be signed.

Immutable X partners can embed the Link directly into their site’s transaction flow as an iframe, making buying and selling NFTs more immersive, efficient, and intuitive. The Link screens will show up in the site’s transaction flow, allowing their users to authorize purchases, listings, and transfers of ETH and NFTs, all without leaving the page.

Immutable X SDK

The purpose of the Immutable X SDK is to allow partners to integrate with Immutable X more easily. At present a Typescript SDK implementation is available which can be used to integrate the protocol easily into websites. The SDK allows for types access to the Immutable X APIs and Wallet, regardless of the platform. The Immutable X SDK, combined with the APIs, will allow partners to build NFT projects in hours rather than weeks.

Shared Asset Book

Every asset that is minted into Immutable X are stored in the shared asset book (Immutable X asset book). This ensures Immutable can deliver the best liquidity outcome for partners on Immutable X.

More information on this coming soon.

Shared Order Book

Immutable X utilises a “shared orderbook” model. Every order submitted to Immutable X is stored by Immutable and made available to all marketplaces (Immutable X Orderbook). This means that functional marketplaces can be built on Immutable X with no backend - indicating a clear time-to-market advantage for our customers.

This means that Immutable X partners:

  • Do not need to build, manage or maintain their own Orderbook to facilitate trades.
  • Have access to pools of demand that exist outside of their marketplace.

More information on this coming soon.


Immutable X supports two types of metadata.

Immutable Metadata: set at the time of asset creation, enforced by the proof and available on-chain when an L2-minted NFT is withdrawn for the first time. This is also called the blueprint or the mintingBlob. This is where applications should store permanent properties (e.g. ids or IPFS hashes).

Mutable Metadata: fully controlled by the application, and not recorded on-chain, mutable metadata is most useful for marketplaces to describe assets accurately to users. Every application must register a schema for their collection’s metadata, where they tell us the “types” of the metadata.

Every application must also expose an API endpoint which Immutable X can call after an asset from that collection is minted. Immutable will store the metadata returned by this endpoint in our database, and subsequent callers will be able to use these metadata properties in filter queries to the APIs.

Currently, your collection’s metadata schema can only be updated via a manual request to Immutable. Soon, we will be switching to a self-serve metadata model, which will let applications update their collections' metadata on-demand.

Key Terms

Below are some key terms that are used in this guide: (if you are new to blockchain, start here):

  • Software Development Kit (SDK): a set of tools for third-party developers to use in producing applications using a particular framework or platform.
  • Application Programming Interface (API): a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
  • Private key: also known as a secret key, a private key is a variable in cryptography that is used with an algorithm to encrypt and decrypt code.
  • Public key: a cryptographic key that can be obtained and used by anyone to encrypt messages intended for a particular recipient, such that the encrypted messages can be deciphered only by using a second key that is known only to the recipient (the private key).
  • Ethereum Elliptic Curve: a curve defined by the equation y² = x³ + ax + b with chosen a and b, that is used in cryptography. Ethereum uses the elliptic curve secp256k1.
  • STARK (Scalable Transparent ARguments of Knowledge) Key: a public key defined over a STARK-friendly elliptic curve, is different from the standard Ethereum elliptic curve. The STARK Key represents the x coordinate of a point on the STARK-friendly elliptic curve.
  • STARK proof: a type of cryptographic proof technology that enables users to share validated data or perform computations with a third party without the data or computation being revealed to the third-party, also known as a zero-knowledge proof.
  • Merkle tree: in cryptography and computer science, a hash tree or Merkle tree is a tree in which every leaf node is labelled with the cryptographic hash of a data block, and every non-leaf node is labelled with the cryptographic hash of the labels of its child nodes.
  • Minting: is how NFTs become part of the Ethereum blockchain. Similar to the way that metal coins are minted and added into circulation, NFTs are created by minting them onto the blockchain. A crucial feature of Immutable X is the ability for assets to be minted off chain. This allows NFT applications to create millions of NFTs without incurring gas costs.
  • Orders: a written direction to pay a fee or deliver property.
  • Deposits: take an on-chain asset (ETH, ERC-20 or ERC-721) and lock it in the Immutable X smart contract on-chain. Once this deposit is processed, the locked asset is available for transfer and trade inside Immutable X.
  • Withdrawals: enable an asset to be moved from Immutable X to the main Ethereum blockchain. Withdrawal is a two step process: first, the withdrawal must be included in a batch. This process may take up to 24 hours depending on when the request is made. Second, the user must send an on-chain transaction to move the asset from the Immutable X smart contract into their own wallet.

Updated about a month ago

Immutable X Concepts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.