> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sim.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Token Holders
> Discover token distribution across ERC20 token holders, ranked by balance descending.
export const SupportedChains = ({endpoint, title, excludeChains}) => {
const dataState = useState(null);
const data = dataState[0];
const setData = dataState[1];
useEffect(function () {
var url = "https://api.sim.dune.com/v1/evm/supported-chains";
fetch(url, {
method: "GET"
}).then(function (response) {
return response.json();
}).then(function (responseData) {
setData(responseData);
});
}, [endpoint]);
if (data === null) {
return Loading chain information...
;
}
if (!data.chains) {
return No chain data available
;
}
var supportedChains = [];
var totalChains = data.chains.length;
var excludedChainNames = excludeChains || [];
for (var i = 0; i < data.chains.length; i++) {
var chain = data.chains[i];
if (excludedChainNames.indexOf(chain.name) !== -1) continue;
if (endpoint === undefined) {
supportedChains.push(chain);
} else if (chain[endpoint] && chain[endpoint].supported) {
supportedChains.push(chain);
}
}
var count = supportedChains.length;
var endpointName = endpoint ? endpoint.charAt(0).toUpperCase() + endpoint.slice(1).replace(/_/g, " ") : "All";
var accordionTitle = title ? title + " (" + count + ")" : "Supported Chains (" + count + ")";
return
| name |
chain_id |
tags |
{supportedChains.map(function (chain) {
return
{chain.name} |
{chain.chain_id} |
{chain.tags ? chain.tags.join(", ") : ""} |
;
})}
;
};
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
```bash theme={null}
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:
```json Response (JSON) [expandable] theme={null}
{
"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](/compute-units) page for detailed information.
## OpenAPI
````yaml /openapi.json GET /v1/evm/token-holders/{chain_id}/{address}
openapi: 3.0.3
info:
title: Sim API
description: >-
The Sim API by Dune provides real-time blockchain data across EVM and SVM
chains. Access token balances, transaction history, on-chain activity, DeFi
positions, NFT collectibles, token information, and webhook subscriptions
through a unified REST API.
version: 1.0.0
license:
name: ''
contact:
name: Dune Support
url: https://docs.sim.dune.com
email: support@dune.com
servers:
- url: https://api.sim.dune.com
security:
- ApiKeyAuth: []
tags:
- name: evm
description: EVM-compatible blockchain endpoints.
- name: svm
description: Solana/SVM blockchain endpoints.
- name: activity
description: On-chain activity feed.
- name: balances
description: Token balances (EVM and SVM).
- name: transactions
description: Transaction history (EVM and SVM).
- name: collectibles
description: NFT and ERC721/ERC1155 holdings.
- name: defi
description: DeFi protocol positions.
- name: supported-chains
description: Supported blockchain networks.
- name: token-info
description: Token metadata and pricing.
- name: token-holders
description: Token holder distribution.
- name: subscriptions
description: >-
Webhook subscription management for real-time on-chain event
notifications.
paths:
/v1/evm/token-holders/{chain_id}/{address}:
get:
tags:
- evm
- token-holders
summary: Get Token Holders
description: >-
Retrieves a list of token holders for a given token contract address on
a specified blockchain.
operationId: getTokenHolders
parameters:
- name: chain_id
in: path
required: true
description: >-
The chain id of the blockchain (e.g., 8453 for Base). For a full
list see [Supported Chains](/evm/supported-chains).
schema:
type: integer
format: int32
default: 8453
example: 8453
- name: address
in: path
required: true
description: The token contract address.
schema:
type: string
format: address
pattern: ^0x[a-fA-F0-9]{40}$
default: '0x63706e401c06ac8513145b7687A14804d17f814b'
example: '0x63706e401c06ac8513145b7687A14804d17f814b'
- name: limit
in: query
required: false
description: >-
Maximum number of token holders to return. Default is 500 when not
provided. Values above 500 are reduced to 500.
schema:
type: integer
format: int32
minimum: 1
maximum: 500
default: 500
- name: offset
in: query
required: false
description: Pagination token from the previous response's next_offset field.
schema:
type: string
responses:
'200':
description: >-
A list of token holders for the specified token address on the
specified chain.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenHoldersResponse'
examples:
success:
value:
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=
'400':
description: Bad Request - Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenHolders_ErrorResponse'
examples:
badRequest:
value:
error:
message: >-
Verify the address format and other parameters in your
request
code: BAD_REQUEST
'401':
description: Unauthorized - Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
invalidApiKey:
value:
error: invalid API Key
'404':
description: Not Found - Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenHolders_ErrorResponse'
examples:
notFound:
value:
error:
message: Resource not found
code: NOT_FOUND
'429':
description: Rate Limit Exceeded - Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
rateLimitExceeded:
value:
error: >-
Too many requests. Please contact sales@dune.com to
increase your limit.
'500':
description: Internal Server Error - Server-side error.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenHolders_ErrorResponse'
examples:
internalServerError:
value:
error:
message: Server-side error
code: INTERNAL_SERVER_ERROR
components:
schemas:
TokenHoldersResponse:
type: object
properties:
token_address:
type: string
format: address
description: The address of the token contract.
example: '0x63706e401c06ac8513145b7687a14804d17f814b'
chain_id:
type: integer
format: int32
description: >-
The identifier of the blockchain. For a full list see Supported
Chains
example: 8453
holders:
type: array
items:
$ref: '#/components/schemas/Holder'
description: A list of token holders and their balances.
next_offset:
type: string
description: >-
An opaque token for fetching the next page of results. Null if no
more results.
example: eyJvZmZzZXQiOjEwMH0=
TokenHolders_ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
required:
- error
GatewayErrorResponse:
type: object
description: >-
Error response from the API gateway. Returned for authentication,
permissions, rate-limiting, and quota errors.
properties:
error:
type: string
description: Error message.
required:
- error
Holder:
type: object
properties:
wallet_address:
type: string
description: The address of the token holder.
example: '0x4a79b0168296c0ef7b8f314973b82ad406a29f1b'
balance:
type: string
description: >-
The raw balance of tokens held by the address, as a string to
support large numbers.
example: '13794442047246482254818'
first_acquired:
type: string
format: date-time
description: The timestamp when the holder first acquired tokens.
example: '2025-02-06T15:11:07+00:00'
has_initiated_transfer:
type: boolean
description: Indicates if the holder has initiated a transfer of these tokens.
example: false
ErrorDetail:
type: object
properties:
message:
type: string
description: Description of what went wrong.
example: Invalid or missing API key
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- message
- code
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Sim-Api-Key
description: >-
API key for authentication. Obtain your key from the Dune dashboard at
sim.dune.com.
````