余额趋势

接口描述

获取指定地址在区块链上对某个代币的持仓余额数据，支持通过指定代币、指定链名、指定时间段查询该地址的持仓余额来判断变化趋势。

使用场景：

• 适用于追踪特定地址的持仓余额变化
• 适用于判断地址的筹码积累和减持行为
• 适用于大户地址持仓动态监控

数据更新频率：每天更新一次

请求URL

• 方法：POST
• 路径：/open/v1/chain/trade/token/balanceTrend

积分消耗

• 消耗积分：2

前置条件

获取 vsTokenId

条件	说明	获取方式
已有 vsTokenId	直接使用缓存的 vsTokenId，无需重复查询	上下文自动提取
未有 vsTokenId	调用 POST /vs-token/list 接口获取	前置接口调用

获取 coinKey

条件	说明	获取方式
已有 coinKey	直接使用缓存的 coinKey，无需重复查询	上下文自动提取
未有 coinKey	调用 POST /vs-token/detail 接口获取该代币在不同链上的 coinKey	前置接口调用

获取 address

条件	说明	获取方式
已有 address	直接使用已知的持仓地址	用户输入
未有 address	调用 POST /chain/trade/token/holdPage 接口查询持仓地址列表	前置接口调用

请求参数

参数通过请求体（Body）以 JSON 格式传递。

参数名	类型	必需	描述
vsTokenId	long	是	代币 ID
coinKey	string	是	代币的 coinKey（链+合约地址），通过代币详情获取
address	string	是	地址
startTime	long	否	开始时间（毫秒时间戳）
endTime	long	是	截止时间（毫秒时间戳）

响应字段

仅展示 data 数组内每个对象的字段结构：

字段	类型	实际返回类型	描述
vsTokenId	long	string	代币 ID
symbol	string	string	代币符号
name	string	string	代币名称
date	long	long	时间（毫秒时间戳）
balance	number	string	余额
price	number	string	币价

字段业务含义

字段	业务含义	使用建议
balance	地址余额	反映该地址持有的代币数量，持续增加表示在积累筹码

请求示例

{
    "vsTokenId": 1,                         // 代币 id
    "coinKey": "BTC_BTC",                    // 代币的 coinKey（链+合约地址），通过代币详情获取
    "address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6", // 地址
    "endTime": 1773479265534                  // 截止时间
}

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

成功响应示例

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "vsTokenId": "1",           // 代币 ID
            "symbol": "BTC",             // 代币符号
            "name": "Bitcoin",           // 代币名称
            "date": 1542038400000,       // 时间
            "balance": "0",              // 余额
            "price": "6359.49"           // 币价
        },
        {
            "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"
        }
        // ... 更多数据省略
    ],
    "requestId": "xxx-xxx-xxx"
}