Skip to main content

Use case: Marketplace

This page outlines how developers can use the Unity zkEVM API package to display active listings.

This can be useful for managing the players NFT stacks which are for sale in your in-game marketplace.
Unity zkEVM API MarketplaceUnity zkEVM API Marketplace
💡Who is this for?
Developers who want to use the zkEVM API in Unity.

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.


Related content