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 | Array | 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=8453&tokenContractAddress=0xfde4c96c8593536e31f229ea8f37b2ada2699bb2&rangeFilter=1' \
--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,
"msg": "success",
"error_code": "0",
"error_message": "",
"detailMsg": "",
"data": {
"holdingAmount": "9651442.5",
"holdingPercent": "0.42483",
"clusterTrendType": [
"buy",
"transferIn"
],
"averageHoldingPeriod": "1744614666",
"averagePnlUsd": "null",
"averageBuyPriceUsd": "null",
"averageBuyPricePercent": "null",
"averageSellPriceUsd": "null",
"averageSellPricePercent": "null"
}
}