Honeycluster Docs – List top traders for an NFT collection

nftokens

List top traders for an NFT collection

get

/nft/collection/{slug}/traders

operationId: nft-collectionTraders

Returns the top traders for an NFT collection over the requested window. Each row is { account, role, tradeCount, volumeXrpDrops } where role is buyer or seller. Use role=buyer / role=seller to restrict to one side, or role=both (default) to get both sides (an account active on both appears twice). Ordered by descending XRP volume. windowDays=0 returns lifetime stats; otherwise the window is the trailing N days from now (default 30, max 365). Volume is summed in XRP drops only — non-XRP (IOU) sales contribute to counts but not to volume.

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
`windowDays`	integer	`30`
`role`	enum<string>	`"both"`	Available `buyersellerboth`
`limit`	integer	`20`

Responses

200

application/json

Successful response

Field	Type	Description
`items`	object[]	Traders for the collection ordered by descending XRP-denominated volume. Empty when the slug does not resolve to an indexed collection or no sales occurred in the window.
`items[].account`	string	XRPL classic address of the trader on the role-tagged side of the sale.
`items[].role`	enum<string>	Which side of the sale this row represents. `buyer` = recipient; `seller` = sender. Available `buyerseller`
`items[].tradeCount`	integer	Total sales on the role-tagged side within the window.
`items[].volumeXrpDrops`	string	Sum of XRP-denominated sale amounts (drops) on the role-tagged side within the window. Non-XRP (IOU) sales contribute to `tradeCount` but not to volume.

Example

Json

{
  "items": [
    {
      "account": "string",
      "role": "buyer",
      "tradeCount": 0,
      "volumeXrpDrops": "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": []
}