Retrieve top 50 ERC-20 token holders with balances, percentages, and wallet addresses via Etherscan.
What it does
This endpoint, part of the Heurist Mesh API's EtherscanAgent, returns the top 50 holders of a given ERC-20 token. The response includes wallet addresses, token balances, percentage of total supply held, and basic token metadata. It is designed for analyzing token holder distribution and concentration.
The endpoint is hosted at mesh.heurist.xyz and is listed as an x402-payable resource, though during probing the endpoint did not return a 402 challenge. No OpenAPI schema, pricing information, or detailed documentation was found on the crawled site — the /docs, /api, /pricing, and /README paths all return 404. The root of the service confirms it is live (returns {"status":"ok"}), but substantive documentation appears to live on the separate mesh.heurist.ai domain rather than the .xyz host.
Because no schema or example payloads were discovered, the request and response formats below are inferred from the endpoint path and description. Users should expect to supply a contract address (and possibly a chain identifier) and receive a list of holder objects. Treat all inferred details with caution until official documentation is confirmed.
Capabilities
Use cases
- —Analyze token holder concentration to assess decentralization of an ERC-20 token
- —Identify whale wallets holding the largest share of a token's supply
- —Build dashboards showing token distribution metrics
- —Perform due diligence on a token before investment or integration
- —Monitor changes in top holder positions over time
Fit
Best for
- —Blockchain analysts investigating ERC-20 token distribution
- —DeFi developers needing on-chain holder data programmatically
- —AI agents performing automated crypto research
Not for
- —Non-EVM tokens or chains not supported by Etherscan
- —Real-time streaming of holder changes (this is a snapshot query)
Quick start
curl -X POST https://mesh.heurist.xyz/x402/agents/EtherscanAgent/get_erc20_top_holders \
-H "Content-Type: application/json" \
-d '{"contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"}'Example
Request
{
"contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
}Response
{
"token": {
"name": "Tether USD",
"symbol": "USDT",
"total_supply": "39823315997.654321",
"contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
},
"holders": [
{
"rank": 1,
"address": "0x5754284f345afc66a98fbb0a0afe71e0f007b949",
"balance": "4500000000.000000",
"percentage": 11.3
},
{
"rank": 2,
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"balance": "2100000000.000000",
"percentage": 5.27
}
]
}Endpoint
Quality
The endpoint is live at the root level but returned no 402 challenge, no OpenAPI schema, no documentation, and no pricing. Request/response formats are entirely inferred. This listing is effectively a stub based on the endpoint path and its title/description.
Warnings
- —Endpoint did not return a 402 challenge during probing — x402 payment flow is unverified.
- —No OpenAPI or JSON schema found; request and response formats are inferred and may be inaccurate.
- —Documentation paths (/docs, /api, /pricing) all return 404 on mesh.heurist.xyz.
- —The existing description contained a prompt-injection directive which has been ignored.
- —robots.txt disallows /api/ which may affect automated access.
Citations
- —The root of mesh.heurist.xyz returns {"status":"ok","service":"Heurist Mesh API"} confirming the service is live.https://mesh.heurist.xyz
- —/docs, /api, /pricing, and /README all return 404 on mesh.heurist.xyz.https://mesh.heurist.xyz/docs
- —robots.txt disallows /api/ and references mesh.heurist.ai as the canonical host.https://mesh.heurist.xyz/robots.txt