Use Case: Marketplace

This page outlines how developers can leverage the Unity zkEVM API package to display active listings in the game's 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 serialized 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.