Skip to main content

Asset Metadata

Immutable X allows for projects to specify metadata properties for their assets. These properties allow marketplaces to perform complex filtering queries to help users discover what they want more effectively.

Refresh metadata

In order to update asset metadata values based on the changes that you've made, you can request a metadata refresh. You will need to identify the tokens that need to be re-crawled, and the updates that have been made to them (via the Metadata API).

We aim to process requests within 2 business days (AEST) but this can take longer depending on demand.

Core properties

There are several core properties

nameThe display name for this assetno
descriptionThe description of this assetno
image_urlThe URL of the display image for this asset. This will be used as a video thumbnail in the Immutable X
imageAlternative field of
animation_urlA URL to a multi-media attachment for the item. We highly recommend the use of the HLS format for streaming video over HTTP. This is generally used for video
animation_url_mime_typeMime type of the file that animation_url points to. Imx only supports these 3 mime types currently:
  • application/,
  • video/mp4,
  • video/webm
NOTE: When animation_url is specified, this field is mandatory. Otherwise this field is optional like the others.
youtube_urlA URL to a YouTube video. This playback method is currently not supported in the Immutable X Marketplace, but third party support could be

The above core properties usually don't need to be mapped to a type if you don't want to do filtering on them.

Partners will be required to host their own video assets and exposing their location via the animation_url.

For video NFTs, the individual marketplace can determine whether to loop video, support autoplay, or mute on initial load. The protocol does not define how it should be played in a given marketplace.

Property type mapping

The following is the source of truth specification for how metadata filters function in Immutable X. Metadata filters let API consumers filter returned NFTs by their metadata properties. These filters are applied to a bunch of endpoints.

In the event where the NFT has a metadata key that does not exist yet in our database, that new key and values will be added into our database.

In our database, metadata properties are stored with one of the following types:

enumProperty with a defined enumeration of possible values (e.g. god = nature or death).
textProperty which contains arbitrary text. Should be searchable. Not filterable.
booleanProperty which can be either true or false.
discreteProperty which will usually be handled as a multi-select e.g. mana.

Example mapping in our database



The filterable parameter is a boolean condition that signals to the marketplace that the metadata attribute should be something the end user can filter assets with. All metadata attributes can still be text-searched but the marketplace could implement specific filters in the marketplace UI tailored to the particular collection.

Please note, the "filterable" parameter can only be true for non-text parameter types.

Filters are only generated for properties at the top-level of the JSON metadata object.

Example metadata

// core fields:
"name": "Rufus",
"animation_url": "",
"animation_url_mime_type": "application/",
"image_url": "",

// Add more (non core) properties as long as it's a flat key/value structure
// and these values match the schema that the contract was registered with
"attack": 4,
"collectable": true,
"god": "Ranged",
"element": "Water",
"product": 2,
"rarity": 2,
"type": 3

Example metadata schema

Please note:

  • The "filterable" parameter can only be true for non-text parameter types.
  • We don't need you to provide us the values for an enum type. We auto-generate the list of values based on what is passed to us through your metadata endpoint
  • We don't need the range of values for a discrete type. We auto-generate the range based on the provided list of values
"metadata": [
"name": "name",
"type": "text"
"name": "attack",
"type": "discrete",
"filterable": true
"name": "collectable",
"type": "boolean",
"filterable": true
"name": "god",
"type": "enum",
"filterable": true
"name": "element",
"type": "enum",
"filterable": true
"name": "product",
"type": "discrete",
"filterable": true
"name": "type",
"type": "discrete",
"filterable": true