Asset Ownership

Supporting Immutable X Assets in your application lets your users use their assets while they are tradable in Immutable X. As Immutable X is an asset and trading protocol, rather than an exclusive solution, you can support Immutable X assets alongside assets from any other Layer 2 protocol, or Ethereum mainnet itself.

Users of any NFT-based application can choose to deposit their assets into Immutable X to reap the UX and scalability benefits we provide. Supporting Immutable X natively will improve the experience of those users, will make serious traders more likely to use your project, and will give your application access to our powerful Layer 2 liquidity features.

Immutable X is a fully API-based protocol, so integrating is easy regardless of your level of blockchain experience - it can usually be done in hours.

Registering your Project

Before assets from your project will be tradable on Immutable X, you must register your project with Immutable. Eventually, this process will be automated, but currently, we will verify you and your ownership over the project manually.

Registering your Collections

Each project may maintain multiple collections of assets. In Gods Unchained, for instance, we have cards, trinkets and boards. Collections are tied 1:1 to ERC721 contracts and are therefore uniquely identified by their address. We will need to manually add these collections to our registry in order to support trading of assets from that collection and provide useful UX throughout the ecosystem.

Consuming the Assets API

Assets can have one of the following statuses:

Status

Description

imx

The asset is in the Immutable X L2 environment.

eth

The asset is on the main Ethereum blockchain.

depositing

The asset is still on the main Ethereum blockchain, but is part of a currently ongoing transaction.

pendingWithdrawal

A withdrawal has been requested for this asset, and it will be included in an upcoming batch.

withdrawable

The asset has been included in a published batch, and can now be withdrawn from the Immutable X smart contract.

withdrawing

The asset is on the main Ethereum blockchain, and is being pulled from the Immutable X smart contracts to a user's account.

To display assets which are currently in Immutable X, you will need to use the Assets API. Note that this API will return all assets (including those on-chain or in the withdrawal process). A common use case is displaying a user's inventory:

GET https://api.x.immutable.com/v1/assets?collection=0x...&user=0x...&status=imx

Setting status=imx helps protect against displaying the same asset twice (if you already use Ethereum to track your application's assets). This endpoint will return assets in the following format (note the pagination properties):

{
  "page": 1,
  "perPage": 20,
  "total": 500,
  "records": [
    {
      "name": "Ratify",
      "description": "",
      "image_url": "",
      "cache_for": 100,
      "tradable": true,
      "external_url": "",
      "background_color": "",
      "status": "imx",
      "properties": {
        "proto": {
          "value": "300",
          "type": "number"
        },
        "created": {
          "value": "2020-09-04",
          "type": "date"
        },
        "type": {
          "value": "spell",
          "type": "enum"
        }
      }
        }
  ]
}

I

GET https://api.godsunchained.com/metadata?collection=0x...&token_ids=1456,5423

{
    "0x...": {
    "1456": {
        "name": "Ratify",
      "description": "",
      "image_url": "",
      "cache_for": 100,
      "tradable": true,
      "external_url": "",
      "background_color": "",
      "properties": {
        "proto": {
          "value": "300",
          "type": "number"
        },
        "created": {
          "value": "2020-09-04",
          "type": "date"
        },
        "type": {
          "value": "spell",
          "type": "enum"
        }
      }
    },
    "5423": {
        "name": "Ratify",
      "description": "",
      "image_url": "",
      "cache_for": 100,
      "tradable": true,
      "external_url": "",
      "background_color": "",
      "properties": {
        "proto": {
          "value": "300",
          "type": "number"
        },
        "created": {
          "value": "2020-09-04",
          "type": "date"
        },
        "type": {
          "value": "spell",
          "type": "enum"
        }
      }
    }
    }
}

That's it!

Seriously? Yep - we told you we wanted to make Ethereum NFTs accessible to any developer, and we've worked hard to abstract away everything complex while leaving players fully in control of their assets. If you've set up the above, then your players will have full access to the liquidity and scalability of Immutable X.

If you'd like to support that trading yourself, check out the Supporting Asset Trading guide.


Did this page help you?