Skip to main content

Display marketplace listings

Learn how to display active listings in your marketplace in order to facilitate trade.

Contents
💡This guide requires you to interact with assets on Immutable zkEVM
Learn how to deploy your own NFT collection here.

Marketplaces need to display listings so that users can discover and purchase NFTs.

Setup​

Prerequisites​

Node version

The Immutable SDK requires Node v18 (Active LTS version) or higher. Node v18 can be installed via nvm which allows to quickly install and use different versions of node via the command line.

The installation steps for nvm for Linux, Mac, and Windows Install & Update Script. You are now ready to install the Node LTS version:

nvm install --lts

Install the Immutable SDK​

Run the following command in your project root directory.

npm install -D @imtbl/sdk
Troubleshooting

The Immutable SDK is still in early development. Should complications arise during the installation, please use the following commands to ensure the most recent release of the SDK is correctly installed:

rm -Rf node_modules
npm cache clean --force
npm i

Dependencies​

npm install -D typescript ts-node

Initialize modules​

First, we'll need to set up our SDK clients. This tutorial will use the Orderbook and BlockchainData modules:

import { config, blockchainData, orderbook } from '@imtbl/sdk';

import { ethers } from 'ethers'; // ethers v5

const blockchainDataClient = new blockchainData.BlockchainData({
  baseConfig: new config.ImmutableConfiguration({
    environment: config.Environment.SANDBOX,
  }),
});

const orderbookClient = new orderbook.Orderbook({
  baseConfig: new config.ImmutableConfiguration({
    environment: config.Environment.SANDBOX,
  }),
  overrides: {
    provider: new ethers.providers.JsonRpcProvider(
      'https://rpc.testnet.immutable.com/'
    ),
  },
});

Listing collections​

Most marketplaces start by allowing users to see all collections on a chain. Using filters, marketplaces can provide users with a user-friendly interface from which to browse and select items from their favourite collections.

In this section we will utilize the BlockchainData module to retrieve this information.

import { blockchainData } from '@imtbl/sdk';

const listCollections = async (client: blockchainData.BlockchainData, chainName: string) => {
  const collections = await client.listCollections({
    chainName,
  });
};

Example response:

{
  "base_uri": "https://webhook.site/5ce48076-ccdf-45d7-ab2a-a315833ba60a",
  "chain": {
    "id": "eip155:13392",
    "name": "imtbl-zkevm-testnet"
  },
  "contract_address": "0x3109fe9344e3d299ab6a2b42ecacee0610f391a4",
  "contract_type": "ERC721",
  "contract_uri": "https://webhook.site/10c86fab-d5a7-4283-93c3-398fe269497b",
  "description": "OpenSea Creatures are adorable aquatic beings primarily for demonstrating what can be done using the OpenSea platform. Adopt one today to try out all the OpenSea buying, selling, and bidding feature set.",
  "external_link": "external-link-url",
  "image": "external-link-url/image.png",
  "indexed_at": "2023-07-06T01:18:40.098064Z",
  "last_metadata_synced_at": "2023-07-06T01:18:43.363814Z",
  "name": "OpenSea Creatures",
  "symbol": "TC",
  "updated_at": "2023-07-06T01:18:43.363814Z"
}

This JSON represents the metadata of a collection provided by the indexer API. It includes information such as the base URI, chain details, contract address and type (ERC721), contract URI, description, external link, image URL, timestamps, name, and symbol. The metadata provides important details about the collection, such as image, name and description which can be used in the marketplace collection display.

💡If you want more extensive search capabilities...
[Let us know](/docs/zkEVM/contact) so we can prioritize building one!

Listing orders​

Once a user has selected the collection that they want to browse the assets of, we can display all active fillable orders that are available. In this section we will use the Orderbook module in the Immutable SDK and utilize the collection filter.

For more information on this endpoint, see: Get orders.

import { orderbook } from '@imtbl/sdk';

const listListings = async (client: orderbook.Orderbook, contractAddress: string) => {
  const listOfListings = await client.listListings({
    sellItemContractAddress: contractAddress,
    status: orderbook.OrderStatus.ACTIVE,
    pageSize: 50,
  });
};
{
  "account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
  "buy": [
    {
      "item_type": "NATIVE",
      "start_amount": "1000000"
    }
  ],
  "chain": {
    "id": "eip155:13403",
    "name": "imtbl-zkevm-testnet"
  },
  "create_time": "2023-07-05T01:48:23.696122Z",
  "end_time": "2026-07-05T10:08:04Z",
  "fees": [
    {
      "amount": "10000",
      "fee_type": "ROYALTY",
      "recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
    }
  ],
  "id": "018923bc-8109-c775-2829-27dd3700e6e0",
  "protocol_data": {
    "counter": "0",
    "operator_signature": "0x1aef76023aa9040f7c1e8aa58fcbadcefb39a401c17835b80762a14bb99433ed711d34ffa2075c5b35c42d569166342761ffbe3a2f42c455843225c28819acdc1c",
    "order_type": "FULL_RESTRICTED",
    "seaport_address": "0x41388404Efb7a68Fd31d75CEf71dF91e2BDBa2fb",
    "seaport_version": "1.4",
    "zone_address": "0xcb5063b0c1dcf4f7fed8e7eaa79faf9859792767"
  },
  "salt": "0xe3deca95738ccfc4",
  "sell": [
    {
      "contract_address": "0xeee54f55c805b11bd0ebfaf800ccaeecb4a57bc0",
      "item_type": "ERC721",
      "token_id": "0"
    }
  ],
  "signature": "0x0230042e33b9fb2f73a81286eeb08c45d1ecf4b571b67a7552a73b44aac5e57421ab5c3bc0cc170a75112a8d080e568375fa469a2d44c429f57680983a4699bd1c",
  "start_time": "2023-07-05T01:48:06Z",
  "status": "EXPIRED",
  "update_time": "2023-07-05T10:09:03.732996Z"
}

This JSON represents a sell order in the NFT marketplace. It includes information such as the account address of the seller, the buy item (with its type and starting amount), the chain details, creation and update timestamps, fees information, and more. The sell item is an ERC721 NFT with a contract address and token ID. The order status is marked as "ACTIVE", indicating that the order is active.

Displaying a specific order and its asset details​

To display a particular order listing to users, it is a much more user-friendly experience to provide more information about that order, ie. the collection it is from, it's name, token ID, images. This data is typically stored in an asset's metadata.

💡No bulk retrieval yet
Please note that at the moment, there is no bulk endpoint available to retrieve NFT metadata based on IDs. However, keep an eye out for future updates on this feature.
import { blockchainData, orderbook } from '@imtbl/sdk';

const getOrderAndNFT = async (
  orderbook: orderbook.Orderbook,
  blockchainData: blockchainData.BlockchainData,
  orderId: string
) => {
  const order = await orderbook.getListing(orderId); // orderId is the UUID of the order (see listing.id)
  const nft = await blockchainData.getNFT({
    chainName: '',
    contractAddress: '', // The address of the deployed collection contract
    tokenId: '', // The ID of the minted token
  });
};
🚧Webhook-based integration coming soon
We are currently developing a webhook-based integration which will allow developers to receive and process individual events without polling our SDK functions or APIs