GET
/
holders
/
evm
/
{contract}
curl --request GET \
  --url https://token-api.thegraph.com/holders/evm/{contract} \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "block_num": 21764208,
      "timestamp": 1738564283,
      "date": "2025-02-03",
      "address": "0x5a52e96bacdabb82fd05763e25335261b270efcb",
      "amount": "339640316263000000000000000",
      "decimals": 18,
      "symbol": "GRT",
      "network_id": "mainnet",
      "price_usd": 0.1040243665135064,
      "value_usd": 35330868.74170554
    }
  ]
}

​
Endpoint Overview

Method: GET

Path: /holders/evm/

Description: Retrieves token holder data for a given token contract address.

​
Request Parameters

ParameterTypeDescriptionNotes
contract(string, required)The contract address to query for token holders.Must be a valid hexadecimal address. Example: 0x1234abcd…
network_id(string, optional)Specifies the blockchain network to query.Use this parameter when you need data from a specific EVM-compatible network.
limit(number, optional)The maximum number of records to return.Useful for controlling response size and paginating results.
offset(number, optional)The number of records to skip before returning results.Use together with limit for pagination.
order-by(string, optional)The order in which results are displayedUse to order results. Options include asc and desc.

​
Response Parameters

ParameterTypeDescriptionNotes
block_num(number)The block number of the most recent balance change for the data queried.Block numbers will differ between blockchains.
timestamp(number)The Unix timestamp of the most recent balance change for the data queried.Equals the number of seconds elapsed since January 1, 1970, 00:00:00 UTC.
date(string)The date of the block from which data was queried.In the format “YYYY-MM-DD”.
address(string)The address of this token holder record.Returned in hexadecimal. Example: 0x1234abcd…
amount(string)The amount of tokens held by the address.Returned as an integer, in the smallest divisible units of the token.
decimals(number)The number of decimal places of precision for the specified token.Use together with amount to determine token amount.
symbol(string)The number of records to skip before returning results.Use together with limit for pagination.
network_id(string)The number of records to skip before returning results.Use together with limit for pagination.

​
Additional Notes:

Additional Notes: The field amount returns an integer number. This is the number of smallest divisible units of the token that is held by the address. Use the decimals field to determine how many of those digits are to the right of the decimal point.

For example, the token for Ethereum has 18 decimal places, and the smallest unit of Ether is one Wei, or one quintillionth of one Ether. The amount field will return the number of Wei, not the number of Ether. To determine the number of Ether, you would use decimals to determine how far from the last digit the decimal is placed, in this case 18 digits.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
contract
string
required

EVM contract address to query

Example:

"0xc944e90c64b2c07662a292be6244bdf05cda44a7"

Query Parameters

​
network_id
enum<string>
default:mainnet

The Graph Network ID https://thegraph.com/networks

Available options:
mainnet,
arbitrum-one,
base,
bsc,
matic,
optimism
Example:

"mainnet"

​
order_by
enum<string>
default:desc

The order in which to return the results: Ascending (asc) or Descending (desc).

Available options:
asc,
desc
​
limit
integer
default:10

The maximum number of items returned in a single request.

Required range: 1 <= x <= 500
​
page
integer
default:1

The page number of the results to return.

Required range: x >= 1

Response

200 - application/json
Successful Response
​
data
object[]
required
​
statistics
object