Creating & Managing Items

Suggest Edits

Overview

Items are essential for almost every game. Whether your game's items are weapons, materials, cosmetics, skins, consumables or anything else, MetaFab makes it easy to create and manage them on the blockchain as digital collectibles for your players.

Using MetaFab, items can be created through what's called a Collection. You can think of a Collection as a grouping that maintains all of the various item data and player ownership information for you game's items. A Collection is deployed to, and exists on the blockchain.

Collections can have new items created or updated at any time, allowing you to progressively add new items to your game as needed, or updating existing items attributes if necessary.

Additionally, MetaFab item collections are fully compatible with every existing NFT or digital collectible marketplace like OpenSea, LooksRare and more.

In this guide, we're going to cover patterns on how to create your game's items collection, adding new item types to your collection, minting and transferring items to your player's wallets, and much more.

Guide

Step 1: Create your First Collection

Let's start by creating our first collection. As we mentioned in the overview, a collection is like a grouping that maintains all of the various item data and player ownership information for our game's items. Game's can have as many collections as you'd like, but for most games, only 1 collection is necessary. There is no limit to the number of items you can create for a collection.

To create a collection for our game, we're going to use the POST /v1/collections endpoint. Please keep in mind, your game's primary wallet must have a sufficient native token balance for the chain you want to deploy your collection to, as noted here.

We'll need to provide the following arguments to create a collection using the creation endpoint.

  • chain: The blockchain where you'd like to deploy your collection. We recommend MATIC (Polygon) for production use cases, or MUMBAI (Polygon Testnet) for testing.

Additionally, we'll need to provide our game's secretKey for the X-Authorization header, as well as our game's walletDecryptKey for the X-Wallet-Decrypt-Key header.

After we successfully make the API request to create our player, we'll receive a response with a collection object that looks something like this.

{
  "id": "0b7f916a-f933-492a-a96f-21831447aada",
  "gameId": "898d9a17-9a9b-45a2-9ab9-3cd4300ef5f9",
  "contractId": "739f2147-9987-45c0-8010-46cafc583cf8",
  "updatedAt": "2022-10-28T23:34:34.182Z",
  "createdAt": "2022-10-28T23:34:34.182Z",
  "contract": {
    "id": "739f2147-9987-45c0-8010-46cafc583cf8",
    "gameId": "898d9a17-9a9b-45a2-9ab9-3cd4300ef5f9",
    "chain": "MATIC",
    "abi": [ ...REDACTED FOR LENGTH ],
    "type": "ERC1155_Game_Items_Collection",
    "address": "0x6EC79386b40B03b4e9772ED156C005cB2ae2A3f0",
    "updatedAt": "2022-10-28T23:34:34.182Z",
    "createdAt": "2022-10-28T23:34:34.182Z",
    "transactions": [
      {
        "id": "4274a103-c014-4af4-9632-2358de62bb8c",
        "contractId": "739f2147-9987-45c0-8010-46cafc583cf8",
        "walletId": "b32f7381-2e6b-403a-9b6a-f6da1d8e8d74",
        "function": "create",
        "args": [
          "0xd501120feEe803ea5d8B81b9C9e95eC056d076f4"
        ],
        "hash": "0xe93cc44ce08b150df2863d2e0e99fe62c428c0bbf745348a488f9b38f0b99b45",
        "updatedAt": "2022-10-28T23:34:34.182Z",
        "createdAt": "2022-10-28T23:34:34.182Z"
      }
    ]
  }
}

Step 2: Create your First Item

Now that we've created our game's collection for our items, let's create our first item!

To create an item for our collection, we're going to use the POST /v1/collections/{collectionId}/items endpoint.

We'll need to provide the following arguments to create a collection item using the creation endpoint.

  • id: A unique id identifying this specific item. If an id for an existing item is used, the item for that id will be overridden with the provided item data.
  • name: This one's simple, what is the name of our item? Perhaps it's a Fire Dagger in this example.
  • description: Every good item has some lore, or technical information attached to it that players can read to more deeply understand the items purpose. This is a great place to put that.
  • imageUrl: You can provide the image URL of this item, or optionally upload an image using the imageBase64 fields which we won't be using for this example. Images can be JPEG, PNG, GIF or WEBP format.

Additionally, we'll need to provide our game's secretKey for the X-Authorization header, as well as our game's walletDecryptKey for the X-Wallet-Decrypt-Key header.

After we successfully make the API request to create our item, we'll receive a response with a Transaction object, confirming the item was successfully created within the collection, that looks something like this.

{
  "id": "71d0ce26-6b03-4408-aadf-8e132423fba7",
  "contractId": "739f2147-9987-45c0-8010-46cafc583cf8",
  "walletId": "b32f7381-2e6b-403a-9b6a-f6da1d8e8d74",
  "function": "setItemURI",
  "args": [
    1,
    "ipfs://QmP36ez8TfGQMB9RrtYqvQNHsK8naHkxq9QgSxq4P1K1kd"
  ],
  "hash": "0x400e288c0eb3a98a3f8a2c380d6396bf2ad0a4c0ba849c8009866f78158d9ec9",
  "updatedAt": "2022-10-28T23:49:13.494Z",
  "createdAt": "2022-10-28T23:49:13.494Z"
}

Step 3: Mint your First Item

We've created our first item, but, no one owns any amount of that item yet! Creating an item like in the previous step sets your item's data within your collection, but it does not create any individual instances of that item owned by anyone.

We're going to mint some of the previously created item to one of our players in this step. This will give the player ownership of some specific quantity of the item, from there the player can trade, transfer or use the item for whatever it does in our game.

To mint an item from our collection, we're going to use the POST /v1/collections/{collectionId}/items/{collectionItemId}/mints endpoint.

We'll need to provide the following arguments to create a collection item using the mint endpoint.

  • address or walletId: An EVM address, or MetaFab wallet id to mint to.
  • quantity: The quantity of our item to mint. We'll mint 4 of our previously created item for this example.

The collectionId and the id of the collection item we want to mint is supplied in the path for the API request.

Additionally, we'll need to provide our game's secretKey for the X-Authorization header, as well as our game's walletDecryptKey for the X-Wallet-Decrypt-Key header.

After we successfully make the API request to create our item, we'll receive a response with a Transaction object, confirming the item was successfully minted the provided item id from the collection to the address or wallet id provided. That transaction object response looks something like this.

{
  "id": "d4ad2e78-a7f1-4a0d-8e7f-d642c5c03433",
  "contractId": "739f2147-9987-45c0-8010-46cafc583cf8",
  "walletId": "b32f7381-2e6b-403a-9b6a-f6da1d8e8d74",
  "function": "mintToAddress",
  "args": [
    "0x1061B23BF88AD944d621EA6a8c251ba26A0ac007",
    "1",
    4
  ],
  "hash": "0x5a9ceef987998b796e9b3657d7cf8222609bf831b963d2c8d79c7df82791c168",
  "updatedAt": "2022-10-29T00:00:03.591Z",
  "createdAt": "2022-10-29T00:00:03.591Z"
}

Step 4: Check Inventory (Item Balances)

A common operation for any game is retrieving a player's inventory. With MetaFab item collections, that's no problem.

We're going to check the inventory, which is the same as checking the balance of all items owned by a player, using the GET /v1/collections/{collectionId}/balances endpoint.

We'll need to provide the following arguments to query the balance of all items owned by an address or MetaFab wallet id.

  • address or walletId: An EVM address, or MetaFab wallet id to query the balance of. This is a query parameter.

After we successfully make the API request, we should receive a response that looks like this.

{
  "1": "4"
}

The response structure is a plain object with the object keys representing known item id's within your collection, and the value of each key being the currently held quantity of that item id for the address or walletId queried.

Step 5: Get Collection Item Data

Finally, there will often be cases when you need to retrieve the data specific to each item within a collection, or paginate available items, etc. This includes things like item name, image url, attributes, custom data, and more.

MetaFab offers many different endpoints to query item data, but for this example we're going to retrieve the data for all items in our collection with one GET request.

You can do this efficiently using MetaFab's GET /v1/collections/{collectionId}/items.

Simply provide the collectinId you want to retrieve item data for as a URL parameter as required by the API endpoint, and you'll receive a response that looks something like this.

[
  {
    "id": 1,
    "image": "https://static.wikia.nocookie.net/skyrim_gamepedia/images/4/47/ElvenDaggerofFire.png/revision/latest/scale-to-width-down/200?cb=20120502170251",
    "name": "Fire Dagger",
    "description": "A blazing dagger imbued with power."
  }
]

Going Further

MetaFab's collection and item APIs are very extensive, capable and scalable. We recommend you take some time to go through the API reference related to Collections here.

If you have any questions or ideas on how you might want to use our Collection APIs, head on over to our Discord.

Updated 4 months ago