NFT Rarity API – How to Get an NFT’s Rarity Ranking – Moralis Web3

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:

import fetch from 'node-fetch';

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
};

fetch('https://deep-index.moralis.io/api/v2.2/nft/0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB/1?chain=eth', options)
 .then(response => response.json())
 .then(response => console.log(response))
 .catch(err => console.error(err));

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: 

1. The collection’s contract follows the ERC-721 or ERC-1155 standards. 
2. The number of NFTs in the collection is fewer than 50,000.
3. 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:

1. Get a Moralis API Key
2. Write a Script Calling the getNFTMetadata Endpoint
3. Run the Code

However, before moving on, you need to take care of a couple of prerequisites. 

Prerequisites

Before continuing with the first step, ensure you have the following ready:

Step 1: Get a Moralis API Key

Click the ”Start for Free” button at the top right and set up your Moralis account: 

Once you log in, you’ll find your API key directly under the ”Home” tab: 

Copy and keep the key for now, as you’ll need it in the following step.

Step 2: Write a Script Calling the getNFTMetadata Endpoint

Launch your preferred IDE, set up a folder, and initialize your project with the following terminal command:

npm init

Install the required dependencies by running the commands below in your terminal:

npm install node-fetch --save
npm install moralis @moralisweb3/common-evm-utils

Add "type": "module" to your ”package.json” file:

Create an ”index.js” file and add the following code:

import fetch from 'node-fetch';

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
};

fetch('https://deep-index.moralis.io/api/v2.2/nft/0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB/1?chain=eth', options)
 .then(response => response.json())
 .then(response => console.log(response))
 .catch(err => console.error(err));

Replace YOUR_API_KEY with the key you copied during the first step, and configure the address and tokenId parameters:

Step 3: Run the Code

Execute the following terminal command in your project’s root folder to run the code: 

node index.js

In return, 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'
}

As you can see, the response contains three parameters that we’re particularly interested in: rarity_rank, rarity_percentage, and rarity_label: 

//...
  rarity_rank: 7247,
  rarity_percentage: 72.47,
  rarity_label: 'Top 73%',
//...

Congratulations! You now know how to get an NFT’s rarity ranking using our NFT Rarity API! 

NFT Rarity API Use Cases

The NFT Rarity API has many use cases, as many platforms can benefit from NFT rarity-related data. Here are three key examples: 

• Web3 Games: NFT-based Web3 games can benefit from rarity-related data, giving users better insight into how unique their in-game assets/items actually are. 

• NFT Marketplaces: With rarity rankings, it’s possible for NFT marketplaces to give users better insight into the uniqueness of NFTs being traded on the platform. This will help traders make more informed investment decisions.

• Token Analytics: Token analytics platforms can give users deeper insight into the value of NFTs with our NFT Rarity API. 

The use cases above are only three examples, and the NFT Rarity API will be useful for most platforms that need access to NFT data! 

Beyond the NFT Rarity API – Exploring Moralis’ APIs & RPC Nodes

Moralis is the leading data provider within the crypto space. In our suite of development tools, you’ll find next-generation RPC nodes and multiple use case-specific APIs, including the Wallet API, Token API, Streams API, etc. As such, when using Moralis, you get all crypto data in one place.

But what makes Moralis special? 

• One Call – All the Data: With our APIs and Extended RPC Methods, you get more data with fewer calls. Fetch a wallet’s full history, token balances with prices, and much more with single requests. 
• Truly Cross-Chain: Moralis supports all major chains, including Ethereum, Base, Optimism, BNB Smart Chain (BSC), and many more. Experience full feature parity across these networks so you can streamline your developer experience. 
• Enterprise-Grade Security: Moralis is SOC 2 Type 2 certified, highlighting our commitment to top-tier security and reliability. 

Now, let’s dive deeper into our suite of development tools, starting with the APIs.

Web3 APIs

Our suite of Web3 APIs consists of several use case-specific interfaces. Here are three key examples: 

• Wallet API: The Wallet API is a premier tool for building wallets and integrating wallet functionality into dapps. Use this interface to fetch any wallet’s full history, net worth, profitability, token balances, and much more. 
• Token API: Moralis’ Token API is your go-to tool for ERC-20 data, supporting every single token across all major chains. Get token balances, transactions, prices, and more with one API call. 
• Streams API: The Streams API is the industry’s leading real-time data solution. Set up Web3 data pipelines at the click of a button to stream data directly into the backend of your dapps as soon as on-chain events occur. 

Check out the Web3 API page to learn more about all our interfaces! 

RPC Nodes

With Moralis’ premier node service, you can now seamlessly access RPC nodes for all major chains at the click of a few buttons. Supported chains include Ethereum, Polygon, Base, Optimism, and many more! 

What makes our RPC nodes unique? 

• Speed: Our RPC nodes are lightning-fast, with response times from 70 ms. 
• Reliability: Experience 99.9% reliability with Moralis’ RPC nodes.
• Extended RPC Methods: With our Extended RPC Methods, you can now seamlessly query decoded, human-readable data with your nodes. 

To learn more about this, check out our RPC nodes page! 

Summary: NFT Rarity API – How to Get an NFT’s Rarity Ranking

NFT rarity is a crucial concept for the NFT market, driving demand and influencing the price of individual tokens. However, it’s quite challenging to determine the rarity of an NFT, as you need to compare traits in collections, rank these traits, and assign a score. We know the struggles of doing so, which is why we introduced our NFT Rarity API! 

The NFT Rarity API makes it easy for anyone to seamlessly query trait data and access rarity rankings for ERC-721 and ERC-1155 NFT collections. As such, it’s now easier than ever to get an NFT’s rarity ranking. 

To demonstrate the accessibility of this premier feature, check out this sample script showing you how easy it is to fetch the rarity ranking of an NFT: 

import fetch from 'node-fetch';

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
};

fetch('https://deep-index.moralis.io/api/v2.2/nft/0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB/1?chain=eth', options)
 .then(response => response.json())
 .then(response => console.log(response))
 .catch(err => console.error(err));

In return for calling the script 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'
}

This response is enriched with three key parameters: rarity_rank, rarity_percentage, and rarity_label:

//...
  rarity_rank: 7247,
  rarity_percentage: 72.47,
  rarity_label: 'Top 73%',
//...

That’s it; getting an NFT’s rarity ranking is this easy, thanks to Moralis’ NFT Rarity API! 

If you liked this NFT Rarity API article, consider reading more guides here on the Moralis blog. For instance, check out our Address Labeling API guide or learn how to get token prices with an RPC node. 

Also, if you wish to use the NFT Rarity API yourself, don’t forget to sign up with Moralis. You can create an account free of charge, and you’ll get immediate access to all our industry-leading development tools.