資金快照

介面描述

查詢指定代幣在指定時間点的資金快照。回傳該時間点下，多個統計週期（5分鐘、15分鐘、30分鐘……24小時）的資金快照資料。

資料保留規則（非常重要） 系統為每個統計週期（如5分鐘、15分鐘、24小時等）分別保留最近100個時間点的資料。

對於5分鐘週期：保留最近100個整5分鐘時刻（約8.33小時）
對於24小時週期：保留最近100天（每天一個時間点）其他週期以此類推。

這意味着：

若您查詢的時間点超出了對應週期的100個点範圍（例如用5分鐘週期查8.33小時前的9:50，或查100天前的日期），介面**無法回傳精確資料 **。
此時系統會回傳該時間点之前最近的一個有效資料点（例如9:50查不到，則回傳9:45的資料），而不會強行回傳當天08:00的累計值。

為什麼這樣設計？為了保證效能和歷史資料的可追溯性，我們只保留最近100個時間点的明細。若您需要查詢更早的資料，請使用更大週期的介面（如日線資料）。

請求 URL

方法：POST
路徑：/open/v1/trade/getCoinTradeSnapshot

點數消耗

消耗點數：4

前置條件

取得 vsTokenId

條件	說明	取得方式
已有 vsTokenId	直接使用快取的 vsTokenId，無需重複查詢	上下文自動提取
未有 vsTokenId	呼叫 `POST /vs-token/list` 介面取得	前置介面呼叫

請求參數

參數透過請求體（Body）以 JSON 格式傳遞。

參數名	類型	必需	描述
vsTokenId	integer	是	代幣 ID
date	long	是	指定日期（毫秒時間戳）

回應欄位

僅展示 data 物件內的欄位結構：

欄位	類型	實際回傳類型	描述
updateTime	integer	long	更新時間（毫秒時間戳）
vsTokenId	integer	string	代幣 ID
symbol	string	string	代幣符號
name	string	string	代幣名稱
coinPrice	number	string	幣價(USD)
hasSpotGoods	boolean	boolean	是否存在現貨資料
spotMaxInflow	number	string	現貨主力資金累積
spotGoodsList	array	array	現貨資料
timeRange	string	string	時間範圍
timeParticleEnum	integer	integer	統計時間粒度
tradeInflow	number	string	交易淨流入金額(USD)
tradeAmount	number	string	交易量(USD)
hasContract	boolean	boolean	是否存在合約資料
contractMaxInflow	number	string	合約主力資金累積
contractList	array	array	合約資料
timeRange	string	string	時間範圍
timeParticleEnum	integer	integer	統計時間粒度
tradeInflow	number	string	交易淨流入金額(USD)
tradeAmount	number	string	交易量(USD)

欄位業務含義

欄位	業務含義	使用建議
spotMaxInflow	現貨主力累積	主力資金為現貨交易的所有時間窗口中的最大資金淨流入，主力累積為各時間窗口的資金資料
contractMaxInflow	合約主力累積	主力資金為現貨交易的所有時間窗口中的最大資金淨流入，主力累積為各時間窗口的資金資料
date	快照日期	查詢的歷史資料時間点，最小時間顆粒5分鐘

請求範例

json

{
  "vsTokenId": 1,
  // 代币 id
  "date": 1773654600000
  // 指定日期（时间戳）
}

cURL 範例（Linux/macOS）

bash

curl --location --request POST 'http://${host}/api/open/v1/trade/getCoinTradeSnapshot' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
    "vsTokenId": 1,
    "date": 1773654600000
}'

cURL 範例（Windows CMD）

cmd

curl --location --request POST "http://${host}/api/open/v1/trade/getCoinTradeSnapshot" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{    \"vsTokenId\": 1,    \"date\": 1773654600000}"

成功回應範例

json

{
  "code": 200,
  "message": "success",
  "data": {
    "updateTime": 1773654600000,
    // 更新时间
    "vsTokenId": "1",
    // 代币 ID
    "symbol": "BTC",
    // 代币符号
    "name": "Bitcoin",
    // 代币名称
    "coinPrice": "70559.18",
    // 币价(USD)
    "hasSpotGoods": true,
    // 是否存在现货数据
    "spotMaxInflow": "173206257.989364",
    // 现货主力资金积累
    "spotGoodsList": [
      {
        "timeRange": "m5",
        // 时间范围
        "timeParticleEnum": 5,
        // 统计时间粒度
        "tradeInflow": "973669.0454980996",
        // 交易净流入金额(USD)
        "tradeAmount": "4176136.897351299"
        // 交易量(USD)
      },
      {
        "timeRange": "m15",
        "timeParticleEnum": 15,
        "tradeInflow": "1531287.2033347988",
        "tradeAmount": "11822696.069185598"
      },
      {
        "timeRange": "m30",
        "timeParticleEnum": 30,
        "tradeInflow": "2668474.962980899",
        "tradeAmount": "25890934.620040294"
      }
      // ... 更多数据省略
    ],
    "hasContract": true,
    // 是否存在合约数据
    "contractMaxInflow": "5115857220.793299",
    // 合约主力资金积累
    "contractList": [
      {
        "timeRange": "m5",
        // 时间范围
        "timeParticleEnum": 5,
        // 统计时间粒度
        "tradeInflow": "7412113.461600001",
        // 交易净流入金额(USD)
        "tradeAmount": "33097685.519799992"
        // 交易量(USD)
      },
      {
        "timeRange": "m15",
        "timeParticleEnum": 15,
        "tradeInflow": "5682104.7779",
        "tradeAmount": "69809754.7091"
      },
      {
        "timeRange": "m30",
        "timeParticleEnum": 30,
        "tradeInflow": "-6355722.267499994",
        "tradeAmount": "183233913.60549998"
      }
      // ... 更多数据省略
    ]
  },
  "requestId": "xxx-xxx-xxx"
}

重要注意事項

資料保留範圍
- 每個統計週期只保留最近100個時間点的資料。
- 查詢超出範圍的時間点（如100天前），系統會回傳該時間点之前最近的一個有效資料点。
時間對齐 您傳入的 date 會被向下取整到最近的整5分鐘（例如 15:16 → 15:15）。
時區所有時間基於 UTC+8。

常見問題

Q: 我查詢 4月1日 18:16 的資料，為什麼回傳的是 4月1日 18:15 的資料？

A: 因為時間會自動對齐到最近的整5分鐘（18:16 → 18:15）。如果 18:15 在保留範圍內，就會回傳該点資料。

Q: 我查詢 100 天前的資料，回傳的結果是什麼？

A: 如果該時間点超出了對應週期的100個点範圍，系統會回傳該時間点之前最近的一個有效資料点。例如，5分鐘週期只保留最近8.33小時，查詢更早的時間會回傳 8.33 小時前的那個点；24小時週期保留最近100天，查詢第101天會回傳空值。

Q: 我查詢 4月1日 18:16 的資料，為什麼回傳的是當天 08:00 的資料？

A: 如果該時間点超出了對應週期的100個点範圍，系統會回傳該時間点之前最近的一個有效資料点，直至當天。

資金快照 ​

介面描述 ​

請求 URL ​

點數消耗 ​

前置條件 ​

請求參數 ​

回應欄位 ​

欄位業務含義 ​

請求範例 ​

cURL 範例（Linux/macOS） ​

cURL 範例（Windows CMD） ​

成功回應範例 ​

重要注意事項 ​

常見問題 ​