How to stream real time NFT events

Obtaining real-time NFT data is challenging

If you’re a developer building an application or service that requires real time updates on NFT data and transactions, obtaining reliable, timely sources is challenging for a number of reasons.

First, NFT activity is moving across chains, requiring developers to interface with the different ways that each chain (including L1s, L2s, and side-chains) implement NFT standards. Even with a working implementation for a given chain, querying the current state of NFT data requires multiple steps:

• Setting up a connection to the network directly via a node, or via an RPC node provider
• Continually polling for new blocks
• Checking and extracting the contents of each transaction
• Filtering based on the contract(s) or wallet(s) of interest
• Taking care of any edge cases for the contract or standard(s) involved
• Polling the metadata and / or media of any NFTs found, and comparing it against the prior state

Second, beyond basic metadata and transfers, obtaining detailed information on the sales of NFTs is even more complicated: some marketplaces conduct off-chain sales, and each NFT sales contract has a different implementation to consider.

Finally, developers must also decide on the querying method to obtain this data. Polling an endpoint interfaced with a node provider is one option, but this approach also comes with a scoping challenge – a developer may only be interested in the events for a specific wallet, or contract, and filtering the entire set of events from a chain will be inefficient.

For this use case, where obtaining events in real time is important, and polling would be inefficient or not feasible, a webhook may be the right choice.

The SimpleHash webhook API makes this easy

At SimpleHash, we’ve built a stable and reliable webhook service to deliver NFT events in real-time, abstracting away these challenges.

Using the webhook API, developers can subscribe to multiple types of events, including:

• Inbound NFT transfers to specific wallets
• Outbound NFT transfers from specific wallets
• Transfers of specific NFTs
• Transfers occurring for NFTs from a specific contract
• All NFT metadata updates occurring on those from a specific contract
• All NFT metadata updates occurring on those from a specific chain

Subscribing to these events is easy, and flexible, with the ability to specify multiple wallet addresses, nfts, contracts, or chains per webhook subscription, depending on the developer’s use case.

Once set up, developers will receive an ongoing stream of updates, based on the parameters chosen. There’s no need to worry about the underlying implementation of NFT data, to build custom logic for different chains, or to continually re-poll for the latest data.

In the next section, we’ll walk through setting up a basic webhook to stream metadata updates on a given NFT contract.

What is meant by a “metadata update”? Many NFTs have pointer URIs within their on-chain data that reference off-chain metadata. This metadata can be nearly anything, but it typically contains additional context or information about the NFT, such as a link to a media file, key value pairs, or a json object. A metadata update refers to a change in this off-chain metadata information.

For example, the CloneX NFT, with token ID 5142, on contract address 0x49cf6f5d44e70224e2e23fdcdd2c053f30ada28b, on ethereum contains multiple key value pairs describing its traits (hair, clothing, etc), and a link to its original media file, located at https://clonex-assets.rtfkt.com/images/5142.png. For many NFT collections, metadata can change over time, or be dynamic, depending on their purpose or type (collectible, an in-game item, a quest reward, etc).

The next section assumes some familiarity with modern web and server frameworks, but should only take a few minutes to get up and running, and streaming metadata updates.

Streaming metadata updates for a given NFT contract

The first step is to have an endpoint ready in your client application to accept inbound events. This can be set up using any framework you like, but it should be able to accept POST requests. (e.g. https://examplenftapplication.com/webhook_receiver).

Next, if you don’t have one already, you’ll need a SimpleHash API key, which can be obtained for free from the SimpleHash developer portal.

Next is creating the webhook subscription. The API documentation for doing so can be found here, but to break it down:

• Send a POST request to the SimpleHash API to setup the webhook subscription with the desired parameters
• In our case, we’re going to subscribe to all metadata updates on the OpenSea shared ethereum storefront, which is at the address 0x495f947276749ce646f68ac8c248420045cb7b5e
• Our POST request to setup the webhook will look something like this (in curl format):

curl –request POST \

    –url https://api.simplehash.com/webhook_api/v0/webhook \

    –header ‘X-API-KEY: ${YOUR_API_KEY} \

    –header ‘accept: application/json’ \

    –header ‘content-type: application/json’ \

    –data ‘

{

   “webhook_url”: “https://example.com/webhook_listener”,

   “event_types”: [

       “contract.nft_metadata_update”

   ],

   “contract_addresses”: [

       “ethereum.0x495f947276749ce646f68ac8c248420045cb7b5e”

   ],

“webhook_secret”: “d3pxazhtNnhnaBHuN3FhTJX0aDZh7mxj”

}

We’re also including a webhook secret parameter, which is best practice for ensuring the security of streamed events. (More info about this can be found here)

Assuming a successful 200 response from your POST request, your webhook subscription will be set up, and you will start receiving events at the specified endpoint. The payload for events being streamed will look similar to this:

For NFT metadata updates, they will be sent anytime any of the following fields on an NFT changes:

• nft_id
• name
• description
• image_url
• video_url
• audio_url
• model_url
• previews
• extra_metadata

If you need to list, update, or delete your webhook subscription, that’s also easy to accomplish.

What can you build with this?

With this webhook subscription setup, you can use the data in any which way that makes sense for your application. NFT metadata updates are useful for building a wide range of different applications, including:

• An NFT reveal / drop application. Many NFT collections don’t reveal their final metadata or media until well after their initial mints, and it can be challenging to keep track of when this occurs. Doing so reliably requires keeping track of on-chain events, events from various marketplaces, and employing a number of other tracing heuristics. SimpleHash’s indexing platform has a built-in automatic refresh system to do all this, detecting reveals and drops when they occur, and then publishing these events to the relevant webhooks.
• With real-time updates, developers could build an application that displays prominent or interesting NFT collections to an end-user, and reflect the latest information post reveal or drop

• NFT games. Many NFT gaming applications involve updates to the NFT metadata on certain collections, such as the traits of particular items, or characters. These can be dynamic in nature, and change after different events (such as a player taking a certain action, or unlocking a certain set of content).
• To provide a seamless gaming experience, it is important that these state changes are reflected as quickly as possible. Continually polling specific gaming NFT contracts can be inefficient, so webhooks are an ideal solution for capturing and ingesting these events as quickly as possible.

• NFT wallets. Wallet developers have an interest in ensuring that the collectibles or NFTs shown to their users reflect the latest and most up to date metadata and media. Depending on their architecture or set up of their client application, publishing updates on collections of interest, or notifying users of drops and reveals via webhooks can be a better alternative to polling.

There are plenty of other potential use cases – and if you’re building in the space, or have plans to do so, please get in touch. The goal for the SimpleHash webhook API is to provide developers with the easiest, most reliable solution for streaming real time NFT-related events. We love chatting with builders and projects in the space – if you have more questions about the webhook API (or the SimpleHash platform overall), say hi at hello@simplehash.com.

‍