Get Token Cluster List#
Get the list of holding clusters for a specified token. Only includes address clusters within the top 300 holders.
Limit: Returns only the top 100 clusters by holding amount
Request Path#
GET https://web3.okx.com/api/v6/dex/market/token/cluster/list
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 |
Response Parameters#
| Field | Type | Description |
|---|---|---|
| clustList | array | Cluster list |
| > holdingAmount | string | Total token holdings of cluster addresses (excluding black holes and liquidity pool addresses) |
| > holdingValueUsd | string | Total USD value of token holdings of cluster addresses (excluding black holes and liquidity pool addresses) |
| > holdingPercent | string | Percentage of token supply held by cluster addresses |
| > trendType | object | Buy/Sell/Neutral/Transfer dominant. The overall direction of cluster traders' holdings over time — increasing (buying), decreasing (selling), flat (neutral), or primarily accumulated through transfers (transfer dominant) |
| > averageHoldingPeriod | string | Weighted average holding period of cluster holders |
| > pnlUsd | string | Total token PnL of cluster holders |
| > pnlPercent | string | Total token PnL percentage of cluster holders |
| > buyVolume | string | Value of tokens bought by cluster holders |
| > averageBuyPriceUsd | string | Average cost price of cluster holders |
| > sellVolume | string | Value of tokens sold by cluster holders |
| > averageSellPriceUsd | string | Weighted average selling price of cluster holders |
| > lastActiveTimestamp | string | Last active time |
| > clusterAddressList | array | List of addresses in the cluster |
| >> address | string | Address |
| >> holdingAmount | string | Total token holdings of cluster addresses (excluding black holes and liquidity pool addresses) |
| >> holdingValueUsd | string | Total USD value of token holdings of cluster addresses (excluding black holes and liquidity pool addresses) |
| >> holdingPercent | string | Percentage of token supply held by cluster addresses |
| >> averageHoldingPeriod | string | Average holding period of the address |
| >> lastActiveTimestamp | string | Last active time |
| >> isContract | boolean | Whether it is a contract address |
| >> isExchange | boolean | Whether it is an exchange address |
| >> isKol | boolean | Whether it is a KOL address |
| >> addressRank | string | Address holding rank |
Request Example#
Shell
curl --location --request GET 'https://web3.okx.com/api/v6/dex/market/token/cluster/list?chainIndex=1&tokenContractAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' \
--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": [
{
"clustList": [
{
"holdingAmount": "320000000.00",
"holdingValueUsd": "320145600.00",
"holdingPercent": "6.52",
"trendType": {
"trendType": "buy"
},
"averageHoldingPeriod": "62",
"pnlUsd": "45230.12",
"pnlPercent": "14.15",
"buyVolume": "980000.00",
"averageBuyPriceUsd": "0.9982",
"sellVolume": "210000.00",
"averageSellPriceUsd": "1.0015",
"lastActiveTimestamp": "1697630501000",
"clusterAddressList": [
{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"holdingAmount": "180000000.00",
"holdingValueUsd": "180082800.00",
"holdingPercent": "3.67",
"averageHoldingPeriod": "75",
"lastActiveTimestamp": "1697630501000",
"isContract": false,
"isExchange": true,
"isKol": false,
"addressRank": "1"
}
]
}
]
}
],
"msg": ""
}