Display marketplace listings
Learn how to display active listings in your marketplace in order to facilitate trade.
Marketplaces need to display listings so that users can discover and purchase NFTs. This can be done in 2 ways:
Immutable strongly recommends partners use webhook streams to keep track of orders and trades for the following reasons:
Real-time Updates: Webhooks provide real-time updates. When an event occurs, the webhook immediately triggers an action in the receiving application. This is in contrast to polling, which involves repeatedly checking for updates at predefined intervals.
Efficiency: Polling can be inefficient, especially when there are no updates. It requires regular requests to the API, even when there's no new data. In contrast, webhooks are event-driven, meaning they only send data when an event occurs, reducing unnecessary traffic and load on the server.
Reduced Latency: Webhooks minimise latency. Since they send updates in real-time, you get the latest data as soon as it becomes available. With polling, you may experience delays depending on the polling frequency.
Simplicity: Setting up a webhook involves configuring the source application to send data to a specified endpoint. Polling, on the other hand, requires writing and maintaining code to periodically query an API, making it more complex.
Overall, webhooks in Web3 gaming provide a mechanism for real-time communication and data synchronization, enabling a more dynamic and engaging gaming experience while also enhancing the operational efficiency of blockchain-based games.
Option 1: Webhooks
Webhook streams enable marketplaces and other interested parties to receive order updates in real time. The Orders event is your go-to source for achieving this use case.
To gain more insights into the assets being listed, partners can complement orders event monitoring with separate API calls or subscribe to additional webhook events.
Immutable's recommendation is for partners to develop their own backend database and subscribe to NFT and Metadata events. This approach allows them to maintain a local asset database, enhancing performance and facilitating more detailed analysis.
Identify what type of events your application would like to be notified of via a webhooks stream
Immutable's Blockchain Data API sends notifications for various events. Partners can receive multiple events groups through a single webhook connection.
The Activities event should be the primary event subscribed to for the purpose tracking inventory changes. Additional events can also be subscribed to for additional information regarding the asset, collection or transaction.
| Event Group | Event Types | Description |
|---|---|---|
| Orders | order_updated | This event signals when an order is placed or updated on Immutable's Global Orderbook. All details regarding the listing are present in this event including price, order_id, token_id, seller address and listing marketplace. No NFT metadata is delivered with this endpoint. |
| NFT | nft_updated | This event signals when an NFT is created or modified. It includes token_id to metadata_id mappings, connecting metadata stacks to individual NFTs. When used in conjunction with the metadata_updated event, it provides a comprehensive view of NFTs and their associated metadata within Immutable's ecosystem. |
| Metadata | metadata_updated | This event provides details of a metadata stack's attributes, with each stack being defined by a unique metadata_id. This event is triggered when new metadata stacks are created, as well as when existing stacks get updated through the Metadata Refresh service. |
| Collections | collection_updated | This event offers insights into newly deployed collections and updates to existing collections, providing metadata attributes. It serves as a valuable source of additional information regarding the collection to which the asset represented by the order belongs. |
Select filters for each event
Each event mentioned above can be customised with specific filters applied at the event level. This means that different events can have their own unique filters to refine the data stream as needed. For more information on each event's filters, select the links above to learn more about each event.
By default a webhook subscription will return all events from all collections on a specified chain
Request webhooks from your Partner Success representative
Contact your Immutable Partner Success representative to set up your custom webhooks connection.
Develop a webhook endpoint function
To set up your webhook, follow these steps:
- Create a webhook endpoint function to handle the events sent by Immutable via POST.
- Share your webhook's endpoint details with Immutable.
- Accept the subscription invitation sent by Immutable.
- Begin receiving and processing webhooks as they come in.
Examples
Below are some examples of order_updated events that represent activity on Immutable's Global Orderbook.
All order_updated events contain all properties of the order, but for brevity and clarity, immutable fields on the order have been trimmed from the below examples on the subsequent events.
Please be advised that all fees and quantities within our system are denoted in the smallest unit of the respective currency, and decimal representations are not supported.
For instance, IMX, which has 18 decimal places, will have a fee of 0.000000000000000001 IMX represented as "1".
Similarly, 1 IMX is represented as "1000000000000000000" in our system.
New order being placed
In this example, an order is posted on Immutable's Global Orderbook. Orders are validated asynchronously, and a number of status changes can occur before the order becomes "ACTIVE". Orders are non-executable until custody and approvals are confirmed, at which point the status is updated to "ACTIVE."
Initial pending order
"PENDING" orders have not yet been validated by the orderbook.
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
"buy": [
{
"item_type": "NATIVE",
"end_amount": "1000000",
"start_amount": "1000000",
"contract_address": ""
}
],
"hash": "0xdd62c8ff1e410075251673fdca918a1b8a26a4aaff3f558ddfe9fe88af4b30cd",
"salt": "0x52c2669364b63b85",
"sell": [
{
"token_id": "0",
"item_type": "ERC721",
"end_amount": "1",
"start_amount": "1",
"contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8"
}
],
"status":
{
"name": "PENDING",
"evaluated": false,
"started": false
},
"chain_id": "eip155:13473",
"end_time": 1697528363,
"signature": "0xb2dd0a83659d419355a6ad77ccc83c23a0d6dea6f080ecee55eb8e11cfd42848049b2649c787fa27a2caf4d340661f77d278e953fa8569d992a65883febe43ec1c",
"buyer_fees": [
{
"amount": "1",
"fee_type": "MAKER_ECOSYSTEM",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
},
{
"amount": "20000",
"fee_type": "PROTOCOL",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
},
{
"amount": "10000",
"fee_type": "ROYALTY",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
}
],
"created_at": 1697498374,
"start_time": 1697498363,
"updated_at": 1697498374,
"protocol_data": {
"counter": "0",
"order_type": "FULL_RESTRICTED",
"zone_address": "0x63441cbfbd15dd8f5e92598e535661ac5acb808e",
"seaport_address": "0x7fb7da6de152597830ed16361633e362a2f59410",
"seaport_version": "1.5"
},
"account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
}
}
Inactive order
If the user has only just approved the settlement contract, or has only just received ownership of the NFT they are listing, the order might temporarily be "INACTIVE" until those on-chain events are received by the orderbook.
In a number of scenarios, an order will transtion from "PENDING" straight to "ACTIVE".
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "INACTIVE",
"sufficient_balances": false,
"sufficient_approvals": false,
},
"updated_at": 1697498374,
}
}
Live order
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "ACTIVE"
},
"updated_at": 1697498374,
}
}
If custody of the asset referenced in the listing cannot be confirmed by Immutable, the order will remain in an "INACTIVE" state and should not be listed.
Order is executed
In this example, an order is executed on Immutable's Global Orderbook. The previous status of the order was "ACTIVE".
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "FILLED"
},
"updated_at": 1697498374,
}
}
Order is cancelled
In this example, an order is cancelled. The previous status of the order was "ACTIVE".
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "CANCELLED",
"pending": false,
"cancellation_type": "ON_CHAIN"
},
"updated_at": 1697498374,
}
}
Order expires
In this example, an order that was placed previously on the orderbook expires as it does not execute in the allocated time window. The previous status of the order was "ACTIVE".
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "EXPIRED",
},
"updated_at": 1697498374,
}
}
Order becomes inactive due to an asset transfer
In this example, an order placed previously on the orderbook becomes "INACTIVE" because the seller no longer has custody of the asset. This could be for a variety of reasons including the asset being consumed in a crafting activity or because the seller has transferred the asset to another wallet. The previous status of the order was "ACTIVE".
{
"event_name": "order_updated",
"event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
...
"status": {
"name": "INACTIVE",
"sufficient_balances": false,
"sufficient_approvals": true,
},
"updated_at": 1697498374,
}
}
Option 2: Polling
Follow the below guide to use polling as a means to track orders on Immutable's Global Orderbook.
Setup
Prerequisites
Node Version >18
To install nvm follow these instructions. Once installed, run:
nvm install --lts
- (Optional) To enable code splitting (importing only the SDK modules you need) there are additional prerequisites. See the Code Splitting section below.
Install the Immutable SDK
Run the following command in your project root directory.
- npm
- yarn
npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node
The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:
- npm
- yarn
rm -Rf node_modules
npm cache clean --force
npm i
rm -Rf node_modules
yarn cache clean
yarn install
Initialize modules
First, we'll need to set up our SDK clients. This tutorial will use the Orderbook and BlockchainData modules:
- Typescript
import { config, blockchainData, orderbook } from '@imtbl/sdk';
import { ethers } from 'ethers'; // ethers v5
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY'; // Replace with your Publishable Key from the Immutable Hub
const blockchainDataClient = new blockchainData.BlockchainData({
baseConfig: {
environment: config.Environment.SANDBOX,
publishableKey: PUBLISHABLE_KEY,
},
});
const orderbookClient = new orderbook.Orderbook({
baseConfig: {
environment: config.Environment.SANDBOX,
publishableKey: PUBLISHABLE_KEY,
},
overrides: {
// @ts-ignore FIXME
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.
- Typescript
import { blockchainData } from '@imtbl/sdk';
const listCollections = async (
client: blockchainData.BlockchainData,
chainName: string,
contractAddress: string[]
) => {
const collections = await client.listCollections({
chainName,
contractAddress,
});
};
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.
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.
- Typescript
import { orderbook } from '@imtbl/sdk';
const listListings = async (client: orderbook.Orderbook, contractAddress: string) => {
const listOfListings = await client.listListings({
sellItemContractAddress: contractAddress,
status: orderbook.OrderStatusName.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": {
"name": "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, its name, token ID, images. This data is typically stored in an asset's metadata.
- Typescript
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
});
};