资金快照

接口描述

查询指定代币在指定时间点的资金快照。返回该时间点下，多个统计周期（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） ​

成功响应示例 ​

重要注意事项 ​

常见问题 ​