Traits and rarity

Traits are the attributes an NFT carries, such as Background: Aqua. The API counts every trait value in a collection, finds the cheapest listing for each value, and ranks every item by rarity. Use these figures for filter sidebars, trait floor tables and rarity badges.

Trait types

GET /collections/{slug} returns traitTypes: each trait type and how many distinct values it has. See Collections and stats.

[
  { "type": "Background", "valueCount": 11 },
  { "type": "Fur", "valueCount": 18 },
  { "type": "Rarity Tier", "valueCount": 4 }
]

Trait values, counts and floors

Returns every trait value in the collection as { data: TraitValue[] }, grouped by trait type, most common value first within each type. The list is not paged. The endpoint takes no query parameters besides ?type= (a Move type in place of the slug).

curl "https://rare.market/api/v1/collections/mystic-yetis/traits"

{
  "data": [
    {
      "type": "Rarity Tier",
      "value": "Tier 1",
      "count": 2127,
      "pct": 39.77,
      "floorMist": "29938600000",
      "floorPriceMist": "15009900000",
      "sales90d": 75,
      "median90dMist": "20000000000",
      "lastSaleMist": "14669900000",
      "lastSaleAt": "2026-10-24T15:22:22.306Z",
      "premium": 1
    },
    {
      "type": "Rarity Tier",
      "value": "Tier 4",
      "count": 346,
      "pct": 6.47,
      "floorMist": "47722000000",
      "floorPriceMist": "42990000000",
      "sales90d": 24,
      "median90dMist": "43200000000",
      "lastSaleMist": "43200000000",
      "lastSaleAt": "2026-10-25T15:48:15.691Z",
      "premium": 2.564
    }
  ]
}

The example shows two of the collection's values.

Trait facts

When value analytics are available, each row (and each attribute on GET /items/{id}) also carries:

Treat these fields as optional. See Analytics for how the value model works.

Filter items by trait

Pass trait values to the items grid as type:value pairs. Values of one type are ORed, different types are ANDed:

curl -G "https://rare.market/api/v1/collections/mystic-yetis/items" \
  --data-urlencode "traits=Background:Aqua,Background:White,Fur:Ice"

See Items for the full syntax.

Rarity

Every item card has rarity: { rank, tier }, or null when the item has no rank.

{ "rank": 2221, "tier": "uncommon" }

How the rank is chosen

1. When a marketplace publishes a full rarity ranking for the collection, its ranks are used as they are.
2. Otherwise the rank is computed from trait frequency over every item the index knows for the collection, as below.
3. A collection with fewer than two items with traits gets no ranks, and rarity is null on its items.

How the score is computed

The computed score is a sum of inverse trait frequencies:

score(item) = sum over every trait type T in the collection of  N / count(T = item's value for T)

• N is the number of items that have any traits.
• An item that lacks a trait type counts as having the value None for it, so missing a common trait is itself a trait.
• Rarer values give a bigger term, so a higher score means a rarer item.

Items are then sorted by score, highest first. The rarest item is rank 1. Items with equal scores share a rank, and the next rank skips ahead (1, 1, 3).

The score itself is not returned by the API; only rank and tier are.

Tiers

tier comes from the rank's percentile among the ranked items of the collection (rank / ranked items):

Sort by rarity

On GET /collections/{slug}/items, sort=rarity_asc puts rank 1 first and sort=rarity_desc puts the most common first. Unranked items come last in both. With status=all, listed items still come before unlisted ones; see Items.

curl "https://rare.market/api/v1/collections/mystic-yetis/items?sort=rarity_asc&limit=10"

Gotchas

• pct is not of supply. Its denominator is the items with attributes the index has read, which can be lower than supply.
• Values are exact strings. Numbers and booleans in on-chain attributes become strings. Matching is case-sensitive and keeps spacing as the creator wrote it (one collection has a trait type Mystic Yeti with two spaces).
• Two floors. floorMist is the live all-in trait floor. floorPriceMist is a bare list price from the last analytics run and can lag the live market.
• Creator traits named like rarity are ordinary traits. A trait such as Rarity Tier: Tier 1 is the creator's own label and has no link to the computed rarity.tier.
• Trait offers are not indexed yet. Trait-level offers return empty lists today. See Offers.