Metadata schema registration

Prior to metadata registration, you need to register your collection.

Add collection metadata schema

Only the project owner (wallet owner) can add a metadata schema to a collection. See an example schema here.

Each property of the metadata schema contains the following fields:


Required (Default value)

Value Type / Notes





no ("text")


no (false)


If set to true, then the particular metadata's "name" will show up in the filters that are used by marketplaces and other ecosystem projects.

Example payload:

  "metadata": [
      "name": "some-metadata-name",
      "type": "discrete",
      "filterable": true
      "name": "rare",
      "type": "boolean",
      "filterable": true
      "name": "image_url"

Learn more about asset metadata


View example code

The repository imx-examples provides easy to use examples. Follow the instructions in the README to get started.

Edit metadata schema

To add missing attributes to your collection's metadata schema that were not submitted in the original request, you can execute this call multiple times. Just add the missing attributes and they will be appended.

Submitting the same metadata schema attribute will cause the error:

{"code":"metadata_key_already_exists","message":"Metadata key(s) already exist"}


Metadata refreshing requires support

While you can register your own collections and metadata on Ropsten, you cannot execute a metadata refresh yourself.

To refresh metadata changes, you need to contact support and identify the tokens that need to be re-crawled, and the updates that have been made to them.

Requests may take up to 2 business days (AEST).

Other attributes

You can update the "filterable" attribute of a metadata schema property.

Expensive API call on "filterable": true
This API call may take a few seconds to a few minutes as it will trigger a re-scan of all the assets for the {{contract-address}} to get the up to date the filter values.

You can also edit the "type" attribute of a metadata schema property.

Filterable text is not allowed
If passing both "filterable": true and the "type": "text", this API call will return an error. This error will also be triggered when passing "filterable": true and the metadata "type" is already "text".

Did this page help you?