Define your collection

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"
    }
  }
}
PropertyDescription
nameCollection name.
descriptionShort description about this collection.
mediaDetailsAn 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:

PropertyDescription
nameItem name.
rarityShould be one of ["Common", "Uncommon", "Rare", "Epic", "Mythic"].
colorHex color to represent this item. (Optional).
quantityTotal quantity of this item.
mediaDetailsAssets to represent this item. (see below)
attributesThese 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:

PropertyDescription
nameThe attribute name
valueThe attribute value
displayTypeThe 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:

PropertyDescription
imageThe main image used to represent the item in the wallet and in the market
multimediaComplementary 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"
  }
}
PropertyDescription
urlCan reference either a path to a local file or a URI to a remote file.
contentTypeOne of ["image/png", "image/jpg", "image/gif", "text/html", "audio/mpeg", "application/fbx", "application/glb"]

 Expected image sizes

ContextAspect ratioOptimal resolution
Collection2:1600x300
Collection itemsFrom 1:1 to 2:3From 728:728 to 2048:2048