NFT Rarity

The rarity of an NFT (non-fungible token) is determined by its unique attributes and the scarcity of similar items. This typically includes factors such as:

• wearable art pieces (attributes)

• rare colors/features in the NFT (attributes)

• if the combination of attributes rarely occurs in the collection (scarcity)

These attributes are tied to traits, which you can think of as the features of the NFT. For example, an NFT collection can consist of creatures with humanoid traits like feet, arms, and legs. The attributes for the feet trait could be the shoe color that the creature is wearing.

The more unique and scarce an NFT is, AKA rare, the more valuable it will be. A tried and true way to calculate rarity is to look at the attributes of a given NFT and calculate the number of occurrences for each attribute in the total collection. Fewer occurrences mean that an NFT with those attributes is considered rare.

This guide will show how you can seek some NFT alpha and quickly evaluate the rarity of an NFT using the GoldRush API!

Prerequisite

• Fetching data using APIs

• Basic familiarity with Node.js (optional)

Use Cases for Developers

There are several use cases for a developer wanting to know the rarity of an NFT. Some examples of projects leveraging NFT rarity include:

• Investment tools

• Authentication features

• Games with rare items

• NFT rarity calculators

• Wallets with unique NFT rarity features

Getting NFT Rarity Data

1

Sign up or sign in

Sign up for an API key if you haven’t gotten one yet.

2

Find the API Reference

Once signed up, navigate to the API Reference page. This is where you can try out all the GoldRush endpoints live.

3

Find the right NFT endpoints

Where you see the list of API endpoints, go to CLASS A > NFT > Core rendering. The endpoints we are interested in are:

• Get Traits for a collection
• Get Attributes for a collection trait
• Get Trait Summary for collection

The first two endpoints are especially helpful if you want to find a specific trait or attribute of an NFT. In contrast, the trait summary endpoint will allow you to scan through all the details for a collection, which is especially useful if you want to build an application that showcases the rarity of different NFTs.

4

Get traits

To understand the different trait types for a collection, such as feet and arms, let’s start with the Get Traits for a collection endpoint.

To use this endpoint, we will need the contract address of the NFT collection we want to browse and the name of the blockchain that the NFT collection is on. In this example, we’re going to use the Invisible Friends collection. From Opensea or Etherscan, we can get the contract address 0x59468516a8259058baD1cA5F8f4BFF190d30E066. We also find that this collection is on Ethereum, so we will use eth-mainnet as the chainName parameter.

5

Hit Run

Input the relevant collectionContract (in our case, 0x59468516a8259058baD1cA5F8f4BFF190d30E066) and hit Run. In this code block is a snippet of the response you will see.

This tells you all the types of traits for this NFT collection. Knowing the traits is important for understanding how many possible features an NFT in a given collection can have. Think of traits as categories for the attributes. For example, an NFT might have the attribute Red Shoes for the trait Feet. We don’t know how rare red shoes are until we examine the rest of the attributes.

"items": [
	{
		"name": "Feet"
	},
	{
		"name": "Legs"
	},
	{
		"name": "Upper Body"
	},
	{
		"name": "Sleeves"
	},
	{
		"name": "Hat"
	},
	{
		"name": "Eyes"
	},

6

Get attributes

To see all the attributes and their count for each trait, we use the Get Attributes for a collection trait endpoint. In addition to the chainName and collectionContract parameters, we now include the trait parameter. Let’s use the first trait from our previous response and input Feet. Hit Run and you should see a similar response.

This response tells us how many occurrences of each attribute exist for the trait Feet. The number of occurrences is what determines the rarity of each attribute. We could manually calculate these as follows: (count/number of IDs for the collection)

Or, we could just use the last endpoint in this guide which will give us all the information in one API call!

"items": [
	{
		"values": [
			{
				"value": "Bubblegum Blue Sneakers",
			"count": 220
			},
			{
				"value": "Dark Blue Slippers",
			"count": 222
			},
			{
				"value": "Blue Shoes",
			"count": 400
			},
			{
				"value": "Summer Day Sneakers",
			"count": 236
			},

7

Get trait summary

Go to Get Trait Summary for a collection. Using the same parameters for chainName and collectionContract, hit Run. The response you see will look the same as our previous step but will include values for all trait types!

Also contained in the response, is the trait_percentage field, AKA the rarity of a certain trait based on how often it occurs in the collection.

In this snippet of the API response, we can see that 267 NFTs in the collection have this trait for the trait type Shoe Gum. Out of the total number of IDs in the collection (4999 -also contained in the response), the percentage of this trait occurring is 5.34%.

(267/4999) = 0.05341068213642729

(0.05341068213642729 * 100) = 5.34%

"name": "Feet",
	"attributes": [
		{
			"values": [
				{
					"value": "Bubblegum Blue Sneakers",
					"count": 220
				},
				{
					"value": "Dark Blue Slippers",
					"count": 222
				},
				{
					"value": "Blue Shoes",
					"count": 400
				},

...

"name": "Upper Body",
	"attributes": [
		{
			"values": [
				{
					"value": "Yellow / Blue Hoodie Jacket with Hood Down",
					"count": 45
				},
				{
					"value": "Grey / White V-Neck Sweater Vest and Shirt",
					"count": 133
				},
				
...

"name": "Shoe Gum",
"attributes": [
	{
		"values": [
			{
				"value": "Gum",
				"count": 267
			}
		],
		"trait_type": "Shoe Gum",
		"unique_values": 1
	}
],
"value_type": "string",
"value_numeric": null,
"value_string": {
		"name": "Shoe Gum",
		"token_count": 267,
		"trait_percentage": 0.05341068213642729
	}
},

Sample Code

Sample code for making a request to the Get Trait Summary for a collection endpoint and searching for the rarity of a given trait name:

const apiKey = // your API key (Warning: do not supply it like this in the production environment)

const getDataFromCovalentAPI = async (nftContract) => {
	const getTraitSummaryEndpoint = '<https://api.covalenthq.com/v1/eth-mainnet/nft/${nftContract}/traits_summary/>'
	const res = await fetch(getTraitSummaryEndpoint, {method: 'GET', headers: {
      "Authorization": `Basic ${btoa(apiKey + ':')}`
    }})
	
  return res.json()
}

const getTraitPercentage = ( trait, res ) => {
    const match = res.data.items.find(item => trait === item.name)
    if (match) {
        return match.value_string.trait_percentage
    } else {
        console.log("Trait not found.")
    }
}

const main = async () => {
		const collectionAddress = '0x59468516a8259058baD1cA5F8f4BFF190d30E066'
    const trait = "Special"
		const data = await getDataFromCovalentAPI(collectionAddress)
    console.log(`Trait percentage of ${trait} is:`, getTraitPercentage(trait, data))
}

main()

Conclusion

To summarize, NFT rarity is determined by the uniqueness of its attributes and the scarcity of similar items. This includes factors such as wearable art pieces, rare colors or features, and whether it is part of a limited series. The more unique and scarce an NFT is, the more valuable and rare it becomes. Developers can leverage NFT rarity for various use cases, including investment tools, authentication features, games with rare items, and NFT rarity calculators. To obtain NFT rarity data, developers can use the GoldRush API endpoints to get traits for a collection, attributes for a collection trait, and trait summary for a collection. By understanding the trait types and the types of attributes for each trait, developers can calculate the rarity of an NFT based on the number of occurrences of each attribute.

Check out our other NFT endpoints to get NFT metadata, balances, transactions, check ownership and more!