Home API

HowRare.is public API

In creating our first public APIs we followed YAGNI principle ("You aren't gonna need it" is a principle which arose from extreme programming that states a programmer should not add functionality until deemed necessary). APIs are very simple but at the same time data rich. If your use case requires some extra functionality let us know, and we will look into supporting it.

Disclaimer: All APIs should be considered experimental. There can be bugs! Use on your own risk! APIs should be considered alpha quality and going forward there will be breaking changes. Do not use as an oracle in DeFi applications!

Please be nice and don't abuse APIs. In case APIs will get abused we will need to put them under authorization and no one wants to deal with extra keys, right? :)

We have very useful Drops page on which you can see many of the upcoming Solana NFT drops. If you want to retrieve this information through an API make a GET call:

GET https://api.howrare.is/v0.1/drops

Shortened sample of successful retrieval

{
  "api_version": "0.1",
  "result": {
    "api_code": 200,
    "api_response": "Success",
    "data": {
      "2022-11-11": [
        {
          "date": "2022-11-11",
          "time": "00:01 UTC",
          "twitter": "",
          "extra": "Some Extra info if there is some",
          "discord": "",
          "website": "",
          "nft_count": 222,
          "price": "0 SOL",
          "name": "Some title",
          "left": "7 hours 59 minutes",
          "image": ""
        }
      ]
    }
  }
}

Use this API to look up mapping between mint and Collections on HowRare.is.

GET https://api.howrare.is/v0.1/find_collection_from_mint/{mint_hash}

In case we have a collection for this mint you will get a response like this:

{
    "api_version":"0.1",
    "result": {
        "api_code":200,
        "api_response":"Success",
        "data": {
            "name":"SolanaMonkeyBusiness (SMB)",
            "url":"\/smb"
        }
    }
}

However in case we will not have mapping you will receive response like this:

{
    "api_version": "0.1",
    "result": {
        "api_code": 404,
        "api_response": "Mint not found"
    }
}

To retrieve list of all collections for which we have Rarity ranking you need to make a following GET call:

GET https://api.howrare.is/v0.1/collections

Shortened sample of successful retrieval

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": [
			{
				"name": "SolanaMonkeyBusiness (SMB)",
				"url": "/smb",
				"logo": "/icons/97cea13f2c66791644ad2cde29c03a6d.jpg",
				"official_rarity": 0,
				"metadata_refresh_ts": 1655641809,
				"me_key": "solana_monkey_business",
				"on_sale": 364,
				"holders": 2863,
				"items": 5000,
				"floor": 185.00,
				"floor_marketcap": 207135250,
				"floor_marketcap_pretty": "207.14M"
			},
			{
				"name": "SolStein",
				"url": "/solstein",
				"logo": "/icons/d4e2b4869413ee9ca60440077e6b8dbe.jpg",
				"official_rarity": 1,
				"metadata_refresh_ts": 1657634055,
				"me_key": "solstein",
				"on_sale": 47,
				"holders": 1950,
				"items": 2217,
				"floor": 8.90,
				"floor_marketcap": 4418430.009,
				"floor_marketcap_pretty": "4.42M"
			}
        ]
    }
}

This API endpoint is available only to those who have applied and received API key. API key is granted for free. It's required so that it would be possible to know who to contact in case of excessive use. To receive API key contact us on Twitter or Discord. You will need to inform us about the project that you are representing, contact information (email or Twitter/Discord/TG) and approximate requests per second/day.

Key should be supplied in headers with key X-HOWRARE-API-KEY

To retrieve rarity you need to make a GET call to:

https://api.howrare.is/v0.1/rarity/{mint_hash}

If mint will not be located you will get 404 error code and "Mint not found" error:

{
    "api_version":"0.1",
    "result": {
        "api_code":404,
        "api_response":"Mint not found"
    }
}

However in case of properly formatted request you will get Rarity data:

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": {
            "collection": "SolanaMonkeyBusiness (SMB)",
            "mint": "4ogxDto5Pt8z2EsaQPjjVmsXL9L83hHWRR33Z3L5Ayd7",
            "mint_name": "SMB #127",
            "mint_url": "https://howrare.is/smb/127",
            "rank": 756,
            "rank_algo": "howrare.is",
            "rank_shared_with": 0,
            "all_ranks": {
                "howrare.is": 756,
                "trait_normalized": 2830
            }
        }
    }
}

Once you have retrieved list of collections you can look up rank for a specific collection. To do that use "url" parameter from Collections API response to construct Rarity API url. Rarity URL is in the form of:

https://api.howrare.is/v0.1/collections/{collection}

To retrieve Rarity data for SolanaMonkeyBusiness:

GET https://api.howrare.is/v0.1/collections/smb

If collection will not be located you will get 404 error code and "Collection not found" error:

{
    "api_version":"0.1",
    "result": {
        "api_code":404,
        "api_response":"Collection not found"
    }
}

However in case of properly formatted request you will get Rarity data (items trimmed to 1 item to save space here):

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": {
            "collection": "SolanaMonkeyBusiness (SMB)",
            "ranking_url": "https://howrare.is/smb",
            "official_rarity": 0,
            "twitter": "https://twitter.com/SolanaMBS",
            "discord": "http://discord.gg/solanamonkey",
            "website": "http://solanamonkey.business",
            "description": "5000 Solana inspired generative NFTs",
            "logo": "https://media.howrare.is/images/project_logo/smb.jpg",
            "items": [
                {
                    "id": "1355",
                    "mint": "9ARngHhVaCtH5JFieRdSS5Y8cdZk2TMF4tfGSWFB9iSK",
                    "link": "https://howrare.is/smb/1355/",
                    "name": "SMB #1355",
                    "description": "SMB is a collection of 5000 randomly generated 24x24 pixels NFTs on the Solana Blockchain. Each SolanaMonkey is unique and comes with different type and attributes varying in rarity.",
                    "image": "https://arweave.net/wGChHSDTXTP9oAtTaYh9s8j1MRE0IPmYtH5greqWwZ4",
                    "attributes": [
                        {
                            "name": "Attribute count",
                            "value": "2",
                            "rarity": "45.96"
                        },
                        {
                            "name": "Type",
                            "value": "Skeleton",
                            "rarity": "2.42"
                        },
                        {
                            "name": "Clothes",
                            "value": "Orange Jacket",
                            "rarity": "1.04"
                        },
                        {
                            "name": "Ears",
                            "value": "None",
                            "rarity": "78.08"
                        },
                        {
                            "name": "Mouth",
                            "value": "None",
                            "rarity": "73.64"
                        },
                        {
                            "name": "Eyes",
                            "value": "None",
                            "rarity": "71.52"
                        },
                        {
                            "name": "Hat",
                            "value": "Crown",
                            "rarity": "0.02"
                        }
                    ],
                    "rank": 1,
                    "rank_algo": "howrare.is",
                    "all_ranks": {
                        "howrare.is": 1,
                        "trait_normalized": 1
                    }
                }
            ]
        }
    }
}

At HowRare.is we support multiple ranking algorithms. Not all collections have all algorithms enabled. API tries to mimic Web UI. If in the Web UI by default we use HowRare.is ranking (with or without weights) you will see "rank_algo":"howrare.is". However if ranking is set to match in-house ranking of the NFT project then you will see "rank_algo":"teams_vision". To view all the available rankings for the item look into all_ranks attribute. Possible values for algorithms are: howrare.is, teams_vision, trait_normalized, statistical_rarity.

If you are interested only in Rarity you can a call to retrieve just rarity data. Append /only_rarity to the regular call. Example to retrieve only Rarify for SMB collection:

GET https://api.howrare.is/v0.1/collections/smb/only_rarity

Response format is the same like in a regular call, but with extra fields trimmed off. Response example:

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": {
            "collection": "SolanaMonkeyBusiness (SMB)",
            "official_rarity": 0,
            "ranking_url": "https://howrare.is/smb",
            "items": [
                {
                    "id": "1355",
                    "mint": "9ARngHhVaCtH5JFieRdSS5Y8cdZk2TMF4tfGSWFB9iSK",
                    "link": "https://howrare.is/smb/1355/",
                    "rank": 1,
                    "rank_algo": "howrare.is",
                    "all_ranks": {
                        "howrare.is": 1,
                        "trait_normalized": 1
                    }
                }
            ]
        }
    }
}

If you want to retrieve the information about owners of the NFTs in any of the listed collections you can use Owners API. Keep in mind that there are couple caveats:

Owners data is refreshed only about once every 24h. This delay will be reduced later on.
If an item is listed on most marketplaces, it's owner will be set to be equal to the escrow wallet of the marketplace.

To get the owners data use the URL in the following form:

https://api.howrare.is/v0.1/collections/{collection}/owners

To retrieve owners data for SolanaMonkeyBusiness:

GET https://api.howrare.is/v0.1/collections/smb/owners

If collection will not be located you will get 404 error code and "Collection not found" error:

{
    "api_version":"0.1",
    "result": {
        "api_code":404,
        "api_response":"Collection not found"
    }
}

However in case of properly formatted request you will get Owners data (in this elements trimmed to 2 item to save space here):

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": {
            "collection": "SolanaMonkeyBusiness (SMB)",
            "ranking_url": "https://howrare.is/smb",
            "twitter": "https://twitter.com/SolanaMBS",
            "discord": "http://discord.gg/solanamonkey",
            "website": "http://solanamonkey.business",
            "description": "5000 Solana inspired generative NFTs",
            "logo": "https://media.howrare.is/images/project_logo/smb.jpg",
            "owners": {
                "2Ly6auiJtRVbAGv7Dmrco51c9Jyn8UYZoyYtkAjJ7ZAh": "4VUE76iyXsUh5NRfpqfWhKG3Rhm8vCyBQhQrjXPjUmXL",
                "2jsS8xuaMUs57csFKEr5z8SEyt2cFsxRu6dqTxTGGzag": "B1kVMqtMSjzjgqU2QSK8TJLtVF9gV9e7gGnayXHoNGAx"
            }
        }
    }
}

Key in the "owners" is equal to mint ID (hash). Value is equal to owner.

If you want to retrieve Mints (hashlist) you can use Mints API.

To get mints use the URL in the following form:

https://api.howrare.is/v0.1/collections/{collection}/mints

To retrieve mints data for Solana Monkey Business:

GET https://api.howrare.is/v0.1/collections/smb/mints

If collection will not be located you will get 404 error code and "Collection not found" error:

{
    "api_version":"0.1",
    "result": {
        "api_code":404,
        "api_response":"Collection not found"
    }
}

However in case of properly formatted request you will get Mints (in this example elements trimmed to 2 item to save space here):

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": {
            "collection": "SolanaMonkeyBusiness (SMB)",
            "ranking_url": "https://howrare.is/smb",
            "twitter": "https://twitter.com/SolanaMBS",
            "discord": "http://discord.gg/solanamonkey",
            "website": "http://solanamonkey.business",
            "description": "5000 Solana inspired generative NFTs",
            "logo": "https://media.howrare.is/images/project_logo/smb.jpg",
            "mints": [
                "128hYy4xQnPE1jnxEb5hBZCVEEygHRX224oNYYUUgEw9",
                "12N4b7GyUgZRiUMoSDiwpVWzAtH4TzTV7bRpp8RHpVHM"
            ]
        }
    }
}

Reminding this one more time: As we can't guarantee that this data is up to date and always accurate, do not use this API as an oracle for DeFi applications!

To retrieve Floor pricing for all NFT collections listed on HowRare.is use a GET request:

GET https://api.howrare.is/v0.1/floor

Result of successful data query:

{
    "api_version": "0.1",
    "result": {
        "api_code": 200,
        "api_response": "Success",
        "data": [
            {
                "name": "Degen Ape Academy",
                "url": "/degenapes",
                "floor_sol": "24.99",
                "floor_usd": "5596.01"
            },
            {
                "name": "SolanaMonkeyBusiness (SMB)",
                "url": "/smb",
                "floor_sol": "138.00",
                "floor_usd": "30902.34"
            }
        ]
    }
}

Data in the result trimmed to 2 items.