持倉成本趨勢

介面描述

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

使用情境：

• 適用於追蹤特定位址的持倉成本變化
• 適用於分析位址的建倉成本區間
• 適用於評估位址的持倉策略和成本管理

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

請求 URL

• 方法：POST
• 路徑：/open/v1/chain/trade/token/holdTrend

點數消耗

• 消耗點數：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	餘額
holding	number	string	持倉成本
holdingPrice	number	string	持倉價格
price	number	string	幣價

欄位業務含義

欄位	業務含義	使用建議
holding	持倉成本	該位址買入代幣的平均成本，用於計算盈虧
holdingPrice	持倉價格	基於持倉成本計算的價格指標

請求範例

{
    "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/holdTrend' \
--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/holdTrend" ^
--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",               // 餘額
            "holding": "0",               // 持倉成本
            "holdingPrice": "0",          // 持倉價格
            "price": "6359.49"            // 幣價
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542124800000,
            "balance": "1",
            "holding": "5738.35",
            "holdingPrice": "5738.35",
            "price": "5738.35"
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542211200000,
            "balance": "0",
            "holding": "0",
            "holdingPrice": "0",
            "price": "5648.03"
        }
        // ... 更多資料省略
    ],
    "requestId": "xxx-xxx-xxx"
}