This page describes the different ways of defining the collection metadata. This information is used to create the items and inscribe them on-chain during the inscription process.

Programmatically

The recommended way of defining the collection metadata in a dynamic environment is using Typescript/Javascript.

Example programmatic collection metadata

import { Types } from "@handcash/handcash-connect";

const collectionMetadata: Types.CreateItemParameters = {
  collection: {
    name: 'Example collection',
    description: 'A collection with example items',
    mediaDetails: {
      image: {
        url: './assets/000012.png',
        contentType: 'image/png',
      },
    },
    totalQuantity: 5,
  },
  items: [
    {
      item: {
        name: "An example item",
        rarity: "Common",
        attributes: [
          {
            "name": "Edition",
            "value": "First",
            "displayType": "string"
          }
        ],
        mediaDetails: {
          image: {
            url: './assets/188272.png',
            contentType: 'image/png',
          },
        },
        color: '#B19334',
      },
      quantity: 5,
    }
  ]
};

From JSON file

This section describes the JSON format expected to define the collection metadata.

Example JSON collection metadata

{
  "collection": {
    "name": "Example collection",
    "description": "A collection with example items",
    "mediaDetails": {
      "image": {
        "url": "./assets/000012.png",
        "contentType": "image/png"
      }
    }
  },
  "items": [
    {
      "name": "An example item",
      "rarity": "Common",
      "color": "#B19334",
      "quantity": 5,
      "mediaDetails": {
        "image": {
          "url": "./assets/188272.png",
          "contentType": "image/png"
        }
      },
      "attributes": [
        {
          "name": "Edition",
          "value": "First",
          "displayType": "string"
        }
      ]
    }
  ]
}

Collection

Here's an example of collection metadata:

{
  "name": "Example collection",
  "description": "A collection with example items",
  "mediaDetails": {
    "image": {
      "url": "./assets/000012.png",
      "contentType": "image/png"
    }
  }
}

Property	Description
`name`	Collection name.
`description`	Short description about this collection.
`mediaDetails`	An image to represent this collection in the wallet and in the market.

Items

Here's an example of a collection item metadata:

{
  "name": "An example item",
  "rarity": "Common",
  "color": "#B19334",
  "quantity": 5,
  "mediaDetails": {
    "image": {
      "url": "./assets/188272.png",
      "contentType": "image/png"
    }
  },
  "attributes": [
    {
      "name": "Edition",
      "value": "First",
      "displayType": "string"
    }
  ]
}

This is how each of these properties is used:

Property	Description
`name`	Item name.
`rarity`	Should be one of [`"Common"`, `"Uncommon"`, `"Rare"`, `"Epic"`, `"Mythic"`].
`color`	Hex color to represent this item. (Optional).
`quantity`	Total quantity of this item.
`mediaDetails`	Assets to represent this item. (see below)
`attributes`	These are the attributes for the item, which will show up on the HandCash for the item. (see below)

Attributes

Each item can be described using the following properties:

Property	Description
`name`	The attribute name
`value`	The attribute value
`displayType`	The way this value should be represented. (see below)

Display types

These are the supported display types to represent attributes:

string: "fire"
number: 4
date: 23/05/2023
boostPercentage: +7%
boostNumber: +10

String

{
  "name": "Element",
  "displayType": "string", 
  "value": "Fire"
}

Number

{
  "name": "Attack",
  "displayType": "number", 
  "value": 8
}

Date

Pass in a unix timestamp (seconds) as the value.

{
  "name": "Birthday",
  "displayType": "string", 
  "value": 1688280400
}

Boost Percentage

{
  "name": "Element",
  "displayType": "string", 
  "value": "Fire"
}

Boost Number

{
  "name": "Attack increase",
  "displayType": "boostNumber", 
  "value": 3
}

Media details

The media details define the different assets available to represent the item:

Property	Description
`image`	The main image used to represent the item in the wallet and in the market
`multimedia`	Complementary asset to represent this item (3D files, audio files, etc...)

{
  "image": {
    "url": "https://myapp.com/assets/188272.png",
     "contentType": "image/png"
  },
  "multimedia": {
    "url": "./assets/2001021.png",
     "contentType": "image/png"
  }
}

Property	Description
`url`	Can reference either a path to a local file or a URI to a remote file.
`contentType`	One of [`"image/png"`, `"image/jpg"`, `"image/gif"`, `"text/html"`, `"audio/mpeg"`, `"application/fbx"`, `"application/glb"`]

Expected image sizes

Context	Aspect ratio	Optimal resolution
Collection	2:1	600x300
Collection items	From 1:1 to 2:3	From 728:728 to 2048:2048