Honeycluster Docs – List holders for a collection

nftokens

List holders for a collection

get

/nft/collection/{slug}/holders

operationId: nft-collectionHolders

Returns the holder list for an NFT collection, grouped by current owner. Each row is { owner, nftCount, firstAcquiredAt } where firstAcquiredAt is the earliest acquisition time among the holder's NFTs in the collection. Ordered by descending nftCount with owner ascending as a stable tiebreaker. Cursor-paginated via an opaque base64 {nftCount, owner} token. Returns an empty items array when the slug does not resolve to an indexed collection.

Authorizations

Name	Location	Details
`BearerAuth`	Authorization header · bearer	JWT issued by the Honeycluster auth service for the `indexer` audience. Present as `Authorization: Bearer <token>`.

Path Parameters

Name	Type	Default	Description
`slug` required	string		Collection slug in `issuer:taxon` form. Example: `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B:42`.

Query Parameters

Name	Type	Default	Description
`cursor`	string
`limit`	integer	`50`

Responses

200

application/json

Successful response

Field	Type	Description
`items`	object[]	Holders ordered by descending `nftCount`, with `owner` ascending as a stable tiebreaker. Empty when the slug does not resolve to an indexed collection or the collection has no indexed NFTs.
`items[].owner`	string	XRPL account address that holds at least one NFT in the collection.
`items[].nftCount`	integer	Number of NFTs in the collection currently attributed to this owner.
`items[].firstAcquiredAt`	integer	Unix-seconds timestamp of the earliest acquisition time among the holder's NFTs in the collection.
`nextCursor`	object	Cursor for the next page, or null when this is the last page.

Example

Json

{
  "items": [
    {
      "owner": "string",
      "nftCount": 0,
      "firstAcquiredAt": 1745798400
    }
  ],
  "nextCursor": "string"
}

400

application/json

Invalid input data

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

401

application/json

Authorization not provided

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

403

application/json

Insufficient access

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

404

application/json

Not found

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "NOT_FOUND",
  "message": "Not found",
  "issues": []
}

500

application/json

Internal server error

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}