資金快照

介面描述

查詢指定代幣在指定時間點的資金快照。回傳該時間點下，多個統計週期（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

點數消耗

消耗點數：3

前置條件

取得 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	代幣名稱
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",
    // 代幣名稱
    "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） ​

成功回應範例 ​

重要注意事項 ​

常見問題 ​