Display marketplace listings in Unity

In this tutorial step, you will learn how to display active NFT listings in your game by using the Unity zkEVM API package.

This allows players to view which NFTs are currently for sale.

💡Prerequisite step

Before continuing with this step, ensure you have completed the previous display player inventory step of this tutorial series.

Overview

Displaying marketplace listings is another essential feature of a game marketplace. To make it easier for the players to find the NFTs they are interesteed in, you can filter the listings based on the NFT attributes the player wants.

We will start by fetching all the active NFT listings in your game's marketplace. Then we will show you how to fetch the available filters from the NFT contract so you can build a dynamic search filter.

Once you have displayed the filtered results, we want to show the details of a selected NFT stack including each of the listings and their prices.

In these examples, we fetch Stacked NFTs instead of individual ones. This means the results are grouped when they have the exact same metadata, which makes it much easier for players to browse the listings.

Let's get started by fetching the active NFT listings in your game's marketplace.

Displaying NFT listings

Use the Search NFT stacks endpoint to show all active listings in your in-game marketplace. This allows you to retrieve stacks of NFTs grouped by metadata attributes.

Here's an example of how to implement this:

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"

// Retrieve NFT stacks with active listings
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 // Show only NFTs with active listings
);

Check out the sample game Marketplace screen for an implementation example.

Fetch NFT attribute filters

You can fetch available attribute filters for a contract to allow users to filter and search NFTs by attributes. The Get list of metadata attribute filters endpoint returns all possible attribute types and values, helping you build dynamic search filters in your marketplace.

using Immutable.Api.ZkEvm.Api;
using Immutable.Api.ZkEvm.Client;

private readonly MetadataSearchApi m_MetadataSearchApi =
    new(new Configuration { BasePath = "https://api.sandbox.immutable.com" }); // Use "https://api.immutable.com" for mainnet

var filtersResponse = await m_MetadataSearchApi.ListFiltersAsync(
    chainName: "imtbl-zkevm-testnet", // Use "imtbl-zkevm-mainnet" for mainnet
    contractAddress: "NFT_CONTRACT_ADDRESS" // Replace with the NFT contract address
);

var filters = filtersResponse.Result.Filters;

These filters will help your users search for NFTs by their attributes. The sample game Marketplace screen implements an example of this, dynamically showing filter options for listed assets.

Search NFTs by attributes

With available filters, you can now let users search for NFTs based on specific attributes. To do this, send these filters as parameters in a call to the Search NFT stacks endpoint, as shown below:

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
);

Viewing Details of a Selected NFT

To create an Asset Details screen for a selected NFT stack, you can display comprehensive information, including listings and market data such as the last trade price and floor price.

By using the result from the Search NFT stacks call, you can access the following details for the NFT stack: stack information, market data, and active listings. The example below demonstrates how to retrieve and display these details:

using System.Numerics;

// The decimal precision of your in-game ERC20 token
int erc20Decimals = 18;

// `result` is the SearchStacksResult from SearchStacksAsync()
var stackBundle = result.Result.First();
var stack = stackBundle.Stack; // Access the Stack object from the StackBundle
var market = stackBundle.Market; // Access the Market data
var listings = stackBundle.Listings; // Access the active listings
var count = stackBundle.StackCount; // Number of NFTs in the stack

// Access stack details
string stackName = stack.Name;
string stackDescription = stack.Description;
string stackImageUrl = stack.Image; // Image URL for displaying the stack

// Access the market data
// Floor price
if (market?.FloorListing != null)
{
    decimal floorPrice = (decimal)BigInteger.Parse(market.FloorListing.PriceDetails.Amount) / (decimal)BigInteger.Pow(10, erc20Decimals);
}

// Last trade price
if (market?.LastTrade?.PriceDetails?.Count > 0)
{
    decimal lastTradePrice = (decimal)BigInteger.Parse(market.LastTrade.PriceDetails[0].Amount) / (decimal)BigInteger.Pow(10, erc20Decimals);
}

// Display listings for the stack
if (listings != null && listings.Count > 0)
{
    foreach (var listing in listings)
    {
        string tokenId = listing.TokenId;
        string amount = listing.Amount;
        decimal listingPrice = (decimal)BigInteger.Parse(listing.PriceDetails.Amount) / (decimal)BigInteger.Pow(10, erc20Decimals);
    }
}

For a more detailed implementation, see the Marketplace Asset Details screen and the Listing Object in the sample game, which provides examples of how this information can be used.

Next steps

Great, you now can fetch, filter and display the details of the active NFT listings in your game's marketplace! Next we will teach you how to create an order so it becomes active in your marketplace. Click next below to continue the tutorial.