持幣地址
介面描述
取得指定代幣在鏈上的持倉位址列表及位址的基礎資訊資料，同時支援指定位址的基礎資訊查詢。
使用情境：
- 適用於鯨魚、專案方、交易所等在鏈上的相關資訊追蹤與分析
- 適用於識別大戶持倉行為和位址歸屬分析
- 適用於鏈上持倉分佈和籌碼集中度研究
資料更新頻率：即時更新
請求 URL
- 方法：
POST - 路徑：
/open/v1/chain/trade/token/holdPage
點數消耗
- 消耗點數：
2
前置條件
取得 vsTokenId
| 條件 | 說明 | 取得方式 |
|---|---|---|
| 已有 vsTokenId | 直接使用快取的 vsTokenId，無需重複查詢 | 上下文自動提取 |
| 未有 vsTokenId | 呼叫 POST /vs-token/list 介面取得 | 前置介面呼叫 |
取得 coinKey
| 條件 | 說明 | 取得方式 |
|---|---|---|
| 已有 coinKey | 直接使用快取的 coinKey，無需重複查詢 | 上下文自動提取 |
| 未有 coinKey | 呼叫 POST /vs-token/detail 介面取得該代幣在不同鏈上的 coinKey | 前置介面呼叫 |
請求參數
參數透過請求體（Body）以 JSON 格式傳遞。
| 參數名 | 類型 | 必需 | 描述 |
|---|---|---|---|
| vsTokenId | long | 是 | 代幣 ID |
| page | integer | 是 | 當前頁，預設 1 |
| pageSize | integer | 是 | 當前頁資料數量，預設 10，最多查詢 10000 條資料 |
| coinKey | string | 是 | 代幣的 coinKey 資訊（鏈+合約位址資訊），透過代幣詳情取得 |
| address | string | 否 | 位址 |
回應欄位
僅展示 data 陣列內每個物件的欄位結構：
| 欄位 | 類型 | 實際回傳類型 | 描述 |
|---|---|---|---|
| vsTokenId | long | string | 代幣 ID |
| symbol | string | string | 代幣符號 |
| name | string | string | 代幣名稱 |
| coinKey | string | string | 代幣鍵 |
| address | string | string | 位址 |
| label | object | object | 位址標籤 |
| labelName | string | string | 標籤名 |
| iconUrl | string | string | 圖示 URL |
| isContract | boolean | boolean | 是否是合約位址 |
| exchangeSymbol | string | string | 交易所名稱 |
| labelType | string | string | 類型 |
| reliability | integer | integer | 可信度 |
| balance | number | string | 餘額 |
| price | number | string | 價格 |
| profit | number | string | 盈利 |
| cost | number | string | 持倉成本 |
| preCost | number | string | 前一次持倉成本 |
| chainName | string | string | 鏈名 |
欄位業務含義
| 欄位 | 業務含義 | 使用建議 |
|---|---|---|
| label | 位址標籤 | 標識位址歸屬（如交易所、合約等），幫助識別大戶身份 |
| profit | 持倉盈利 | 基於當前價格和持倉成本計算的浮動盈虧 |
| cost | 持倉成本 | 該位址買入代幣的平均成本價 |
請求範例
json
{
"vsTokenId": 1, // 代幣 ID
"page": 1, // 當前頁，預設 1
"pageSize": 10, // 當前頁資料數量，預設 10，最多查詢 10000 條資料
"coinKey": "BTC_BTC" // 代幣的 coinKey 資訊（鏈+合約位址資訊），透過代幣詳情取得
}cURL 範例（Linux/macOS）
bash
curl --location --request POST 'http://${host}/api/open/v1/chain/trade/token/holdPage' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
"vsTokenId": 1,
"page": 1,
"pageSize": 10,
"coinKey": "BTC_BTC"
}'cURL 範例（Windows CMD）
cmd
curl --location --request POST "http://${host}/api/open/v1/chain/trade/token/holdPage" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{ \"vsTokenId\": 1, \"page\": 1, \"pageSize\": 10, \"coinKey\": \"BTC_BTC\"}"成功回應範例
json
{
"code": 200,
"message": "success",
"data": [
{
"vsTokenId": "1", // 代幣 ID
"symbol": "BTC", // 代幣符號
"name": "Bitcoin", // 代幣名稱
"coinKey": "BTC_BTC", // 代幣鍵
"address": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo", // 位址
"label": { // 位址標籤
"labelName": "Binance Cold Wallet", // 標籤名
"iconUrl": "/icon/label/Binance.png", // 圖示 URL
"isContract": false, // 是否是合約位址
"exchangeSymbol": "", // 交易所名稱
"labelType": "Exchange", // 類型
"reliability": "" // 可信度
},
"balance": "248597.58214169", // 餘額
"price": "70624.85790154382", // 價格
"profit": "7913271920.4341697967652188545", // 盈利
"cost": "38828.441617175034708941", // 持倉成本
"preCost": "38828.441617175034708941", // 前一次持倉成本
"chainName": "BTC" // 鏈名
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6",
"label": {
"labelName": "Binance Cold Wallet",
"iconUrl": "/icon/label/Binance.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "Exchange",
"reliability": ""
},
"balance": "156026.54705644",
"price": "70624.85790154382",
"profit": "1804396311.20359371149441240088",
"cost": "59095.423712405135733623",
"preCost": "59095.423712405135733623",
"chainName": "BTC"
},
{
"vsTokenId": "1",
"symbol": "BTC",
"name": "Bitcoin",
"coinKey": "BTC_BTC",
"address": "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
"label": {
"labelName": "Robinhood Cold",
"iconUrl": "/icon/default.png",
"isContract": false,
"exchangeSymbol": "",
"labelType": "",
"reliability": ""
},
"balance": "140574.82614005",
"price": "70624.85790154382",
"profit": "5416163383.0562816957331038294",
"cost": "32131.412397458211476123",
"preCost": "32131.412397458211476123",
"chainName": "BTC"
}
// ... 更多資料省略
],
"requestId": "xxx-xxx-xxx"
}