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"
}
}
}
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 |
Updated about 2 months ago