餘額趨勢

介面描述

取得指定位址在區塊鏈上對某個代幣的持倉餘額資料，支援透過指定代幣、指定鏈名、指定時間段查詢該位址的持倉餘額來判斷變化趨勢。

使用情境：

• 適用於追蹤特定位址的持倉餘額變化
• 適用於判斷位址的籌碼積累和減持行為
• 適用於大戶位址持倉動態監控

資料更新頻率：每天更新一次

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