Whale Cost Trend

Description

Returns real-time average holding cost data for whale addresses across BTC-series, EVM-series, Tron, and other multi-chain networks for a token.

Use cases:

• Obtain average whale holding cost data on-chain for a specified token
• Whale behavior analysis
• Assess how far the current price deviates from whale cost

Tips:

• When users ask about whale cost in natural language, this endpoint typically provides on-chain whale cost data
• For comprehensive queries such as whale analysis or whale status, call this endpoint

Update frequency: Updated once per day

Endpoint

• Method: POST
• Path: /open/v1/trade/getCoinTradeCost

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

Request parameters

Parameters are sent as JSON in the request body.

Field	Type	Required	Description
vsTokenId	long	Yes	Token ID
startTime	long	No	Start time (millisecond timestamp)
endTime	long	No	End time (millisecond timestamp)

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
date	long	long	Time (millisecond timestamp)
price	number	string	Price at that time (USD)
cost	number	string	Whale cost (USD)
balance	number	string	Balance

Field semantics

Field	Meaning	Tip
cost	Whale holding cost	Average whale holding cost weighted by large trades; use to judge profit/loss relative to whales
balance	Whale holding balance	Reflects changes in whale holdings; sustained increases indicate accumulation
price	Token market price	Compare with cost to compute price deviation: (price - cost) / cost * 100%

Example

{
    "vsTokenId": 1,           // Token ID
    "startTime": 1770825600000, // Start time (timestamp)
    "endTime": 1773417600000    // End time (timestamp)
}

cURL (Linux/macOS)

curl --location --request POST 'http://${host}/api/open/v1/trade/getCoinTradeCost' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
    "vsTokenId": 1,
    "startTime": 1770825600000,
    "endTime": 1773417600000
}'

cURL (Windows CMD)

curl --location --request POST "http://${host}/api/open/v1/trade/getCoinTradeCost" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{    \"vsTokenId\": 1,    \"startTime\": 1770825600000,    \"endTime\": 1773417600000}"

Success response example

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "vsTokenId": "1",           // Token ID
            "symbol": "BTC",             // Token symbol
            "name": "Bitcoin",           // Token name
            "date": 1770825600000,       // Time
            "price": "67308.54906296561", // Price
            "cost": "60410.667759839053903122", // Whale cost
            "balance": "3878063.59266208"       // Balance
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1770912000000,
            "price": "66945.34755133065",
            "cost": "60419.968721902531478833",
            "balance": "3869188.04491703"
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1770998400000,
            "price": "66945.34755133065",
            "cost": "60530.743564442072031617",
            "balance": "3879695.17965919"
        }
        // ... more data omitted
    ],
    "requestId": "xxx-xxx-xxx"
}