Use case: Marketplace
This can be useful for managing the players NFT stacks which are for sale in your in-game marketplace.
Overview
Displaying a player's active NFT listings is a common requirement of an in-game marketplace.
To do this, you can simply send a request to the Immutable zkEVM API to fetch the NFTs owned by a player using the OnlyIfHasActiveListings flag and
then processing the request to display the NFTs in your in-game marketplace.
Displaying NFT stacks
To display NFT stacks, you can use the Search NFT stacks endpoint, which retrieves stacks of NFTs grouped by their metadata attributes.
using System.Collections.Generic;
using Immutable.Api.ZkEvm.Api;
using Immutable.Api.ZkEvm.Client;
private readonly MetadataSearchApi m_MetadataSearchApi =
new(new Configuration { BasePath = "https://api.sandbox.immutable.com" }); // Or "https://api.immutable.com"
var result = await m_MetadataSearchApi.SearchStacksAsync(
"imtbl-zkevm-testnet", // Or "imtbl-zkevm-mainnet"
new List<string> { "NFT_CONTRACT_ADDRESS" }, // Replace with the NFT contract address
onlyIfHasActiveListings: true // Set to true to only show NFTs with active listings
);
Searching for NFTs by traits
You can search for NFTs with specific metadata attributes by providing the desired traits as filters.
You may hardcode these traits directly into the game, but you can also dynamically retrieve them using the Get list of metadata attribute filters endpoint.
Fetching metadata attribute filters (optional)
using Immutable.Api.ZkEvm.Api;
using Immutable.Api.ZkEvm.Client;
private readonly MetadataSearchApi m_MetadataSearchApi =
new(new Configuration { BasePath = "https://api.sandbox.immutable.com" }); // Or "https://api.immutable.com"
// Fetch metadata attribute filters for a given NFT contract
var filtersResponse = await m_MetadataSearchApi.ListFiltersAsync(
chainName: "imtbl-zkevm-testnet", // Or "imtbl-zkevm-mainnet"
contractAddress: "NFT_CONTRACT_ADDRESS"); // Replace with the NFT contract address
var filters = filtersResponse.Result.Filters;
Searching for NFTs with specific traits
Whether you hardcode the traits or fetch them dynamically, you can filter NFTs based on metadata attributes.
using System.Collections.Generic;
using Immutable.Api.ZkEvm.Api;
using Immutable.Api.ZkEvm.Client;
private readonly MetadataSearchApi m_MetadataSearchApi =
new(new Configuration { BasePath = "https://api.sandbox.immutable.com" }); // Or "https://api.immutable.com"
// Define filters for metadata attributes
var filters = new Dictionary<string, object>
{
{ "Attribute1", new { values = new List<string> { "Desired_Attribute1_Value" }, condition = "eq" } },
{ "Attribute2", new { values = new List<string> { "Desired_Attribute2_Value" }, condition = "eq" } }
};
// Serialise the filters to JSON
var trait = filters.Count > 0 ? JsonConvert.SerializeObject(filters) : null;
// Search for NFT stacks using the filters
var result = await m_MetadataSearchApi.SearchStacksAsync(
"imtbl-zkevm-testnet", // Or "imtbl-zkevm-mainnet"
new List<string> { "NFT_CONTRACT_ADDRESS" }, // Replace with the NFT contract address
onlyIfHasActiveListings: true, // Set to true to only show NFTs with active listings
traits: trait // Use the serialised filters here
);
Example in-game marketplace
You can view an example of an in-game marketplace in the sample game here, which also utilises the Search NFT stacks endpoint. This example builds upon the concepts presented in the Build a game with Unity tutorial.