Skip to main content

Adding Metadata

Adding Metadata

to a token enables games and apps to import detailed information and showcase your token's data. Usually, digital assets are identified just by its Token ID. Metadata adds extra details to these assets, giving them properties such as a title, a narrative, and visuals.

What you'll need:
  • Some Enjin Coin on Enjin Matrixchain to pay for Transaction Fees and metadata Storage Deposits. You can obtain cENJ (Canary ENJ) for testing from the built-in Canary faucet in the Platform UI.
  • An Enjin Platform Account.
  • A Collection and a Token to add metadata to.
  • Follow our Best Practices for Collection/Token Metadata.

You can even use metadata to attach gifs, videos, and 3D models to your token. This data can be stored both on-chain and off-chain to allow users and other supported platforms to access the information.

When storing data on-chain, metadata can be defined as attributes such as name, description, fallback image, and any other attribute you choose. However, if the data is stored off-chain, it should always reference a centralized public repository through a .json file.

Metadata Storage​

There are three main ways to store metadata for your tokens:

  1. On-Chain Storage: Attributes

    • Storing metadata directly on the blockchain is known as on-chain storage.
    • It's immutable and highly secure since it's protected by the Enjin Blockchain's decentralized nature.
    • On-chain storage can cost a small fee at the time of mint and has slight limitations in terms of space, making it suitable for smaller, permanent files.

  2. Off-Chain Storage: JSON

    • This means the metadata is stored outside the blockchain on a separate server or database.
    • It's often accessible through a URL, typically pointing to a JSON file containing the asset's information.
    • Off-chain storage is cheaper and more flexible for large or frequently updated data, but it relies on external servers' availability and security.

  3. InterPlanetary File System (IPFS): JSON

    • IPFS is a decentralized storage solution that distributes file storage across a network of computers.
    • It allows metadata to be stored off the main blockchain but in a way that's still decentralized, tamper-proof, and permanent.
    • IPFS assigns a unique hash to each file. When you store metadata on IPFS, you link to it using this hash, ensuring the data remains unchanged.

Each option has trade-offs between cost, reliability, and security, and the choice depends on the specific needs and goals of the digital asset being created.

Attributes: OnChain Metadata​

You can assign multiple on-chain attributes to a token simultaneously, which allows you to define the metadata of the token.

Some commonly recognized attributes, following the Universal Metadata Standard, include:

  • name: The title of the token.
  • description: A brief explanation or description of the token.
  • media: A token image, GIF, or MP4 to represent the token.
  • URI: The web address (URL) where the JSON file containing the token's off-chain or IPFS metadata is hosted.
Need to add more metadata?

Check the Best Practices for Collection/Token Metadata, and the Universal Metadata Standard.

Attributes for Collections and Tokens are very similar.

The process of adding attributes is similar for both collections and tokens. While this tutorial guides you through adding an attribute to a token, you can follow the same steps to add attributes to a collection. Simply navigate to the corresponding menu for collections instead of tokens — and on the API, use the batchSetCollectionAttribute action (described below) in place of batchSetTokenAttribute.

Important: Attribute keys are case sensitive.

Ensure you use the correct casing when defining attributes to avoid errors.

There are two ways to add metadata:

  1. Using the Enjin Dashboard
  2. Using the GraphQL API & SDKs

Option A. Using the Enjin Dashboard​

Locate the token in the dashboard, click the 3 vertical dots (⋮), then click "Set Attribute".

Need to add multiple attributes for a token?

The Set Attribute form has a + Add to Batch button — queue several attributes and submit them as a single batched transaction. See Batching transactions for the full flow.

Type in the "Key" that you wish to add, and its "Value" in the corresponding text fields.

The Set Attribute form

Once you're satisfied with the options, click the "Set Attribute" button to submit the request. A Transaction Submitted modal appears with the new transaction's UUID and a View Transaction button that opens its row on the Transactions page.

Since this request requires a Transaction

, it must be signed before it broadcasts.

  • By default, transactions are signed automatically by the Wallet Daemon.
  • To sign with a different account, expand Transaction Options → Signing Account on the form and provide a Managed Wallet address.

Option B. Using the Enjin API & SDKs​

Batched attributes are split into two discriminator actions on CreateTransaction:

  • batchSetTokenAttribute — sets multiple attributes on a single token (collectionId, tokenId, attributes).
  • batchSetCollectionAttribute — sets multiple attributes on a collection (id, attributes).

The example below sets three attributes on a token. To target the collection itself, swap batchSetTokenAttribute for batchSetCollectionAttribute and replace the collectionId / tokenId pair with a single id field equal to the collection ID.

SDKs are not yet available

The C# and C++ SDK examples below are out of date and will not work against the current Enjin Platform API. This section will be updated once new SDKs are published. Until then, use the GraphQL, cURL, Javascript, Node.js, or Python examples.

mutation BatchSetTokenAttribute {
  CreateTransaction(
    network: ENJIN  # or CANARY for testnet
    chain: MATRIX
    transaction: {
      batchSetTokenAttribute: {
        collectionId: 36105
        tokenId: 0
        attributes: [
          { key: "name", value: "Chronicles of the Celestium" }
          {
            key: "description"
            value: "An epic saga where players assume the roles of intrepid tradesmiths, shaping destinies with fire and will across the star-woven expanses of the multiverse."
          }
          { key: "uri", value: "https://yourhost/metadata.json" }
        ]
      }
    }
  ) {
    uuid
    action
    state
  }
}

The response includes the transaction's uuid, action (e.g. MultiTokens.batch_set_attribute), and state (PENDING → BROADCAST → FINALIZED). Use GetTransaction(network, chain, uuid: "<returned-uuid>") to poll the current state.

Once it reaches FINALIZED, an event is emitted for each attribute set, confirming the change. See Working with Events for how to read them.

Setting a single attribute, or removing one

Use setTokenAttribute / setCollectionAttribute to write a single key, removeTokenAttribute / removeCollectionAttribute to remove one, and removeAllTokenAttributes / removeAllCollectionAttributes to wipe everything. All of these are discriminator fields on CreateTransaction.transaction.

JSON File: Off-Chain & IPFS Metadata​

A JSON file can be used to provide comprehensive information about the asset, including its description, visual representation, multimedia attachments, external references, categorization, associated files, and specific attributes.

Take a look at this simple JSON schema (following the Universal Metadata Standard) to learn how to properly format the off-chain metadata for your NFT.

{
   "name": "Starforged Cleaver",
   "description": "A blade smithed from cosmic steel, its edge sharp enough to slice through the fabric of reality itself.",
   "external_url": "https://enjin.io",
   "fallback_image": "https://yourhost/image.jpg",
   "media": [
      {
         "type": "image/png",
         "url": "https://yourhost/image.jpg"
      }
   ],
   "attributes": {
      "Strength": {
         "value": "800"
      }
   }
}

Take note of these data points:

  • description: This field provides a human-readable description of the asset. It's a text description that helps users understand the nature or significance of the asset.

  • media: The media field contains a URL pointing to an image representation of the asset. It supports PNG, GIF, and JPG file formats.

  • external_url: The "external_url" field is a URL pointing to an external application or website where users can view additional information or interact with the asset.

  • attributes: This is an object array where each object should contain an title and value fields. The attribute title defines the type of trait or attribute associated with the asset, while value can be a string or a number, representing the value of that trait or attribute.

You can also host your JSON files on IPFS, to make your metadata more immutable.

Need to add more metadata?

Check the Best Practices for Collection/Token Metadata, and the Universal Metadata Standard.

Explore More Arguments

For a comprehensive view of all available arguments for queries and mutations, please refer to our API Reference. This resource will guide you on how to use the GraphiQL Playground to explore the full structure and functionality of our API.

To sign with a managed wallet instead of the Wallet Daemon, set signerAccount on CreateTransaction.

What's next?

To mint some token supply, head to the Minting Tokens tutorial.