Get Token Top Holders Cluster Overview#
Get the overview data for the top 10/50/100 holding addresses of a specified token.
Request Path#
GET https://web3.okx.com/api/v6/dex/market/token/cluster/top-holders
Request Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
| chainIndex | string | Yes | Unique chain identifier. Pass in the chain ID (e.g., 501 for Solana). Only supports single-chain queries |
| tokenContractAddress | string | Yes | Token contract address |
| rangeFilter | string | Yes | Data for the top 10/50/100 holding addresses. Values: 1=10, 2=50, 3=100 |
Response Parameters#
| Field | Type | Description |
|---|---|---|
| holdingAmount | string | Total token holdings of the top 10/50/100 addresses (excluding black holes and liquidity pool addresses) |
| holdingPercent | string | Percentage of token supply held by the top 10/50/100 addresses |
| clusterTrendType | object | Buy/Sell/Neutral/Transfer dominant. The overall direction of traders' holdings over time — increasing (buying), decreasing (selling), flat (neutral), or primarily accumulated through transfers (transfer dominant) |
| averageHoldingPeriod | string | Weighted average holding period of the top 10/50/100 holders |
| averagePnlUsd | string | Weighted average PnL of the top 10/50/100 holders |
| averageBuyPriceUsd | string | Weighted average cost price of the top 10/50/100 holders |
| averageBuyPricePercent | string | Percentage difference between the average cost price of the top 10/50/100 holders and the current token price |
| averageSellPriceUsd | string | Weighted average selling price of the top 10/50/100 holders |
| averageSellPricePercent | string | Percentage difference between the average selling price of the top 10/50/100 holders and the current token price |
Request Example#
Shell
curl --location --request GET 'https://web3.okx.com/api/v6/dex/market/token/cluster/top-holders?chainIndex=1&tokenContractAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&rangeFilter=2' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z'
Response Example#
Json
{
"code": "0",
"data": [
{
"holdingAmount": "1250000000.00",
"holdingPercent": "25.40",
"clusterTrendType": {
"trendType": "buy"
},
"averageHoldingPeriod": "45",
"averagePnlUsd": "12340.56",
"averageBuyPriceUsd": "0.9985",
"averageBuyPricePercent": "-0.15",
"averageSellPriceUsd": "1.0023",
"averageSellPricePercent": "0.23"
}
],
"msg": ""
}