Skip to main content

Display user inventories

Estimate time to complete: 20 minutes

Learn how to display user-owned assets in your application.

At the core of all Web3 games is the concept of true asset ownership, so it is critical for games and marketplaces to offer users a complete and up-to-date view of the assets they own. There are a number of ways to do this:

MethodDescription
Direct Event MonitoringMonitor events yourself by connecting to a blockchain RPC and filtering blockchain logs according to your use case. Provides maximum customisability, but you will need to maintain your own infrastructure and invest in scalability and performance.
Immutable Blockchain Data APIsImmutable provides a strong set of default APIs for accessing blockchain data which is regularly used by games, optimised for the scale required by mainstream-quality games.
Third Party IndexerThere are many blockchain data indexers which provide similar functionality. Some of these providers expose REST APIs and others provide Graph-based interefaces for querying. Ensure your chosen indexer supports your chosen blockchain (e.g. Immutable zkEVM).

The following tutorial assumes you're using Immutable's Blockchain Data APIs.

NFT Inventories​

Most Web3 game items such as weapons, powerups and skins are powered by non-fungible tokens (NFTs). Partners can use Immutable's Blockchain Data APIs product to track player inventory changes in their applications by either:

  1. Loading ownership data directly from Immutable's APIs
  2. Updating your own inventory backend using webhooks from Immutable

Option 1: Loading ownership data from Immutable's APIs​

Immutable provides an endpoint to returns all the NFTs that belong to a particular owner wallet address:

listNFTsByAccountAddress.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listNFTsByAccountAddress(
  chainName: string,
  contractAddress: string,
  accountAddress: string,
): Promise<blockchainData.Types.ListNFTsResult> {
  return await client.listNFTsByAccountAddress({
    chainName,
    contractAddress,
    accountAddress,
  });
};

Polling Immutable's Blockchain Data API is a great way to get additional details regarding an asset or an activity. See the below table for useful endpoints that can be harnessed for the purpose of monitoring updates in players' inventories.

Data EndpointsDescription
ActivitiesThis endpoint provides historical "activities" (e.g. NFT mints, transfers, burns and trades) on Immutable-supported blockchains. No NFT metadata is present in these API responses.
NFTThis endpoint provides details on NFT assets including metadata. The NFT Owner feature should be used to determine who is the current custodian of a specific NFT.
CollectionsThis endpoint provides details on a specific collection including metadata. The collections endpoint provides additional information as to the grouping of each NFT represented within the collection. No NFT ownership information is delivered with this endpoint.

Option 2: Updating your own inventory backend using webhooks from Immutable​

For applications which want to maintain their own asset databases (for performance or customisation), Immutable can also send webhooks whenever an asset's ownership/history or metadata is updated. You can complement these webhooks with synchronous calls to the NFT endpoint for more detail if necessary.

Identify what type of events your application would like to be notified of via a webhooks stream​

Immutable's Blockchain Data API can send notifications for various on and off-chain events through a single webhook connection.

Event GroupEvent TypesDescription
Activitiesimtbl_zkevm_activity_mint; imtbl_zkevm_activity_burn; imtbl_zkevm_activity_trasnfer; imtbl_zkevm_activity_sale; imtbl_zkevm_activity_deposit; imtbl_zkevm_activity_withdrawalThis event provides details on minting (NFT), transferring (NFT), burning (NFT), trading (NFT), withdrawals (ERC20) and deposits (ERC20) on Immutable's zkEVM blockchain. These events are a valuable resource for tracking changes in NFT ownership as they contain details of wallet addresses, facilitating ownership tracking. No metadata is present in these events.
NFTnft_updatedThis 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. No ownership information is contained within this event.
Metadatametadata_updatedThis 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. No ownership information is contained within this event.
Collectionscollection_updatedThis event provides details on newly deployed collections as well as collection updates, including metadata attributes. This event provides additional information as to the grouping of each NFT represented within each collection. No NFT ownership information is delivered with this endpoint.
Tradestrade_createdThis event signals when a trade takes place on Immutable's Global Orderbook. The details of the trade are present, including additional fees. It provides trade details, including any additional fees, as well as buyer and seller addresses. For tracking inventory changes, Immutable suggests using activities_sale events unless more specific trade details are required.

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.

note

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:

  1. Create a webhook endpoint function to handle the events sent by Immutable via POST.
  2. Share your webhook's endpoint details with Immutable.
  3. Accept the subscription invitation sent by Immutable.
  4. Begin receiving and processing webhooks as they come in.

Webhook Payload Examples​

{
    "Type": "Notification",
    "MessageId": "dca9d68e-f9b0-5b4b-aca7-8b26df34eac6",
    "TopicArn": "arn:aws:sns:us-east-2:783421985614:webhook-outbound-sandbox",
    "Message": "{\"event_name\":\"imtbl_zkevm_activity_mint\",\"event_id\":\"018b3c3d-a3aa-a4c9-4c16-dc7a2bd7d715\",\"chain\":\"imtbl-zkevm-testnet\",\"data\":{\"id\":\"018b3c3d-a377-8e68-6cab-2e8db249729a\",\"chain\":{\"id\":\"eip155:13472\",\"name\":\"imtbl-zkevm-testnet\"},\"details\":{\"to\":\"0x9c1634bebc88653d2aebf4c14a3031f62092b1d9\",\"asset\":{\"token_id\":\"123123\",\"contract_type\":\"erc721\",\"contract_address\":\"0x43c98025464e9b326be3c3782db5867073b8e78c\"},\"amount\":\"1\"},\"indexed_at\":\"2023-10-17 06:05:54.469511\",\"activity_type\":\"mint\",\"blockchain_metadata\":{\"log_index\":\"0\",\"block_number\":\"2895332\",\"transaction_hash\":\"0xa58996d4250b964799ad62afa1b6d9188df1d60fad339857ccab4388a07212af\",\"transaction_index\":\"0\"}}}",
    "Timestamp": "2023-10-17T06:05:56.378Z",
    "SignatureVersion": "1",
    "Signature": "hYHM9z0H38JA3AYO/guKTRgsxloGLx0vICVLny36gM8vfqjj1i7xzxRioWFTB+OfngE96gG+vmLmGf7W/RWkjf+dn9dKBijAtZ5CTKigkYnhmxNY1CuarAsEAzf2BlpY80fzHx+gaHaLUgaC6/DJ3ZGD1gM8SS4J5JWKWpvf7DAclGyIp8cPHCcsOcT8JBJf1Mu8Z+0sDOIhtsMD04pUn6QGAbZ82z6eG9mn1PbrocPE/8lOk8elmXdvQjVn9+FcLEIEadXG6INooJ5e5EtZuVEKXlVj9tPugwDbm/1nuWWAf2tArjGvHzIWL04IwbBMDj5Bx5cMU7ycPuLoea3ATA==",
    "SigningCertURL": "https://sns.us-east-2.amazonaws.com/SimpleNotificationService-01d088a6f77103d0fe307c0069e40ed6.pem",
    "UnsubscribeURL": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-2:783421985614:webhook-outbound-sandbox:b2be3be8-98de-4d84-b9b1-98d95859351d",
    "MessageAttributes": {
      "chain": {
        "Type": "String",
        "Value": "imtbl-zkevm-testnet"
      },
      "collection_address": {
        "Type": "String",
        "Value": "0x43c98025464e9b326be3c3782db5867073b8e78c"
      },
      "event": {
        "Type": "String",
        "Value": "imtbl_zkevm_activity_mint"
      }
    }
}

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us