Moralis Web3: A Guide to Obtaining an NFT's Rarity Ranking with NFT Rarity API

Listen to this article

Looking for the easiest way to get an NFT’s rarity ranking? If so, you’ve come to the right place. In today’s guide, we’ll introduce you to Moralis’ NFT Rarity API. This innovative interface introduces a few new endpoints and enriches our API responses with comprehensive NFT rarity data. As such, you can now query an NFT’s rarity ranking with a single request. Are you eager to learn how this works? Check out the sample script below, where we fetch the metadata of an NFT:

In return for calling the endpoint above, you’ll get the metadata of the specified NFT. Here’s a sample response:

{
amount: ‘1’,
token_id: ‘1’,
token_address: ‘0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb’,
contract_type: ‘CRYPTOPUNKS’,
owner_of: ‘0xffa914c83d851b9fe372e4ba6a6e131373aa16ab’,
last_metadata_sync: ‘2024-09-05T08:44:23.476Z’,
last_token_uri_sync: ‘2024-09-05T08:44:23.393Z’,
metadata: ‘{“image”:”https://www.larvalabs.com/cryptopunks/cryptopunk001.png”,”name”:”CryptoPunk 001″,”attributes”:[“Smile”,”Mohawk”],”description”:”Male”}’,
block_number: ‘16079985’,
block_number_minted: null,
name: ‘CRYPTOPUNKS’,
symbol: ‘Ͼ’,
token_hash: ‘a99d02058e62e327e79aabd57e0b88a3’,
token_uri: ‘Invalid uri’,
minter_address: null,
rarity_rank: 7247,
rarity_percentage: 72.47,
rarity_label: ‘Top 73%’,
verified_collection: true,
possible_spam: false,
collection_logo: ‘https://i.seadn.io/gae/BdxvLseXcfl57BiuQcQYdJ64v-aI8din7WPk0Pgo3qQFhAUH-B6i-dCqqc_mCkRIzULmwzwecnohLhrcH8A9mpWIZqA7ygc52Sr81hE?w=500&auto=format’,
collection_banner_image: ‘https://i.seadn.io/gae/48oVuDyfe_xhs24BC2TTVcaYCX7rrU5mpuQLyTgRDbKHj2PtzKZsQ5qC3xTH4ar34wwAXxEKH8uUDPAGffbg7boeGYqX6op5vBDcbA?w=500&auto=format’
}

In addition to metadata, the response contains three key rarity parameters: rarity_rank, rarity_percentage, and rarity_label:

//…
rarity_rank: 7247,
rarity_percentage: 72.47,
rarity_label: ‘Top 73%’,
//…

That’s it; fetching an NFT’s rarity is simple when working with Moralis. However, if you want a more in-depth explanation of how this works, join us in today’s guide as we lay it all out for you.

Are you eager to start leveraging our APIs yourself? Don’t forget to sign up with Moralis. You can set up your account for free, and you’ll gain immediate access to our APIs and premier RPC nodes!

Overview

The concept of rarity is important for the NFT market as it affects the price of individual tokens and drives demand. However, determining the rarity of a token is easier said than done, as you need a solid system to determine an NFT’s uniqueness. And coming up with a system is a tedious and time-consuming task. Fortunately, it is with this in mind that we introduced our NFT Rarity API.

With Moralis’ NFT Rarity API, you can now effortlessly get any NFT’s rarity ranking with a single API request. But how does this work? How is our rarity ranking calculated? And what endpoints are supported? For the answers to these questions, tag along in this tutorial. Let’s dive straight in!

What is NFT Rarity?

NFT rarity refers to the uniqueness of an NFT within a particular collection, which is usually determined by how common or uncommon the token’s attributes/traits are. In NFT collections, certain characteristics or traits – such as background, color, accessories, etc. – can be more rare than others. The less frequently a trait occurs, the rarer and potentially more valuable the NFT is considered to be.

But why does NFT rarity matter?

NFT rarity plays an essential role in the value and desirability of tokens. Collectors, investors, and crypto enthusiasts often search for NFTs with rare traits, as they generally hold greater value in the long term.

While rarity can be calculated in multiple ways, it typically involves analyzing the frequency of certain traits across the entire collection. Based on this, a rarity score is assigned, and each NFT is ranked accordingly.

All in all, the concept of NFT rarity is fundamental to the market, driving demand and affecting the price of individual NFTs!

Introducing Moralis’ NFT Rarity API – The Easiest Way to Get an NFT’s Rarity Ranking

With Moralis’ introduction of the NFT Rarity API, you can now seamlessly get an NFT’s rarity ranking without breaking a sweat. The NFT Rarity API introduces a few new endpoints and enriches our API responses with rarity-related data. As such, when querying NFT balances, metadata, collections, etc., you’ll automatically get the rarity ranking of all NFTs!

The NFT Rarity API assigns each NFT three key parameters:

rarity_rank: A numerical rank based on the NFT’s rarity score.
rarity_percentage: A percentage indicating the token’s rarity relative to the entire collection.
rarity_label: A label describing how rare the NFT is (e.g., “Top 5% rarity”).

All in all, the NFT Rarity API makes it easy for you to seamlessly query an NFT’s rarity ranking with just a single API call!

How is the Rarity Ranking Calculated?

Moralis’ NFT rarity algorithm is a custom-designed method that calculates the rarity of any given token within a collection with precision. The algorithm factors in the total number of tokens in the collection, the number of copies of the NFT, and the traits that contribute to an NFT’s uniqueness. The formula assigns a numerical value to each trait, which is then added together to determine the overall rarity score.

Within an NFT collection, each trait is analyzed and assigned the following three:

count: The total number of occurrences of this attribute/trait.
percentage: The percentage of tokens that possess the attribute/trait.
rarity_label: A label showing the rarity based on the percentage (e.g., ”Top 5% trait”).

From there, each NFT is then assigned the parameters described in the previous section:

rarity_rank
rarity_percentage
rarity_label

What Collections Does the NFT Rarity API Support?

The NFT Rarity API supports ERC-721 and ERC-1155 collections with a maximum limit of 50,000 tokens. Rarity calculations are only performed when the conditions below are met:

The collection’s contract follows the ERC-721 or ERC-1155 standards.
The number of NFTs in the collection is fewer than 50,000.
The metadata and traits for all tokens in the collection have been requested.

What Endpoints Does the NFT Rarity API Cover?

Here’s a list of new endpoints that are available:

/nft/:address/traits: Get NFT traits by collection (one response, limited to 5,000 traits).
/nft/:address/traits/paginate: Fetch NFT traits by collection (paginated, no limit).
/nft/:address/nfts-by-traits: Get NFTs by traits.
/nft/:address/traits/resync: Resync NFT traits by collection.

NFT rarity data has been added to the following endpoints:

/:address/nfts: Get NFTs by wallet.
/nft/:address: Fetch NFTs by collection.
/nft/:address/owners: Query NFT owners by collection.
/nft/:address/:token_id/owners: Get NFT owners by token id.
/nft/:address/:token_id: Fetch NFT metadata.

Check out the NFT Rarity documentation page to learn more!

Full Tutorial: How to Get an NFT’s Rarity Ranking in 3 Steps

We’ll now walk you through a tutorial on how to get an NFT’s rarity using the Moralis NFT Rarity API. With this premier feature, you can easily get the data you need in three simple steps: