Jinxto94 / rarity-analyser

An open source NFT rarity analyser

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Rarity analyser

Creates rarity data for an NFT collection and provides a GraphQL API for making queries.

Creates both classic and normalized rarity scores.

User interface at rarity-interface.

Getting started

Create a MongoDB instance

  1. Create a free MongoDB Atlas instance or use a local MongoDB.

  2. Add the connection string for MongoDB into a .env file:

# .env

Analyse metadata

Analyse collection metadata with yarn analyse --json <path_to_metadata_json_file>.

Start the GraphQL server

Start the server with yarn dev



heroku create
heroku config:set MONGODB=mongodb+srv://<user>:<password>@db.b5lu1.mongodb.net/db
git push heroku main


Following options can be applied in the rarityConfig.ts file.


Add weights to scale rarity scores up or down.

# rarityConfig.ts
  weights: {
    "Trait A": 1.2,
    "Trait B": 0.1,


Array of trait types to be ignored by the rarity analyser.

  ingoreTraits: [
    'Trait x',
    'Trait y',


(trait_type?: string) => string | undefined

By default it is assumed that the missing traits are completely missing from the attribute list. Some collections however use other values for missing traits, for example "No Hat" for the trait type "Hat".


# rarityConfig.ts
  getMissingTraitIdentifier: (traittype?: string) => "No " + traitType


The default name is attributes, define a custom name here.



yarn analyse --json <collection.json> --saveJson --db <true> Analyses rarity data form existing metadata

Cli options:


Default: src/data/collection.json Path to the token attribute file


Default: false Saves rarity data into a json file


Default: true Skips saving to database if false


interface Token {
  id: number
  name: string
  attributes: Attribute[] // Attribute field name can be configured in rarityConfig.ts
  image?: string
  description?: string
  image_data?: string
  external_url?: string
  animation_url?: string
  background_color?: string

  // The following fields are included in the analysed data
  rarity_score: number
  rank: number
  rarity_score_normalized: number
  rank_normalized: number
interface Attribute {
  trait_type: number
  value: string

  // The following fields are included in the analysed data
  rarity_score: number
  rarity_score_normalized: number
  percentile: number
  count: number // Count of how many tokens have the value of this attribute
ezoic increase your site revenue


An open source NFT rarity analyser

License:MIT License


Language:TypeScript 98.9%Language:JavaScript 0.9%Language:Shell 0.2%