Token Holders

Discover token distribution across ERC20 token holders, ranked by balance descending.

GET /v1/evm/token-holders/{chain_id}/{address}

Get Token Holders

cURL

curl --request GET \
  --url https://api.sim.dune.com/v1/evm/token-holders/{chain_id}/{address} \
  --header 'X-Sim-Api-Key: <api-key>'

200

{
  "token_address": "0x63706e401c06ac8513145b7687a14804d17f814b",
  "chain_id": 8453,
  "holders": [
    {
      "wallet_address": "0x4a79b0168296c0ef7b8f314973b82ad406a29f1b",
      "balance": "13794442047246482254818",
      "first_acquired": "2025-02-06T15:11:07+00:00",
      "has_initiated_transfer": false
    },
    {
      "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
      "balance": "25000000000000000000",
      "first_acquired": "2024-01-15T10:30:00+00:00",
      "has_initiated_transfer": true
    }
  ],
  "next_offset": "eyJwYWdlIjoyLCJsaW1pdCI6Mn0="
}

The Token Holders API returns accounts holding a specific ERC20 token, ranked by balance descending. Use it for whale tracking, governance analysis, airdrop eligibility checks, or understanding token distribution.

Example Request

curl -X GET "https://api.sim.dune.com/v1/evm/token-holders/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?limit=5" \
     -H "X-Sim-Api-Key: YOUR_API_KEY"

The response returns holders sorted by balance, with each holder’s share of total supply:

Response (JSON)

{
  "holders": [
    {
      "address": "0x37305b1cd40574e4c5ce33f8e8306be057fd7341",
      "balance": "2500000000000",
      "share": 0.025
    },
    {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "balance": "1000000000000",
      "share": 0.01
    }
  ],
  "next_offset": "eyJsYXN0X2JhbGFuY2UiOiIxMDAwMDAwMDAwMDAwIn0"
}

Field	Description
address	Holder’s wallet address
balance	Raw token balance (divide by token’s decimals for human-readable amount)
share	Proportion of total supply held (0.025 = 2.5%)

Pagination

This endpoint uses cursor-based pagination. You can use the limit query parameter to define the maximum page size (up to 500). Results might at times be less than the maximum page size. The next_offset value is included in the initial response and can be used to fetch the next page of results by passing it as the offset query parameter in the next request.

You can only use the value from next_offset to set the offset query parameter of the next page of results.

Compute Unit Cost

The Token Holders endpoint has a fixed CU cost of 2 per request. See the Compute Units page for detailed information.

Authorizations

X-Sim-Api-Key · string · header · required

API key for authentication. Obtain your key from the Dune dashboard at sim.dune.com.

Path Parameters

chain_id · integer<int32> · default: 8453 · required

The chain id of the blockchain (e.g., 8453 for Base). For a full list see Supported Chains.

address · string<address> · default: 0x63706e401c06ac8513145b7687A14804d17f814b · required

The token contract address.

Pattern: ^0x[a-fA-F0-9]{40}$

Query Parameters

limit · integer<int32> · default: 500

Maximum number of token holders to return. Default is 500 when not provided. Values above 500 are reduced to 500.

Required range: 1 <= x <= 500

offset · string

Pagination token from the previous response's next_offset field.

Response

200

application/json

A list of token holders for the specified token address on the specified chain.

token_address · string<address>

The address of the token contract.

Example:

"0x63706e401c06ac8513145b7687a14804d17f814b"

chain_id · integer<int32>

The identifier of the blockchain. For a full list see Supported Chains

Example:

8453

holders · object[]

A list of token holders and their balances.

Show child attributes

next_offset · string

An opaque token for fetching the next page of results. Null if no more results.

Example:

"eyJvZmZzZXQiOjEwMH0="