Token Holders
Description
Returns a paginated list of on-chain holding addresses and basic address information for a specified token. Also supports querying basic information for a specific address.
Use cases:
- Track and analyze on-chain information for whales, project teams, exchanges, etc.
- Identify whale holding behavior and address ownership
- Study on-chain holding distribution and chip concentration
Update frequency: Real-time
Endpoint
- Method:
POST - Path:
/open/v1/chain/trade/token/holdPage
Credits
- Cost:
2
Prerequisites
Obtain vsTokenId
| Condition | Description | How to obtain |
|---|---|---|
| vsTokenId available | Use cached vsTokenId; no repeat lookup | Auto-extracted from context |
| vsTokenId missing | Call POST /vs-token/list | Prerequisite API call |
Obtain coinKey
| Condition | Description | How to obtain |
|---|---|---|
| coinKey available | Use cached coinKey; no repeat lookup | Auto-extracted from context |
| coinKey missing | Call POST /vs-token/detail to get coinKey for each chain | Prerequisite API call |
Request parameters
Parameters are sent as JSON in the request body.
| Field | Type | Required | Description |
|---|---|---|---|
| vsTokenId | long | Yes | Token ID |
| page | integer | Yes | Current page; default 1 |
| pageSize | integer | Yes | Items per page; default 10, max 10,000 records |
| coinKey | string | Yes | Token coinKey (chain + contract address); obtain from token details |
| address | string | No | Address |
Response fields
Structure of each object in the data array:
| Field | Type | Serialized | Description |
|---|---|---|---|
| vsTokenId | long | string | Token ID |
| symbol | string | string | Token symbol |
| name | string | string | Token name |
| coinKey | string | string | Token key |
| address | string | string | Address |
| label | object | object | Address label |
| labelName | string | string | Label name |
| iconUrl | string | string | Icon URL |
| isContract | boolean | boolean | Whether it is a contract address |
| exchangeSymbol | string | string | Exchange name |
| labelType | string | string | Type |
| reliability | integer | integer | Reliability |
| balance | number | string | Balance |
| price | number | string | Price |
| profit | number | string | Profit |
| cost | number | string | Holding cost |
| preCost | number | string | Previous holding cost |
| chainName | string | string | Chain name |
Field semantics
| Field | Meaning | Tip |
|---|---|---|
| label | Address label | Identifies address ownership (e.g. exchange, contract); helps identify whale identity |
| profit | Holding profit | Floating P&L based on current price and holding cost |
| cost | Holding cost | Average buy price for tokens at this address |
Example
json
{
"vsTokenId": 1, // Token ID
"page": 1, // Current page; default 1
"pageSize": 10, // Items per page; default 10, max 10,000 records
"coinKey": "BTC_BTC" // Token coinKey (chain + contract address); obtain from token details
}cURL (Linux/macOS)
bash
curl --location --request POST 'http://${host}/api/open/v1/chain/trade/token/holdPage' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
"vsTokenId": 1,
"page": 1,
"pageSize": 10,
"coinKey": "BTC_BTC"
}'cURL (Windows CMD)
cmd
curl --location --request POST "http://${host}/api/open/v1/chain/trade/token/holdPage" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{ \"vsTokenId\": 1, \"page\": 1, \"pageSize\": 10, \"coinKey\": \"BTC_BTC\"}"Success response example
json
{
"code": 200,
"message": "success",
"data": [
{
"vsTokenId": "1", // Token ID
"symbol": "BTC", // Token symbol
"name": "Bitcoin", // Token name
"coinKey": "BTC_BTC", // Token key
"address": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo", // Address
"label": { // Address label
"labelName": "Binance Cold Wallet", // Label name
"iconUrl": "/icon/label/Binance.png", // Icon URL
"isContract": false, // Whether it is a contract address
"exchangeSymbol": "", // Exchange name
"labelType": "Exchange", // Type
"reliability": "" // Reliability
},
"balance": "248597.58214169", // Balance
"price": "70624.85790154382", // Price
"profit": "7913271920.4341697967652188545", // Profit
"cost": "38828.441617175034708941", // Holding cost
"preCost": "38828.441617175034708941", // Previous holding cost
"chainName": "BTC" // Chain name
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6",
"label": {
"labelName": "Binance Cold Wallet",
"iconUrl": "/icon/label/Binance.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "Exchange",
"reliability": ""
},
"balance": "156026.54705644",
"price": "70624.85790154382",
"profit": "1804396311.20359371149441240088",
"cost": "59095.423712405135733623",
"preCost": "59095.423712405135733623",
"chainName": "BTC"
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
"label": {
"labelName": "Robinhood Cold",
"iconUrl": "/icon/default.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "",
"reliability": ""
},
"balance": "140574.82614005",
"price": "70624.85790154382",
"profit": "5416163383.0562816957331038294",
"cost": "32131.412397458211476123",
"preCost": "32131.412397458211476123",
"chainName": "BTC"
}
// ... more data omitted
],
"requestId": "xxx-xxx-xxx"
}