Holder addresses

Description

Paged on-chain holders for a token (or filter one address), with labels and balances.

Use cases

• Whales, treasuries, exchanges
• Concentration and attribution

Update: Real-time

Endpoint

• Method: POST
• Path: /open/v1/chain/trade/token/holdPage

Credits

• Cost: 2

Prerequisites

vsTokenId — POST /vs-token/list

coinKey — POST /vs-token/detail

Request body (JSON)

Field	Type	Required	Description
vsTokenId	long	Yes	Token id
page	integer	Yes	Page (default 1)
pageSize	integer	Yes	Page size (default 10, max 10000)
coinKey	string	Yes	e.g. BTC_BTC
address	string	No	Optional filter

Response — data[]

Field	Type	Serialized	Description
vsTokenId	long	string	Token id
symbol	string	string	Ticker
name	string	string	Name
coinKey	string	string	Key
address	string	string	Address
label	object	object	Tag meta
labelName	string	string	Label
iconUrl	string	string	Icon URL
isContract	boolean	boolean	Contract flag
exchangeSymbol	string	string	Venue name
labelType	string	string	Type
reliability	integer	integer	Confidence
balance	number	string	Balance
price	number	string	Price
profit	number	string	Unrealized P&L
cost	number	string	Avg cost
preCost	number	string	Prior cost
chainName	string	string	Chain

Semantics

Field	Meaning	Tip
label	Attribution	Exchange vs contract etc.
profit	Floating P&L	Vs cost
cost	Cost basis	Average entry

Example

{
    "vsTokenId": 1,
    "page": 1,
    "pageSize": 10,
    "coinKey": "BTC_BTC"
}

cURL (Linux/macOS)

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)

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\"}"

Sample success

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "coinKey": "BTC_BTC",
            "address": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
            "label": {
                "labelName": "Binance Cold Wallet",
                "iconUrl": "/icon/label/Binance.png",
                "isContract": false,
                "exchangeSymbol": "",
                "labelType": "Exchange",
                "reliability": ""
            },
            "balance": "248597.58214169",
            "price": "70624.85790154382",
            "profit": "7913271920.4341697967652188545",
            "cost": "38828.441617175034708941",
            "preCost": "38828.441617175034708941",
            "chainName": "BTC"
        }
    ],
    "requestId": "xxx-xxx-xxx"
}