# HowRare.is — Complete Documentation for AI Agents > Solana NFT rarity rankings, trait analysis, and market analytics. > Covers 1,800+ collections with multiple ranking algorithms. For a concise overview, see [llms.txt](https://howrare.is/llms.txt). For a machine-readable API spec, see [openapi.json](https://howrare.is/openapi.json). --- ## Site Overview HowRare.is ranks Solana NFTs by rarity. Each NFT in a collection gets a rarity rank based on its traits — rarer trait combinations produce lower (better) rank numbers. Rank 1 = rarest. The site provides: - Rarity rankings for 1,800+ Solana NFT collections - Multiple ranking algorithms per collection - Trait breakdowns with per-trait rarity percentages - Marketplace listings and sale history - Owner data and wallet viewing - Drops calendar for upcoming NFT launches ## URL Patterns | Pattern | Example | Description | |---------|---------|-------------| | `/{slug}` | `/claynosaurz` | Collection rarity rankings page | | `/{slug}/{item_id}/` | `/smb/1355/` | Individual NFT detail page | | `/{slug}/owners` | `/smb/owners` | Owner distribution | | `/{slug}/sales` | `/smb/sales` | Sale history | | `/{mint_address}` | `/{base58_address}` | Redirects to correct collection/item page if mint is tracked | | `/drops` | `/drops` | Upcoming NFT launches | | `/faq` | `/faq` | Ranking methodology and FAQ | | `/api` | `/api` | API documentation | **Important:** `/explorer/` and `/view_wallet/` Do not access these paths. These are for humans to use. Automated use might block your access to the site. --- ## API Reference **Base URL:** `https://api.howrare.is/` **Authentication:** Some endpoints require an API key sent via the `X-HOWRARE-API-KEY` header. To obtain a key, contact [@SadMouseTweets](https://x.com/SadMouseTweets) on X with your project info and expected usage. **Response format:** All responses follow this structure: ```json { "api_version": "0.1", "result": { "api_code": 200, "api_response": "Success", "data": { ... } } } ``` Error responses omit the `data` field and set `api_code` to the HTTP status code (401, 404, 429, 500). **Caching:** Responses are cached server-side. Collection data is cached for ~30 minutes. Drops data is cached for ~5 minutes. --- ### GET /v0.1/drops Returns upcoming Solana NFT launches grouped by date. No API key required. **Example request:** ``` GET https://api.howrare.is/v0.1/drops ``` **Example response:** ```json { "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": "" } ] } } } ``` --- ### GET /v0.1/find_collection_from_mint/{mint_hash} Look up which collection a Solana NFT mint belongs to. No API key required. **Parameters:** - `mint_hash` (path, required): Solana mint address **Example request:** ``` GET https://api.howrare.is/v0.1/find_collection_from_mint/9ARngHhVaCtH5JFieRdSS5Y8cdZk2TMF4tfGSWFB9iSK ``` **Success response (200):** ```json { "api_version": "0.1", "result": { "api_code": 200, "api_response": "Success", "data": { "name": "SolanaMonkeyBusiness (SMB)", "url": "/smb" } } } ``` **Not found response (404):** ```json { "api_version": "0.1", "result": { "api_code": 404, "api_response": "Mint not found" } } ``` --- ### GET /v0.1/collections List all ranked collections with metadata. No API key required. **Example request:** ``` GET https://api.howrare.is/v0.1/collections ``` **Example response (truncated):** ```json { "api_version": "0.1", "result": { "api_code": 200, "api_response": "Success", "data": [ { "name": "SolanaMonkeyBusiness (SMB)", "url": "/smb", "logo": "https://media.howrare.is/logo/97cea13f2c66791644ad2cde29c03a6d.jpg", "official_rarity": 0, "metadata_refresh_ts": 1655641809, "me_key": "solana_monkey_business", "holders": 2863, "items": 5000 } ] } } ``` **Fields:** - `name`: Full collection name - `url`: URL path on howrare.is (e.g., "/smb") - `logo`: Full URL to collection logo - `official_rarity`: 1 = officially endorsed ranking, 0 = community ranked - `metadata_refresh_ts`: Unix timestamp of last metadata refresh - `me_key`: Magic Eden collection key (if available) - `holders`: Number of unique holders - `items`: Total items in collection --- ### GET /v0.1/collections/{slug} Full rarity data for a collection including all items with traits. No API key required. Paginated. **Parameters:** - `slug` (path, required): Collection URL slug (e.g., "smb", "claynosaurz") - `page` (query, optional): Page number. Default: 1. Range: 1-5000. - `limit` (query, optional): Items per page. Default: 30000. Range: 100-30000. **Example request:** ``` GET https://api.howrare.is/v0.1/collections/smb?page=1&limit=2000 ``` **Example response (items truncated to 1):** ```json { "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": "https://discord.gg/solanamonkey", "website": "https://solanamonkey.business", "description": "5000 Solana inspired generative NFTs", "logo": "https://media.howrare.is/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.", "image": "https://arweave.net/wGChHSDTXTP9oAtTaYh9s8j1MRE0IPmYtH5greqWwZ4", "attributes": [ { "name": "Attribute count", "value": "2", "rarity": "45.96" }, { "name": "Type", "value": "Skeleton", "rarity": "2.42" }, { "name": "Hat", "value": "Crown", "rarity": "0.02" } ], "rank": 1, "rank_algo": "howrare.is", "all_ranks": { "howrare.is": 1, "trait_normalized": 1 } } ] }, "paging": { "limit": 2000, "page": 1, "total_pages": 3 } } } ``` **Item fields:** - `id`: Item ID within collection (used in URL: `/{slug}/{id}/`) - `mint`: Solana mint address - `link`: Full URL to item page on howrare.is - `name`: NFT name - `description`: NFT description - `image`: URL to NFT image (may be Arweave, IPFS, or CDN) - `attributes`: Array of traits, each with `name` (category), `value`, and `rarity` (percentage as string, e.g., "2.42" means 2.42%) - `rank`: Rarity rank under the default algorithm (1 = rarest) - `rank_algo`: Which algorithm was used for the primary rank - `all_ranks`: Object mapping algorithm name to rank number for all available algorithms **Notes on ranking algorithms:** - If the web UI defaults to HowRare.is ranking, `rank_algo` will be `"howrare.is"` - If ranking is set to match a project's in-house ranking, `rank_algo` will be `"teams_vision"` - Check `all_ranks` for all available algorithms for that collection --- ### GET /v0.1/collections/{slug}/only_rarity Lightweight version — returns only rank data without attributes, names, descriptions, or images. Same pagination as above. No API key required. **Example response item:** ```json { "id": "1355", "mint": "9ARngHhVaCtH5JFieRdSS5Y8cdZk2TMF4tfGSWFB9iSK", "link": "https://howrare.is/smb/1355/", "rank": 1, "rank_algo": "howrare.is", "all_ranks": { "howrare.is": 1, "trait_normalized": 1 } } ``` --- ### GET /v0.1/rarity/{mint_hash} Get rarity data for a specific NFT by its mint address. **Requires API key.** **Parameters:** - `mint_hash` (path, required): Solana mint address **Headers:** - `X-HOWRARE-API-KEY`: Your API key **Example request:** ``` GET https://api.howrare.is/v0.1/rarity/4ogxDto5Pt8z2EsaQPjjVmsXL9L83hHWRR33Z3L5Ayd7 X-HOWRARE-API-KEY: your_key_here ``` **Example response:** ```json { "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 } } } } ``` **Fields:** - `rank_shared_with`: Number of other items sharing this exact rank (0 = unique rank) --- ### GET /v0.1/collections/{slug}/owners Owner data for a collection. **Requires API key with 'owners' permission.** Returns a mapping of mint address to owner wallet address. Owner data is refreshed approximately once every 24 hours. If an item is listed on a marketplace, the owner will be the marketplace's escrow wallet. **Headers:** - `X-HOWRARE-API-KEY`: Your API key **Example response (truncated):** ```json { "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": "https://discord.gg/solanamonkey", "website": "https://solanamonkey.business", "description": "5000 Solana inspired generative NFTs", "logo": "https://media.howrare.is/logo/smb.jpg", "owners": { "2Ly6auiJtRVbAGv7Dmrco51c9Jyn8UYZoyYtkAjJ7ZAh": "4VUE76iyXsUh5NRfpqfWhKG3Rhm8vCyBQhQrjXPjUmXL", "2jsS8xuaMUs57csFKEr5z8SEyt2cFsxRu6dqTxTGGzag": "B1kVMqtMSjzjgqU2QSK8TJLtVF9gV9e7gGnayXHoNGAx" } }, "paging": { "limit": 30000, "page": 1, "total_pages": 1 } } } ``` The `owners` object maps mint address (key) to owner wallet address (value). --- ### GET /v0.1/collections/{slug}/mints Get all mint addresses (hashlist) for a collection. No API key required. Paginated. **Example response (truncated):** ```json { "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": "https://discord.gg/solanamonkey", "website": "https://solanamonkey.business", "description": "5000 Solana inspired generative NFTs", "logo": "https://media.howrare.is/logo/smb.jpg", "mints": [ "128hYy4xQnPE1jnxEb5hBZCVEEygHRX224oNYYUUgEw9", "12N4b7GyUgZRiUMoSDiwpVWzAtH4TzTV7bRpp8RHpVHM" ] }, "paging": { "limit": 30000, "page": 1, "total_pages": 1 } } } ``` --- ## Pagination Endpoints that return lists support pagination with two query parameters: - `page`: Page number (default: 1, range: 1-5000) - `limit`: Items per page (default: 30000, range: 100-30000) The response includes a `paging` object with `limit`, `page`, and `total_pages`. Example: `GET https://api.howrare.is/v0.1/collections/smb?page=2&limit=2000` --- ## Ranking Algorithms HowRare.is supports multiple rarity ranking algorithms. Not all collections have all algorithms enabled. | Algorithm Key | API Value | Description | |--------------|-----------|-------------| | `hr` | `howrare.is` | Default HowRare.is ranking. May include team-defined trait weights. | | `trait_n` | `trait_normalized` | Trait Normalized rarity. Normalizes trait counts across categories to prevent categories with more values from dominating. | | `stat_rarity` | `statistical_rarity` | Statistical Rarity. Multiplies the individual probabilities of each trait to produce an overall rarity score. | | `teams_vision` | `teams_vision` | Team Vision. The NFT project's own official ranking, when provided. | - Each item's `rank` field uses the collection's default algorithm - The `rank_algo` field tells you which algorithm was used - The `all_ranks` object contains the rank under every available algorithm - Rank 1 = rarest. Lower rank = more rare. - Multiple items can share the same rank --- ## Data Model ### NFT Item - `id`: Sequential item ID within the collection (used in URLs) - `mint`: Solana mint address (base58 string) - `name`: NFT display name - `description`: NFT description text - `image`: URL to the NFT image (Arweave, IPFS, or CDN) - `rank`: Rarity rank under the default ranking algorithm - `rank_algo`: Which algorithm produced the primary rank - `all_ranks`: Object mapping each available algorithm name to its rank number - `attributes`: Array of trait objects, each containing: - `name`: Trait category (e.g., "Type", "Hat", "Eyes", "Attribute count") - `value`: Trait value (e.g., "Skeleton", "Crown", "None") - `rarity`: Percentage of collection with this trait, as a string (e.g., "2.42" = 2.42%). Empty string if not available. ### Collection - `name`: Full display name - `url`: URL path on howrare.is (e.g., "/smb") - `logo`: Full URL to logo image - `description`: Collection description - `official_rarity`: 1 if the ranking is officially endorsed by the project, 0 if community-ranked - `twitter`, `discord`, `website`: Social links (may be empty strings) ### Special Values - Traits with value `"None"` (or collection-specific equivalent) indicate the NFT does not have that trait - `"Attribute count"` is a special trait that counts how many traits an NFT has - Burned NFTs have status "burned" and may be hidden from listings --- ## Common Agent Workflows ### Find rarity by NFT name Collection names don't map directly to URL slugs (e.g., "Solana Monkey Business" uses slug "smb"). Users may refer to collections by different names. To find the right collection: 1. Call `GET https://api.howrare.is/v0.1/collections` to get all collections with their names and URL slugs 2. Search the results for a matching name 3. Use the `url` field as the slug to construct the NFT page URL: `https://howrare.is/{url}/{item_id}/` ### Find rarity by mint address 1. Visit `https://howrare.is/{mint_address}` — the site will redirect to the correct NFT page 2. Or call `GET https://api.howrare.is/v0.1/find_collection_from_mint/{mint_address}` to get the collection, then look up the specific item ### Browse rarest items in a collection 1. Call `GET https://api.howrare.is/v0.1/collections/{slug}?page=1&limit=100` 2. Items are returned sorted by rank ascending (rarest first) ### List all collections 1. Call `GET https://api.howrare.is/v0.1/collections` 2. Use the `url` field to construct collection page URLs --- ## Error Responses All errors follow the same format: ```json { "api_version": "0.1", "result": { "api_code": 404, "api_response": "Collection not found" } } ``` Common error codes: - `401` Unauthorized — missing or invalid API key - `404` Not found — collection or mint not found - `429` Too many requests — rate limit exceeded - `500` Server error --- ## Links - Website: https://howrare.is - API docs: https://howrare.is/api - OpenAPI spec: https://howrare.is/openapi.json - X/Twitter: https://x.com/SadMouseTweets