Xu hướng số dư

Mô tả API

Lấy dữ liệu số dư nắm giữ của địa chỉ chỉ định đối với token trên blockchain. Hỗ trợ truy vấn thay đổi số dư theo khoảng thời gian bằng cách chỉ định token, tên chuỗi và khoảng thời gian.

Tình huống sử dụng:

• Theo dõi thay đổi số dư nắm giữ của địa chỉ cụ thể
• Nhận diện hành vi tích lũy và giảm vị thế
• Giám sát động thái nắm giữ của địa chỉ cá voi

Tần suất cập nhật dữ liệu: Cập nhật một lần mỗi ngày

URL yêu cầu

• Phương thức: POST
• Đường dẫn: /open/v1/chain/trade/token/balanceTrend

Điểm tín phí

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

Đ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 vsTokenId đã cache, không cần truy vấn lại	Tự động lấy từ ngữ cảnh
Chưa có vsTokenId	Gọi API POST /vs-token/list để lấy	Gọi API tiên quyết

Lấy coinKey

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

Lấy address

Trường hợp	Mô tả	Cách lấy
Đã có address	Dùng địa chỉ nắm giữ đã biết	Người dùng nhập
Chưa có address	Gọi API POST /chain/trade/token/holdPage để truy vấn danh sách địa chỉ nắm giữ	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	long	Có	ID token
coinKey	string	Có	coinKey của token (chuỗi + địa chỉ hợp đồng); lấy từ chi tiết token
address	string	Có	Địa chỉ
startTime	long	Không	Thời gian bắt đầu (timestamp mili giây)
endTime	long	Có	Thời gian kết thúc (timestamp mili giây)

Trường phản hồi

Chỉ liệt kê cấu trúc trường của từng phần tử trong mảng data:

Trường	Kiểu	Kiểu thực tế trả về	Mô tả
vsTokenId	long	string	ID token
symbol	string	string	Ký hiệu token
name	string	string	Tên token
date	long	long	Thời gian (timestamp mili giây)
balance	number	string	Số dư
price	number	string	Giá token

Ý nghĩa nghiệp vụ

Trường	Ý nghĩa nghiệp vụ	Gợi ý sử dụng
balance	Số dư địa chỉ	Số lượng token địa chỉ nắm giữ; tăng liên tục cho thấy đang tích lũy

Ví dụ yêu cầu

{
    "vsTokenId": 1,                         // ID token
    "coinKey": "BTC_BTC",                    // coinKey của token (chuỗi + địa chỉ hợp đồng); lấy từ chi tiết token
    "address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6", // Địa chỉ
    "endTime": 1773479265534                  // Thời gian kết thúc
}

Ví dụ cURL (Linux/macOS)

curl --location --request POST 'http://${host}/api/open/v1/chain/trade/token/balanceTrend' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: xxxxx' \
--header 'X-TIMESTAMP: xxxxx' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: */*' \
--data-raw '{
    "vsTokenId": 1,
    "coinKey": "BTC_BTC",
    "address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6",
    "endTime": 1773479265534
}'

Ví dụ cURL (Windows CMD)

curl --location --request POST "http://${host}/api/open/v1/chain/trade/token/balanceTrend" ^
--header "Content-Type: application/json" ^
--header "X-API-KEY: xxxxx" ^
--header "X-TIMESTAMP: xxxxx" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: */*" ^
--data-raw "{    \"vsTokenId\": 1,    \"coinKey\": \"BTC_BTC\",    \"address\": \"3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6\",    \"endTime\": 1773479265534}"

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

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "vsTokenId": "1",           // ID token
            "symbol": "BTC",             // Ký hiệu token
            "name": "Bitcoin",           // Tên token
            "date": 1542038400000,       // Thời gian
            "balance": "0",              // Số dư
            "price": "6359.49"           // Giá token
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542124800000,
            "balance": "1",
            "price": "5738.35"
        },
        {
            "vsTokenId": "1",
            "symbol": "BTC",
            "name": "Bitcoin",
            "date": 1542211200000,
            "balance": "0",
            "price": "5648.03"
        }
        // ... thêm dữ liệu bị lược bỏ
    ],
    "requestId": "xxx-xxx-xxx"
}