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.CollectionDefinition = {
name: 'Example collection',
description: 'A collection with example items',
mediaDetails: {
image: {
url: 'https://res.cloudinary.com/handcash-iae/image/upload/v1685141160/round-handcash-logo_cj47fp_xnteyo_oy3nbd.png',
contentType: 'image/png',
},
},
};
const collectionItems: Types.CreateItemMetadata[] = [
{
name: 'An example item',
rarity: 'Common',
attributes: [
{
name: 'Edition',
value: 'First',
displayType: 'string',
},
],
mediaDetails: {
image: {
url: 'https://res.cloudinary.com/handcash-iae/image/upload/v1702398906/items/da2qv0oqma0hs3gqevg7.webp',
imageHighResUrl: 'https://res.cloudinary.com/handcash-iae/image/upload/v1697465892/items/gh7tsn11svhx7z943znv.png',
contentType: 'image/png',
},
},
color: '#B19334',
quantity: 5,
},
];
Collection Types
Here's an example of collection metadata:
{
"name": "Example collection",
"description": "A collection with example items",
"mediaDetails": {
"image": {
"url": "https://handcash.io/asset/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": "https://handcash.io/item/188272.webp",
"imageHighResUrl": "https://handcash.io/item/188272.png",
"contentType": "image/webp"
}
},
"attributes": [
{
"name": "Edition",
"value": "First",
"displayType": "string"
}
],
"externalId": "0000012344"
}
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) |
user | The user id to create the item to (Optional). |
externalId | An id that links the item to your internal database, this is a common way to search inventories later on (Optional) |
groupingValue | A unique identifier to distinguish items with the same name but different characteristics. For example, a Pokémon card named Charizard could belong to different editions or have a holographic version. This field helps to differentiate between such variations. If not provided it will be derived based on the name using a hash function, for example it will look like this90c08fbd22f8f73dfd89ed592276426d (Optional) |
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://handcash.io/item/188272.webp",
"imageHighResUrl": "https://handcash.io/item/188272.png",
"contentType": "image/webp"
},
"multimedia": {
"url": "https://handcash.io/asset/3dImage.glb",
"contentType": "application/glb"
}
}
Property | Description |
---|---|
url | An image url to represent an item that is put on the blockchain, 50kb size limit |
imageHighResUrl | A high resolution image of an item that is not put on chain but is used to display the item |
contentType | One of ["image/png" , "image/jpg" , "image/gif" , "text/html" , "audio/mpeg" , "application/fbx" , "application/glb" ] |
Expected image sizes
image.url
max size is 50kb and image.imageHighResUrl
has no limit.
image.url
will be put on chain and should be a lower resolution image, image.imageHighResUrl
will be used to display the item in the inventory and market. It should follow the guidelines below for best results. Please reach out to Handcash Support or Sales with any questions or if you would like to put larger files on chain.
Context | Aspect ratio | Optimal resolution |
---|---|---|
Collection | 2:1 | 600x300 |
Collection items | From 1:1 to 2:3 | From 728:728 to 2048:2048 |
Updated 3 months ago