Get token holders by contract address (Admin)

Request

Returns all addresses holding the specified token, enriched with PERS ownerId and ownerType where the address is a tracked wallet. Uses Blockscout for on-chain data.

Security

authJWT

Path

contractAddressstringrequired

Query

chainIdnumber

Chain ID (defaults to PERS Besu mainnet)

pagenumber

Page number (default: 1)

limitnumber

Items per page (default: 50)

includeArray of strings

Optional relations to embed. Use user to include full UserDTO for USER-owned wallets.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/balances/tokens/{contractAddress}/holders?chainId=0&page=0&limit=0&include=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Token holders retrieved successfully

Bodyapplication/json

dataArray of anyrequired

Array of data items

paginationobjectrequired

Pagination metadata

Example:

{
  "page": 1,
  "limit": 50,
  "total": 150,
  "pages": 3,
  "hasNext": true,
  "hasPrev": false
}

metadataobject or null

Additional metadata (e.g., enriched relations)

Example:

{
  "includes": [
    "sender",
    "recipient"
  ]
}

Response

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3,
    "hasNext": true,
    "hasPrev": false
  },
  "metadata": {
    "includes": [ … ]
  }
}