Holders Endpoints

Current Holders

The holders endpoint,

/v1/tokens/<chain id>/<token address>/holders

returns a list of all holders of a token. The list is sorted in descending order, and paginated.

You will find the formal API definition here.

For information about pagination see the Pagination section.

blockNumber is the block for which the holder list should be compiled. If none is supplied the latest block is used. Instead of blockNumber, timestamp can be used. See the Time section for more details.

endTimestamp/endBlock are optional. If neither is provided, the latest block is used.

The Scaling section should be consulted to understand the optional scaled parameter.

The quoteAddress parameter is the token address in which value of the holdings is expressed. The default value is 0x0000000000000000000000000000000000000348, which represents USD.

Given the following call, which requests the holders of the Aave token at block 15940669:

curl \
-H 'Authorization: Bearer <API KEY>' \
'https://gateway.credmark.com/v1/tokens/1/0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9/holders?pageSize=100&scaled=true&blockNumber=15940669'

the endpoint returns:

{
  "chainId": 1,
  "blockNumber": 15940669,
  "blockTimestamp": 1668095999,
  "tokenAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "quoteAddress": "0x0000000000000000000000000000000000000348",
  "scaled": true,
  "data": [
    {
      "address": "0x4da27a545c0c5b758a6ba100e3a049001de870f5",
      "balance": 3116988.0050337,
      "value": 216481352.93056834
    },
    {
      "address": "0xffc97d72e13e01096502cb8eb52dee56f74dad7b",
      "balance": 1730576.78113676,
      "value": 120192186.27909459
    },
    {
      "address": "0x25f2226b597e8f9514b3f68f00f494cf4f286491",
      "balance": 1435743.3258050901,
      "value": 99715384.57298596
    },
    ...
  ],
  "total": 141279,
  "cursor": "cD0xJmI9MTU5NDA2Njk"
}

Note that total is the total number of holders of the requested token and block.

Current Number of Holders

Sometimes we don't care about all the addresses that hold a token. We just want to know how many holders there are in total. Although that information is included in the result of the holders endpoint, there is no point collating and returning all that data if all we want is the count. This is why the holders/count endpoint exists.

Given the following call, which requests the number of holders of the Aave token at block 15940669:

curl \
-H 'Authorization: Bearer <API KEY>' \
'https://gateway.credmark.com/v1/tokens/1/0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9/holders/count?blockNumber=15940669'

the endpoint returns:

{
  "chainId": 1,
  "blockNumber": 15940669,
  "blockTimestamp": 1668095999,
  "tokenAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "count": 141279
}

Historical Number of Holders

The same way that we retrieved a list of holders at each block between 14966197 and 14966200, we can retrieve just the total number of holders for each of those blocks using the holders/count/historical endpoint.

Given this input:

curl -X 'GET' \
-H 'Authorization: Bearer <API KEY>' \
'https://gateway.credmark.com/v1/tokens/1/0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9/holders/count/historical?startBlockNumber=14966197&endBlockNumber=14966200&blockInterval=1' \

we get the following output:

{
  "chainId": 1,
  "startBlockNumber": 14966197,
  "endBlockNumber": 14966200,
  "startTimestamp": 1655276429,
  "endTimestamp": 1655276478,
  "tokenAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "data": [
    {
      "blockNumber": 14966197,
      "blockTimestamp": 1655276429,
      "count": 112964
    },
    {
      "blockNumber": 14966198,
      "blockTimestamp": 1655276469,
      "count": 112964
    },
    {
      "blockNumber": 14966199,
      "blockTimestamp": 1655276471,
      "count": 112964
    },
    {
      "blockNumber": 14966200,
      "blockTimestamp": 1655276478,
      "count": 112964
    }
  ]
}