Snapshot dòng vốn

Mô tả API

Truy vấn snapshot dòng vốn của token tại một thời điểm cụ thể. Phản hồi gồm dữ liệu snapshot trên nhiều chu kỳ thống kê (5 phút, 15 phút, 30 phút, … 24 giờ) tại thời điểm đó.

Quy tắc lưu trữ dữ liệu (rất quan trọng)

Hệ thống lưu 100 mốc thời gian gần nhất riêng cho từng chu kỳ thống kê (ví dụ 5 phút, 15 phút, 24 giờ, v.v.).

Chu kỳ 5 phút: 100 mốc tròn 5 phút gần nhất (khoảng 8,33 giờ)
Chu kỳ 24 giờ: 100 ngày gần nhất (mỗi ngày một mốc)
Các chu kỳ khác áp dụng tương tự.

Ý nghĩa:

Nếu thời điểm truy vấn vượt ngoài phạm vi 100 mốc của chu kỳ đó (ví dụ dùng chu kỳ 5 phút để hỏi mốc 9:50 cách đây hơn ~8,33 giờ, hoặc ngày cách đây hơn 100 ngày trên chu kỳ ngày), API không thể trả về dữ liệu chính xác.
Khi đó hệ thống trả về mốc hợp lệ gần nhất trước thời điểm đó (ví dụ không có 9:50 thì trả 9:45) và không ép trả về tổng lũy kế 08:00 cùng ngày.

Vì sao thiết kế như vậy?
Để đảm bảo hiệu năng và khả năng truy vết lịch sử, chúng tôi chỉ giữ chi tiết 100 mốc gần nhất cho mỗi chu kỳ. Nếu cần dữ liệu xa hơn, hãy dùng chu kỳ lớn hơn (ví dụ dữ liệu theo ngày).

URL yêu cầu

Phương thức: POST
Đường dẫn: /open/v1/trade/getCoinTradeSnapshot

Điểm tín phí

Điểm tín phí mỗi lần gọi: 3

Điều kiện tiên quyết

Lấy vsTokenId

Trường hợp	Mô tả	Cách lấy
Đã có `vsTokenId`	Dùng id đã cache, không cần truy vấn lại	Tự động từ ngữ cảnh
Chưa có `vsTokenId`	Gọi `POST /vs-token/list`	Gọi API tiên quyết

Tham số yêu cầu

Tham số gửi trong body dạng JSON.

Tên tham số	Kiểu	Bắt buộc	Mô tả
vsTokenId	integer	Có	ID token
date	long	Có	Ngày chỉ định (mốc thời gian ms)

Trường phản hồi

Chỉ liệt kê cấu trúc trong đối tượng data:

Trường	Kiểu	Kiểu thực tế trả về	Mô tả
updateTime	integer	long	Thời điểm cập nhật (ms)
vsTokenId	integer	string	ID token
symbol	string	string	Ký hiệu
name	string	string	Tên
hasSpotGoods	boolean	boolean	Có dữ liệu giao ngay
spotMaxInflow	number	string	Tích lũy dòng vốn chủ lực (giao ngay)
spotGoodsList	array	array	Dữ liệu giao ngay
timeRange	string	string	Khung thời gian
timeParticleEnum	integer	integer	Độ mịn thống kê
tradeInflow	number	string	Dòng vào ròng (USD)
tradeAmount	number	string	Khối lượng (USD)
hasContract	boolean	boolean	Có dữ liệu hợp đồng
contractMaxInflow	number	string	Tích lũy dòng vốn chủ lực (hợp đồng)
contractList	array	array	Dữ liệu hợp đồng
timeRange	string	string	Khung thời gian
timeParticleEnum	integer	integer	Độ mịn thống kê
tradeInflow	number	string	Dòng vào ròng (USD)
tradeAmount	number	string	Khối lượng (USD)

Ý nghĩa nghiệp vụ

Trường	Ý nghĩa	Gợi ý
spotMaxInflow	Tích lũy chủ lực giao ngay	Dòng chủ lực = dòng vào ròng lớn nhất trên mọi cửa sổ giao ngay; tích lũy = chuỗi theo từng cửa sổ
contractMaxInflow	Tích lũy chủ lực hợp đồng	Dòng chủ lực = dòng vào ròng lớn nhất trên mọi cửa sổ giao ngay; tích lũy = chuỗi theo từng cửa sổ
date	Ngày snapshot	Mốc lịch sử truy vấn; bước tối thiểu 5 phút

Ví dụ yêu cầu

json

{
  "vsTokenId": 1,
  // ID token
  "date": 1773654600000
  // Ngày chỉ định (mốc thời gian)
}

Ví dụ 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
}'

Ví dụ 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}"

Ví dụ phản hồi thành công

json

{
  "code": 200,
  "message": "success",
  "data": {
    "updateTime": 1773654600000,
    // Thời điểm cập nhật
    "vsTokenId": "1",
    // ID token
    "symbol": "BTC",
    // Ký hiệu
    "name": "Bitcoin",
    // Tên
    "hasSpotGoods": true,
    // Có dữ liệu giao ngay
    "spotMaxInflow": "173206257.989364",
    // Tích lũy dòng vốn chủ lực (giao ngay)
    "spotGoodsList": [
      {
        "timeRange": "m5",
        // Khung thời gian
        "timeParticleEnum": 5,
        // Độ mịn thống kê
        "tradeInflow": "973669.0454980996",
        // Dòng vào ròng (USD)
        "tradeAmount": "4176136.897351299"
        // Khối lượng (USD)
      },
      {
        "timeRange": "m15",
        "timeParticleEnum": 15,
        "tradeInflow": "1531287.2033347988",
        "tradeAmount": "11822696.069185598"
      },
      {
        "timeRange": "m30",
        "timeParticleEnum": 30,
        "tradeInflow": "2668474.962980899",
        "tradeAmount": "25890934.620040294"
      }
      // ... bỏ qua thêm dòng
    ],
    "hasContract": true,
    // Có dữ liệu hợp đồng
    "contractMaxInflow": "5115857220.793299",
    // Tích lũy dòng vốn chủ lực (hợp đồng)
    "contractList": [
      {
        "timeRange": "m5",
        // Khung thời gian
        "timeParticleEnum": 5,
        // Độ mịn thống kê
        "tradeInflow": "7412113.461600001",
        // Dòng vào ròng (USD)
        "tradeAmount": "33097685.519799992"
        // Khối lượng (USD)
      },
      {
        "timeRange": "m15",
        "timeParticleEnum": 15,
        "tradeInflow": "5682104.7779",
        "tradeAmount": "69809754.7091"
      },
      {
        "timeRange": "m30",
        "timeParticleEnum": 30,
        "tradeInflow": "-6355722.267499994",
        "tradeAmount": "183233913.60549998"
      }
      // ... bỏ qua thêm dòng
    ]
  },
  "requestId": "xxx-xxx-xxx"
}

Lưu ý quan trọng

Phạm vi lưu trữ
- Mỗi chu kỳ chỉ giữ 100 mốc gần nhất.
- Truy vấn ngoài phạm vi (ví dụ quá 100 ngày trên chu kỳ ngày), hệ thống trả về mốc hợp lệ gần nhất trước đó.
Căn chỉnh thời gian
date được làm tròn xuống mốc 5 phút gần nhất (ví dụ 15:16 → 15:15).
Múi giờ
Mọi thời gian theo UTC+8.

Câu hỏi thường gặp

H: Tôi truy vấn 1/4 lúc 18:16, vì sao nhận 1/4 lúc 18:15?

Đ: Thời gian căn theo bội 5 phút (18:16 → 18:15). Nếu 18:15 còn trong phạm vi lưu trữ, mốc đó được trả về.

H: Truy vấn dữ liệu 100 ngày trước thì kết quả là gì?

Đ: Nếu mốc vượt ngoài 100 điểm của chu kỳ, hệ thống trả về mốc hợp lệ gần nhất trước thời điểm đó. Ví dụ chu kỳ 5 phút chỉ giữ ~8,33 giờ gần nhất; truy vấn sớm hơn sẽ trả về mốc tại ranh giới 8,33 giờ; chu kỳ 24 giờ giữ 100 ngày — ngày thứ 101 có thể trả rỗng.

H: Tại sao truy vấn 1/4 18:16 lại nhận 08:00 cùng ngày?

Đ: Nếu mốc nằm ngoài 100 điểm của chu kỳ, hệ thống trả mốc hợp lệ gần nhất trước đó, trong phạm vi còn lại của ngày đó.

Snapshot dòng vốn ​

Mô tả API ​

URL yêu cầu ​

Điểm tín phí ​

Điều kiện tiên quyết ​

Tham số yêu cầu ​

Trường phản hồi ​

Ý nghĩa nghiệp vụ ​

Ví dụ yêu cầu ​

Ví dụ cURL (Linux/macOS) ​

Ví dụ cURL (Windows CMD) ​

Ví dụ phản hồi thành công ​

Lưu ý quan trọng ​

Câu hỏi thường gặp ​