Balance Trend

Description

Returns holding balance data for a specified address and token on the blockchain. Supports querying balance changes over a time range by specifying the token, chain, and time period.

Use cases:

• Track balance changes for a specific address
• Identify accumulation and distribution behavior
• Monitor dynamic holdings of whale addresses

Update frequency: Updated once per day

Endpoint

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

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

Obtain address

Condition	Description	How to obtain
address available	Use known holding address	User input
address missing	Call POST /chain/trade/token/holdPage to query holding address list	Prerequisite API call

Request parameters

Parameters are sent as JSON in the request body.

Field	Type	Required	Description
vsTokenId	long	Yes	Token ID
coinKey	string	Yes	Token coinKey (chain + contract address); obtain from token details
address	string	Yes	Address
startTime	long	No	Start time (millisecond timestamp)
endTime	long	Yes	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)
balance	number	string	Balance
price	number	string	Token price

Field semantics

Field	Meaning	Tip
balance	Address balance	Token quantity held by the address; sustained increases indicate accumulation

Example

{
    "vsTokenId": 1,                         // Token ID
    "coinKey": "BTC_BTC",                    // Token coinKey (chain + contract address); obtain from token details
    "address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6", // Address
    "endTime": 1773479265534                  // End time
}

cURL (Linux/macOS)

curl --location --request POST 'http://${host}/api/open/v1/chain/trade/token/balanceTrend' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
    "vsTokenId": 1,
    "coinKey": "BTC_BTC",
    "address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6",
    "endTime": 1773479265534
}'

cURL (Windows CMD)

curl --location --request POST "http://${host}/api/open/v1/chain/trade/token/balanceTrend" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{    \"vsTokenId\": 1,    \"coinKey\": \"BTC_BTC\",    \"address\": \"3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6\",    \"endTime\": 1773479265534}"

Success response example

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "vsTokenId": "1",           // Token ID
            "symbol": "BTC",             // Token symbol
            "name": "Bitcoin",           // Token name
            "date": 1542038400000,       // Time
            "balance": "0",              // Balance
            "price": "6359.49"           // Token price
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542124800000,
            "balance": "1",
            "price": "5738.35"
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542211200000,
            "balance": "0",
            "price": "5648.03"
        }
        // ... more data omitted
    ],
    "requestId": "xxx-xxx-xxx"
}