Skip to content
rare
⌘K
Marketplace API

Marketplace data

Holders

List who holds a collection, with header figures, kiosk, wallet and staked counts, and items staked or locked in protocols.

GET /collections/{slug}/holders returns the holders of a collection, largest first, with a header of collection-wide figures. Holder data is read from chain state, including items that sit inside kiosks and inside staking or locking protocols.

GET/collections/{slug}/holders

Query parameters

ParameterValuesNotes
sortcount (default), pct, address, listedpct sorts the same as count. Anything else is 400 bad_request.
dirasc or descDefaults to desc, except sort=address, which defaults to asc.
limit1 to 200Default 50.
cursorthe previous page's nextCursorOpaque.
typea full Move typeAccepted in place of the slug.

Request

curl "https://rare.market/api/v1/collections/popkins/holders?limit=2"
Response
{
  "data": [
    {
      "rank": 1,
      "address": "0x1c8d86c652698628a08650bd7455f5072e925697ce4da9ae0f0ae4e924118e3d",
      "name": null,
      "count": 901,
      "pctOfSupply": 3.6,
      "inKiosk": 9,
      "inWallet": 0,
      "staked": 892,
      "listed": 0
    },
    {
      "rank": 2,
      "address": "0x16386f6d07a85631e419e8f83b1d99a13949515a6af7ba3f81f3cfb0ec7e5543",
      "name": null,
      "count": 719,
      "pctOfSupply": 2.88,
      "inKiosk": 1,
      "inWallet": 718,
      "staked": 0,
      "listed": 0
    }
  ],
  "nextCursor": "eyJuIjo3MTksImgiOiIweDE2Mzg2ZjZkMDdhODU2MzFlNDE5ZThmODNiMWQ5OWExMzk0OTUxNWE2YWY3YmEzZjgxZjNjZmIwZWM3ZTU1NDMifQ",
  "total": 3643,
  "header": {
    "owners": 3643,
    "uniqueOwnersPct": 14.61,
    "uniquePct": 14.61,
    "top10Pct": 17.88,
    "top100Pct": 53.16,
    "itemsHeld": 24927,
    "supply": 25000,
    "stakedOrLocked": [
      {
        "protocol": "0x38f0bad7a60a8c4399a810430b7625b60c93983321b3cd8723f201cc559de5c1::staking_contract",
        "name": "staking_contract",
        "count": 18806,
        "attributed": 18806
      }
    ],
    "asOf": "2026-10-27T01:59:25.044Z"
  }
}

Holder rows

FieldTypeNotes
ranknumberRank by count (largest first, ties by address). It stays the count rank when you sort by something else.
addressstringThe holder's address.
namestring or nullSuiNS name when one resolves quickly, else null.
countnumberItems of the collection this holder holds.
pctOfSupplynumbercount as a percent of supply (of itemsHeld when supply is unknown). Two decimals.
inKiosknumberItems in the holder's kiosks, personal kiosks included.
inWalletnumberItems owned directly by the address.
stakednumberItems a protocol holds on the holder's behalf.
listednumberThe holder's live listings in this collection, from the current listing set.

inKiosk + inWallet + staked can be lower than count. The rest are items held another way, for example in an escrow listing or nested inside another object the holder owns.

Header figures

FieldNotes
ownersDistinct holders, stakers included. Same as total.
uniqueOwnersPctowners over itemsHeld, in percent. uniquePct is the same number under an older name.
top10Pct, top100PctShare of itemsHeld held by the 10 and 100 largest holders.
itemsHeldItems with a known holder.
supplyThe collection's supply.
stakedOrLockedItems held by protocols, see below.
asOfWhen the holder data behind this list was last read from chain (ISO 8601), or null.

The same owners, uniqueOwnerPct and stakedOrLocked figures appear in stats on GET /collections/{slug}.

Staked or locked items

Many collections let holders stake or lock items in a protocol. On chain, those items belong to the protocol's shared object, not to the user. rare.market follows the ownership chain to find the real holder:

  • An item owned by another address-owned object is held by that object's owner.
  • An item in a kiosk is held by whoever holds the kiosk's owner cap.
  • An item in a protocol's shared object is held by the user the protocol records for it. Those items count in staked and the user counts in owners.

header.stakedOrLocked lists each protocol that holds items of the collection, largest first:

FieldTypeNotes
protocolstring or null<package>::<module> of the shared object holding the items. null means an ownership chain whose contract is not identified yet.
namestring or nullThe module name, for display.
countnumberItems held by that protocol.
attributednumberOf count, the items traced back to a user. Those users count in owners; the rest have no known holder.

When attributed equals count, every staked item is credited to a holder. When it is lower, the difference is missing from itemsHeld.

TypeScript
const { header } = await (
  await fetch("https://rare.market/api/v1/collections/popkins/holders?limit=1")
).json();
for (const p of header.stakedOrLocked ?? []) {
  const label = p.name ?? "Unidentified contract";
  console.log(`${label}: ${p.count} items, ${p.attributed} credited to holders`);
}

Freshness and asOf

Holder data comes from a background reader that tracks ownership on chain, separate from the trading feeds. asOf tells you how current it is. The reader can be paused, so check asOf before you treat the numbers as live. Responses are also cached in the API for a few minutes, so a transfer can take a short while to show up.

Paging and sorting

The default order (sort=count, dir=desc) pages with a cursor tied to the last row. Other sorts page by offset with an opaque cursor. Either way, pass nextCursor back as cursor until it is null.

curl "https://rare.market/api/v1/collections/popkins/holders?sort=listed&dir=desc&limit=50"

Holdings of one wallet

For the other direction (what one address holds), use GET /accounts/{address}/holdings-summary and the item endpoints in Wallets and portfolio.

Collections and statsCollection detail, including the same holder figures.Wallets and portfolioHoldings, value and offers for an address.
--
TPS:--