Metadata Guide

Once you have created a token blueprint on the blockchain, you can add complex and dynamic metadata to it using the ERC-1155JSON schema.

 Metadata is not stored on the blockchain because the files are too large.

 However, it is possible to decentralize your metadata by storing it on IPFS.

Storing your metadata on your own servers also gives you more control over what is shown, enabling you to create dynamic tokens that augment, and level up based on user experience.

You also have the option to store your metadata on Enjin’s servers, which can save you time and money.

Setting Your Metadata

You can set your metadata through “Assets” section in your project on Enjin’s minting panel by clicking the “Edit” button on the token you wish to customize.

Basic Editor

If you want to set your metadata the fast and cheap way, you can do so using the “Basic Editor”.

Your token URI will then be customized to point towards Enjin’s servers, where the metadata is stored.

Once a successful request has been made, you will need to accept and sign the transaction in the REQUESTS section of your wallet.

You can also upload .GIF and .MP4 files as your asset images!

Requirements when using hosted metadata:

  • 5mb max for GIFs/regular images.
  • 15mb max for MP4 videos.

Advanced Editor

If you want full control over your metadata, you can choose the URI using the “Advanced Editor”

Your token URI will then be customized to point towards the address you have specified and you will be able to customize the JSON file at your leisure. 

Please note the following requirements when it comes to hosting your own metadata:

1. The link (to both metadata and image) must be publicly accessible to robots

2. The uri must be set appropriately to the requested file

3. The image must be that of a valid image file (the image must show)

4. The JSON must conform with the JSON RFC standards, if it does not conform in anyway then it won't be loaded.


If you want to set your metadataprogrammatically, you can do so using the following API query.

mutation SetItemUri($identityId: Int!, $itemUriData: SetItemUriInput!) {
CreateEnjinRequest(identity_id: $identityId, type: SET_ITEM_URI, set_item_uri_data: $itemUriData) {

The ERC-1155 token standard includes optional formatting to allow for ID substitution by clients. If the string {id} exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard.

  • The string format of the substituted hexadecimal ID MUST be lowercase     alphanumeric: [0-9a-f] with no 0x prefix.
  • The string format of the substituted hexadecimal ID MUST be leading zero     padded to 64 hex characters length if necessary.

In this situation, the following address:


Would be replaced with:


Creating A Custom JSON File

If you wish to create your own Metadata file, you will need to safe it as a .json file.

 Once you have that .json file uploaded with public read access, you can make the request to set the item URI (Uniform Resource Identifier).

 Here is an example of a simple metadata schema

{ "name": "item_name",
 "description": "Description line 1.\nDescription line2.",
 "image": "/image.jpg"

For more information on how to create a more robust JSON file, visit the ERC-1155 Github.

Invalidating Your Metadata

Sometimes for any reason, if your metadata doesn't load or takes a while to load, we have implemented the Invalidate Metadata mutation.

mutation InvalidateTokenMetadata {
 InvalidateTokenMetadata(id: "$id")

<inline-code>Id<inline-code> is the token ID of the asset.

This mutation will instruct the Platform to invalidate the metadata and thus fetch it again, directly from your server.

Please be aware that it can take a few minutes, after invalidating it, for the new metadata to load.

Additionally, please be aware that this mutation can only be ran once, per token, every few minutes.

You can only run this mutation on tokens that belong to an application that you have the minter role (or higher) on.

Specific Metadata URI

Any token ID may have a metadata URI that can be retrieved by calling uri(_id) on the ERC-1155 contract.

If an individual Non-Fungible token ID has a metadata URI defined, client apps should use this URI. If not defined, client apps should call uri(_id) on the base token id to retrieve the Default URI for the entire set of Non-Fungible tokens.

Default URI

A Non-Fungible token that defines a Default URI in its base token has the option of using an {id} placeholder in the URI itself. This will get replaced with the distinct ID when accessing NFTs.

Example{id}.json ->


If the Default URI contains an image property that in turn contains the {id} placeholder, the image URL will be used as the default image for all tokens of this type.

Example{id}.jpg ->

The image property can also be a static URI without the placeholder, as desired.

In GraphiQL, you can set the URI for the item using the following mutation:

mutation SetItemUri($identityId: Int!, $itemUriData: SetItemUriInput!) {
 CreateEnjinRequest(identity_id: $identityId, type: SET_ITEM_URI, set_item_uri_data: $itemUriData) {

Note: Setting the URI is a blockchain transaction that you will need to approve in the Enjin Wallet under the "Requests" tab in order to see the metadata appear on your assets.

On This Page