Dùng chung cho mọi endpoint crypto get_alpha / get_exposure:
period — khung thời gian nến, {n}min / {n}h / {n}d ({n}m được đọc là phút). Các giá trị được ghi trong tài liệu là 5min, 15min, 1h, 4h, 8h, 1d; chỉ báo nào có mức tối thiểu thô hơn sẽ ghi rõ trong mục của nó. period bị thiếu hoặc không phân tích được sẽ trả về 403 {"error": "period is required"} (400 với unusual_movement và liquidation).
start_date / end_date — YYYY-MM-DD (UTC). end_date mặc định là hôm nay; start_date mặc định là end_date − 365 ngày. Khoảng dài hơn 365 ngày sẽ âm thầm bị cắt (start_date được dời về end_date − 365 ngày). Ngày sai định dạng không được kiểm tra và kết thúc bằng 500 — hãy luôn gửi YYYY-MM-DD.
symbol — hợp đồng vĩnh cửu Binance USDT-M, ví dụ BTCUSDT; BTC, btc, BTC/USDT, BTC-USDT cũng được chấp nhận (token trần sẽ được nối thêm USDT). Các endpoint get_symbols liệt kê những symbol được hỗ trợ.
Chỉ các nến đã đóng được trả về — nến cuối cùng đang hình thành bị loại bỏ.
Phản hồi là {"data": {"timestamp": [...], "alpha": [...], ...}} — các mảng song song, mỗi nến một phần tử. timestamp là giây Unix (UTC), nhãn của nến.
Với lịch sử dài hơn 365 ngày, hãy gửi mỗi năm một request rồi nối lại.
Object stat — được trả về bởi các chỉ báo có liệt kê nó trong mục của mình. Đây là một mô hình logistic khớp trên dữ liệu một năm qua của chỉ báo này đối với symbol, so với biến động giá 24h kế tiếp:
Trường
Kiểu
Mô tả
up_prob
float
Xác suất giá tăng trong 24h dựa trên giá trị chỉ báo mới nhất (0–1)
avg_up_return
float
Lợi suất 24h trung bình của các lần tăng trong quá khứ (số thập phân, 0.02 = +2%)
avg_down_return
float
Lợi suất 24h trung bình của các lần giảm trong quá khứ (số thập phân, giá trị âm)
data có key là token (BTC, 1INCH, …). Mỗi token ánh xạ tên chỉ báo → {param: value} ("-" khi chỉ báo không có tham số). "" = không đủ dữ liệu. Ngoài các chỉ báo còn có:
Key
Mô tả
statistics
up_prob (xác suất giá tăng trong 24h), exp_value (lợi suất kỳ vọng), avg_up_return, avg_down_return, return_ratio, is_data_sufficient
price
{"-": 70000} — giá hiện tại
price_change
{"15min": ..., "1h": ..., "24h": ...} — % thay đổi
market_cap
{"-": 1234567890} — vốn hóa thị trường tính bằng USD
market_cap_percentile
{"-": 85.3} — phân vị trong số tất cả coin được niêm yết
funding_rate
{"binance": -0.01, ...} — theo từng sàn
oi_imbalance
{"-": 0.12} — mất cân bằng OI (chi tiết đầy đủ: /oi_imbalance/get_overview_data)
fields — mỗi chỉ báo một mục: id, name (key dùng trong data), param (tên tham số hoặc null), name_en, name_zh.
note — key là id chỉ báo: một danh sách các dải giá trị {min, max, note: {en, zh}, direction: {en, zh}, color, background_color} dùng để gắn nhãn cho một giá trị (ví dụ max: -3 → "Overly Bearish").
Lỗi
Chỉ có các lỗi dùng chung.
Ghi chú
Hãy dùng endpoint này trước tiên cho mọi bộ lọc hoặc bảng xếp hạng nhiều coin — một request bao phủ mọi symbol.
Luôn kiểm tra statistics.is_data_sufficient trước khi dùng statistics.
Luôn lấy dữ liệu mới; đừng dùng lại phản hồi trước đó.
2020-01-01, hoặc ngày niêm yết của hợp đồng nếu muộn hơn
Tần suất cập nhật
Trong khoảng một phút sau mỗi lần đóng nến
Phạm vi. Mọi hợp đồng vĩnh cửu Binance USDⓈ-M có symbol kết thúc bằng USDT — 740 hợp đồng tính đến tháng 10 năm 2026, gồm cả cổ phiếu token hóa, hàng hóa và các hợp đồng vĩnh cửu USDT khác thuộc TradFi. Cả 740 hợp đồng đều có toàn bộ lịch sử 1 phút được lưu phía máy chủ, từ 2020-01-01 hoặc từ ngày niêm yết. Hợp đồng vĩnh cửu mới niêm yết có thể truy vấn được sau khoảng 5–10 phút kể từ khi niêm yết.
Không hỗ trợ: các hợp đồng định giá bằng USDC, USD1, U hoặc BTC (ví dụ BTCUSDC, ETHBTC) và hợp đồng giao hàng theo quý — những hợp đồng này trả về lỗi 400 unknown symbol or no data bên dưới. Hợp đồng đã hủy niêm yết không được bảo đảm: có thể trả về phần lịch sử còn được lưu hoặc chính 400 đó (những hợp đồng hủy niêm yết trước tháng 10 năm 2026 không có lịch sử 1min–4min).
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
symbol
string · queryBắt buộc
Hợp đồng vĩnh cửu USDT Binance USDⓈ-M. Token trần sẽ được nối thêm USDT; token trần chỉ tồn tại dưới dạng có tiền tố hệ số nhân sẽ được quy về dạng đó (PEPE → 1000PEPEUSDT)
BTCUSDT; cũng chấp nhận BTC, btc, BTC/USDT, BTC-USDT
period
string · queryBắt buộc
Khung thời gian nến. Chấp nhận mọi khung tính bằng số phút nguyên, không chỉ các ví dụ được liệt kê
end_date − 365 ngày (period ≥ 5min); end_date − 30 ngày (period < 5min)
end_date
string · query
Ngày cuối cùng, bao gồm cả ngày đó (các nến đến hết ngày UTC đó)
YYYY-MM-DD (UTC)
hiện tại
Cửa sổ mỗi request: period ≥ 5min → tối đa 365 ngày; khoảng dài hơn sẽ âm thầm bị cắt (start_date được dời về end_date − 365 ngày, không báo lỗi). Period < 5min → tối đa 30 ngày; khoảng dài hơn trả về 400.
Một mảng JSON trần (không bọc trong {"data": ...}), tăng dần theo thời gian.
Trường
Kiểu
Đơn vị
Mô tả
time
float
Giây Unix (UTC)
Thời điểm mở nến
open / high / low / close
float
đồng định giá (USDT)
Giá
volume
float | null
tài sản cơ sở
Khối lượng giao dịch; null khi nguồn không có khối lượng cho nến đó
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
403
{"error": "symbol is required"}
Thiếu symbol
403
{"error": "period is required"}
Thiếu periodhoặc không phân tích được
400
{"error": "minimum supported period is 1min"}
period dưới một phút
400
{"error": "periods below 5min must be a whole number of minutes"}
e.g. 90s
400
{"error": "date range exceeds max 30 days for periods below 5min"}
Period < 5min và khoảng > 30 ngày
400
{"error": "invalid date format, expected YYYY-MM-DD"}
start_date / end_date sai định dạng
400
{"error": "unknown symbol or no data: <symbol>"}
Symbol không được hỗ trợ (xem Không hỗ trợ) hoặc không phải hợp đồng có thật, ví dụ BTCUSDC, ETHBTC, lỗi gõ nhầm. <symbol> trả lại giá trị bạn đã gửi. Không phải lỗi tạm thời — đừng thử lại
Ghi chú
Cửa sổ nằm hoàn toàn trước ngày niêm yết của một hợp đồng được hỗ trợ trả về 200 kèm [], không phải lỗi.
Ở 1min, mọi nến được trả về đều đã đóng. Khung dài hơn có thể kết thúc bằng một nến chưa hoàn chỉnh khi end_date là hôm nay — nến đó được dựng từ các nến đã đóng tính đến lúc đó (lúc 07:09 UTC, nến 1h07:00 chứa 07:00–07:05); hãy bỏ nó nếu bạn chỉ cần nến đã đóng.
Với lịch sử dài hơn một cửa sổ, hãy gửi mỗi cửa sổ một request rồi nối lại (ví dụ 3 năm 5min = 3 request; 1 năm 1min = 13 request, mỗi request ≤30 ngày).
Cả 740 hợp đồng vĩnh cửu USDT đều có toàn bộ lịch sử 1 phút trên đĩa, nên request sâu được trả lời từ dữ liệu đã lưu — không có lần lấy đầu tiên chậm.
Ngày bắt đầu áp dụng cho mọi khung thời gian, kể cả 1min.
Nến 1 phút đã đóng mới nhất thường có trong vòng một phút kế tiếp; trong một số ít trường hợp suy giảm, các nến mới nhất có thể trễ khoảng 5–10 phút.
Cache máy chủ: 30 giây (1min), 300 giây (1h / 4h / 1d), 60 giây (mọi khung khác); chỉ 5 giây khi nến đã đóng mới nhất chưa về.
Không có symbol: alpha là một chuỗi duy nhất cho toàn thị trường, không phải theo từng coin. BTCUSDT chỉ được dùng nội bộ để căn nến; nó không được trả về và không làm thay đổi alpha. Xem Quy ước chỉ báo crypto.
{"data": {<condition_id>: {...}}}, key là id điều kiện (key chuỗi JSON, ví dụ "12"; hãy gửi lại dưới dạng số nguyên condition_id). Chỉ gồm các điều kiện của chính tài khoản này.
Trường
Kiểu
Mô tả
filters
object[]
Các bộ lọc của điều kiện, kết hợp bằng AND: indicator_id (int), indicator_name ({"en", "zh"}), param (string; "-" = mặc định của chỉ báo), operator_id (int), operator_symbol (string, ví dụ >), value (ngưỡng)
note
string
Tên bạn đã đặt cho điều kiện khi lưu
name_en / name_zh
string | null
Chỉ có ở điều kiện chính thức / cộng đồng; với điều kiện của riêng bạn, giá trị sẽ rỗng hoặc null, hãy đọc note thay thế
description_en / description_zh
string | null
Chỉ có ở điều kiện chính thức / cộng đồng; có thể rỗng hoặc null
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
403
{"error": "unsupported api feature"}
Key không gắn với tài khoản người dùng
Ghi chú
Mỗi request đọc trực tiếp các điều kiện đã lưu của tài khoản.
Mỗi chỉ báo lọc khác nhau một mục, theo thứ tự bộ lọc: en / zh (tên hiển thị, kèm tham số trong ngoặc đơn nếu có), name (key chỉ báo), type, url; thêm value_format, value_decimals, polarity khi chỉ báo có định nghĩa
symbols
object[]
Các token thỏa mãn mọi bộ lọc
symbols[].symbol
string
Token không kèm USDT (ví dụ BTC)
symbols[].id
int
Id token (0 khi không xác định)
symbols[].user_selected
bool
Token nằm trong danh sách theo dõi của tài khoản
symbols[].price
float
Giá mới nhất tính bằng USDT (cùng feed với /price; 0 khi không có)
symbols[].24h_chg
float
Thay đổi 24h dưới dạng tỷ lệ (0.025 = +2.5%)
symbols[].alphas
float[]
Giá trị của token cho từng chỉ báo lọc, song song với alpha_names
symbols[].alpha_notes
object[]
Theo từng chỉ báo: indicator_id, color, direction, note (thêm background_color khi có quy tắc khớp; color là null và các chuỗi rỗng khi không có quy tắc nào khớp)
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "Missing parameter: condition_id is required."}
Thiếu
400
{"error": "Invalid parameter: condition_id must be an integer."}
Không phải số nguyên
404
{"error": "Invalid condition_id: <id> not found for user."}
{"data": {"alpha": {<sector>: {"data": [...], "name_en": ..., "name_zh": ...}}, "timestamp": [...]}}. timestamp nằm cạnh alpha ở cấp cao nhất của data, không nằm trong từng ngành; đó là trục thời gian chung cho mọi chuỗi ngành.
Trường
Kiểu
Mô tả
timestamp
float[]
Giây Unix (UTC), mỗi điểm một giá trị — 366 điểm theo ngày trong phản hồi quan sát được
alpha.<sector>.data
float[]
Chuỗi của ngành, cùng độ dài và thứ tự với timestamp (366); phần tử đầu tiên là 0.0
alpha.<sector>.name_en / name_zh
string
Tên hiển thị của ngành
Lỗi
Chỉ có các lỗi dùng chung.
Ghi chú
Chuỗi là một cửa sổ theo ngày của một năm gần nhất (366 điểm theo ngày), và mọi ngành đều bắt đầu ở 0.0. Không có tham số nào, và mỗi lần dựng lại chỉ tính lại 365 ngày gần nhất, nên không tồn tại lịch sử dài hơn.
Được dựng lại bởi một job theo lịch, các lần dựng lại cách nhau 50–60 phút; phục vụ từ đầu ra của job, không có thêm cache máy chủ.
Z-score của thay đổi OI (hoặc khối lượng) cộng dồn theo timeframe so với trung bình 30 ngày của nó
stat
object
Xem Object stat
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
403
{"error": "symbol is required"} / {"error": "period is required"}
Thiếu tham số
403
{"error": "Invalid score_type"}
score_type không được phép
Ghi chú
Chỉ bao phủ Binance — hợp đồng mở và khối lượng của hợp đồng vĩnh cửu USDT-M.
timeframe không được kiểm tra phía máy chủ. Đã thử một giá trị ngoài danh sách, 2h, và nó trả về 200 kèm dữ liệu. Đó chỉ là một lần quan sát — không chứng minh rằng mọi {n}h đều hoạt động. Hãy dùng các giá trị được liệt kê, trừ khi bạn tự xác minh giá trị mình cần.
2021-12-01 là nến 1d đầu tiên của BTCUSDT; các symbol khác có thể bắt đầu muộn hơn.
black = squeeze đang bật (Bollinger Bands nằm trong Keltner Channels), grey = squeeze tắt
stat
object
Xem Object stat
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
403
{"error": "symbol is required"}
Thiếu tham số
Ghi chú
Chỉ bao phủ Binance — giá hợp đồng vĩnh cửu USDT-M.
Chuỗi có phần đệm: các dòng BTCUSDT có từ 2020-01-01, nhưng alpha là 0.0 cho đến 2020-02-09. Request bắt đầu sớm hơn ngày Dữ liệu từ sẽ trả về các dòng đệm đó — chúng là phần lấp chỗ trống, không phải tín hiệu. Hãy bỏ các số không ở đầu, hoặc bắt đầu từ ngày Dữ liệu từ.
2020-02-09 là alpha khác không đầu tiên của BTCUSDT; các symbol khác có thể bắt đầu muộn hơn.
Không có symbol: alpha là một chuỗi duy nhất cho toàn thị trường, không phải theo từng coin. BTCUSDT chỉ được dùng nội bộ để căn nến; nó không được trả về và không làm thay đổi alpha. Xem Quy ước chỉ báo crypto.
{"data": {"timestamp": [...], "alpha": [...]}}. Không có stat.
Trường
Kiểu
Mô tả
timestamp
float[]
Giây Unix (UTC)
alpha
float[]
Mức phơi nhiễm ròng của các trader hàng đầu Blave (top 10% theo tài sản tài khoản) — trung vị, trên các trader đó, của vị thế danh nghĩa ròng ÷ tài sản của chính từng trader, ×100 (dương = long ròng). Là tỷ lệ thô, không phải z-score
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
403
{"error": "period is required"}
Thiếu tham số
Ghi chú
Một chuỗi toàn thị trường bao phủ mọi coin mà các trader này nắm giữ; không có chiều symbol.
(thanh lý short − thanh lý long, tính bằng coin) cộng dồn theo timeframe ÷ độ lệch chuẩn cuốn chiếu 30 ngày của nó; không trừ trung bình. > 0 = short bị thanh lý nhiều hơn long, < 0 = long nhiều hơn
stat
object
Xem Object stat
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "symbol is required"} / {"error": "period is required"}
Thiếu tham số
Ghi chú
Chuỗi có phần đệm: các dòng BTCUSDT có từ 2020-01-01, nhưng alpha là 0.0 cho đến 2023-01-01. Request bắt đầu sớm hơn ngày Dữ liệu từ sẽ trả về các dòng đệm đó — chúng là phần lấp chỗ trống, không phải tín hiệu. Hãy bỏ các số không ở đầu, hoặc bắt đầu từ ngày Dữ liệu từ. Các symbol ngoài BTC/ETH còn chuyển sang khác không muộn hơn nữa, nên hãy kiểm tra theo từng symbol.
Phân bổ ước tính hợp đồng mở Binance vào từng vùng giá (ước tính của mô hình, không phải vị thế thật)
cumsum
float[]
USD
Mức phơi nhiễm thanh lý lũy kế qua các vùng giá
liquidation
object
USD
{"24h": {"buy_liq": [...], "sell_liq": [...]}} — các lệnh thanh lý cưỡng chế thực tế trên Binance trong 24 giờ qua theo từng vùng giá, mỗi giá trị được chia cho giả định cố định 0.3 về thị phần Binance: buy_liq = thanh lý short, sell_liq = thanh lý long
Mức phơi nhiễm thanh lý ước tính mới trong 0–1 giờ qua, theo từng vùng giá: chênh lệch dương giữa các snapshot bản đồ của mô hình, không phải thanh lý thực tế
hist_1_8h
float[]
USD
1–8 giờ qua
hist_8_24h
float[]
USD
8–24 giờ qua
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "symbol is required"}
Thiếu tham số
Ghi chú
Mỗi request dựng lại bản đồ hiện tại (cache máy chủ 5 giây) và so sánh với các snapshot bản đồ đã lưu từ khoảng 1 giờ, 8 giờ và 24 giờ trước. Snapshot được lưu mỗi 30 phút cho mọi symbol, cộng thêm ở mỗi request bản đồ.
Các lệnh thanh lý cưỡng chế của một coin trên mọi feed sàn mà Blave thu thập: bốn cửa sổ cuốn chiếu kèm phân tách theo từng sàn, một chuỗi theo giờ gồm 24 điểm, và ghi chú về độ phủ của từng feed. Đây là dòng thanh lý thực tế (giống đầu vào của get_alpha), không phải ước tính của mô hình đằng sau get_map.
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
symbol
string · queryBắt buộc
Coin. Hậu tố đồng định giá bị loại bỏ; symbol trong phản hồi là tên coin đã chuẩn hóa
Cộng trên các sàn; long = vị thế long bị thanh lý (giá giảm), short = vị thế short bị thanh lý (giá tăng)
windows.<h>.long_pct / short_pct
float / null
tỷ lệ 0–1
Tỷ trọng trong tổng của cửa sổ; null khi tổng của cửa sổ bằng 0
windows.<h>.covered_hours
float
h
Số giờ của cửa sổ thực sự có bucket (< h ngay sau khi collector khởi động lại)
windows.<h>.by_exchange
object
USD
{exchange: {total_liq_usd, long_liq_usd, short_liq_usd}}. Sàn không có sự kiện nào trong cửa sổ thì không có key — hãy đọc exchanges[] để phân biệt "feed còn sống, coin này yên ắng" với "không có feed"
exchanges[]
object[]
—
Mỗi feed một dòng (hiện có sáu feed, có mặt kể cả khi không có sự kiện), sắp xếp giảm dần theo tổng 24 giờ, rồi theo thứ tự danh sách
exchanges[].exchange
string
—
binance, bybit, gate, okx, htx, bitfinex
exchanges[].listed
bool / null
—
Sàn đó có niêm yết hợp đồng vĩnh cửu ký quỹ bằng USDT cho coin này hay không; null khi không lấy được danh sách hợp đồng (Bitfinex luôn là null)
exchanges[].last_event_at
string / null
ISO 8601 UTC
Bucket mới nhất nhận được từ feed đó (bất kỳ coin nào); null nếu chưa từng nhận được
exchanges[].price_basis
string
—
Giá dùng để quy đổi sang USD: trade_avg, bankruptcy, unverified
exchanges[].coverage
string
—
Mức độ đầy đủ của feed: full, full_unstated, sampled_1s, aggregated_1s, sampled_undisclosed
exchanges[].time_basis
string
—
event — chia bucket theo timestamp của chính sự kiện
detail_complete
bool
—
false khi coin có thể đã bị cắt khỏi danh sách chi tiết đầy đủ theo từng bucket (các feed giữ top 100 coin cho mỗi bucket 5 phút): khi đó windows có thể đếm thiếu. Các coin thuộc top 50 gần như luôn là true
series.bucket_seconds
int
s
Luôn là 3600
series.points
object[]
—
Luôn có 24 mục, cũ nhất → mới nhất, theo giờ đồng hồ; mục cuối là giờ hiện tại tính đến updated_at (snapshot được dựng lại mỗi 5 phút, nên có thể chậm hơn request vài phút). Mỗi mục là {ts, long_liq_usd, short_liq_usd}; các giờ không có sự kiện là 0, không bao giờ bị thiếu
windows["24"] là cùng khung cuốn chiếu với ma trận sàn, nên cùng một coin hiển thị cùng con số 24 giờ ở đó. series tính theo giờ đồng hồ, nên Σ points ≠ windows["24"] là có chủ đích: lấy tổng từ windows, lấy diễn biến theo thời gian từ series.
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "symbol is required"}
symbol bị thiếu, để trống, dài hơn 32 ký tự, hoặc không còn gì sau khi loại bỏ hậu tố đồng định giá (ví dụ symbol=USDT)
404
{"error": "<SYMBOL> is not a collected symbol"}
Không sàn nào niêm yết coin này và không feed nào ghi nhận nó trong 24 giờ qua — đây là câu trả lời, không phải lỗi tạm thời
503
{"error": "liquidation data unavailable"}
Các bucket upstream không phản hồi — thử lại sau; không bao giờ đọc thành "0 lệnh thanh lý"
Ghi chú
Bao phủ các feed thanh lý của Binance, Bybit, Gate.io, OKX, HTX và Bitfinex.
Chỉ có snapshot: không có start_date / end_date, và không có gì cũ hơn 24 giờ. Để lấy lịch sử, dùng get_alpha (mức mất cân bằng long/short đã chuẩn hóa, không phải số tiền USD).
Cách xử lý symbol khác với các endpoint thanh lý còn lại: get_alpha / get_map cần dạng hợp đồng vĩnh cửu của Binance (BTCUSDT); ở đây BTC và BTCUSDT là cùng một coin.
Cache máy chủ: 5 phút.
Giá trị danh nghĩa USD được quy đổi tại thời điểm thu thập, nên có thể cộng các sàn với nhau.
Cửa sổ cuốn chiếu, căn theo 5 phút (mặc định 24 giờ gần nhất)
Tần suất cập nhật
Mỗi 5 phút
Các lệnh thanh lý cưỡng chế của toàn thị trường, tổng hợp theo từng sàn và dưới dạng ma trận coin × sàn — bản toàn thị trường đi kèm với /liquidation/get_coin. Cùng khung cuốn chiếu căn theo 5 phút, nên tổng 24 giờ của một coin là cùng một con số ở cả hai.
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
hours
int · query
Độ dài cửa sổ. Ngoài phạm vi → 400 (không bị cắt về giới hạn); giá trị không phải số nguyên sẽ âm thầm quay về mặc định
1–168
24
top_n
int · query
Số coin được liệt kê riêng; phần còn lại vào others. Cùng quy tắc về phạm vi / giá trị không nguyên với hours
Mỗi feed một dòng, sắp xếp giảm dần theo tổng: exchange, total_liq_usd, long_liq_usd, short_liq_usd, long_pct, short_pct, events, last_event_at. Mọi feed luôn được liệt kê: số tiền null = không nhận được dữ liệu từ feed đó trong cửa sổ (xếp cuối), 0.0 = có kết nối nhưng không có thanh lý
exchanges[].price_basis / .coverage / .time_basis
string
—
Mức độ so sánh được của dòng đó: trade_avg / bankruptcy / unverified; full, full_unstated, sampled_1s, aggregated_1s, sampled_undisclosed; event. Hãy giữ các trường này khi công bố lại số liệu — feed lấy mẫu không phải là feed đầy đủ
coins[]
object[]
—
top_n coin đứng đầu theo tổng trên các sàn: token, token_id (0 khi symbol không có id token), total_liq_usd, long_liq_usd, short_liq_usd, by_exchange{name: {total/long/short_liq_usd}}. by_exchange là dạng thưa — feed không có gì cho coin đó thì không có key; hãy đọc là 0 khi tổng exchanges[] của feed đó không phải null
others
object
—
Mọi thứ bị top_n cắt đi, cùng các trường cộng thêm coin_count, để coins[] + others cộng lại bằng tổng của từng sàn
Số giờ của cửa sổ thực sự có bucket (< hours ngay sau khi collector khởi động lại)
buckets
int
—
Số bucket 5 phút được tổng hợp
window_hours / window_start / window_end
int / string
giờ / ISO 8601 UTC
Cửa sổ như máy chủ đã xác định
updated_at
string
ISO 8601 UTC
Bucket mới nhất được dùng
long_liq_usd = vị thế long bị thanh lý (giá giảm); short_liq_usd = vị thế short bị thanh lý (giá tăng).
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "hours must be between 1 and 168"} / {"error": "top_n must be between 1 and 50"}
Tham số ngoài phạm vi
Ghi chú
Bao phủ các feed thanh lý của Binance, Bybit, Gate.io, OKX, HTX và Bitfinex.
Hoàn toàn không có dữ liệu (các feed ngừng hoạt động, hoặc không kết nối được nguồn dữ liệu) vẫn là 200 với cùng cấu trúc, mọi số tiền là null, buckets: 0 — không bao giờ là một bảng toàn số không. Hãy kiểm tra total.total_liq_usd trước khi dùng số liệu.
Chỉ có tổng — không có chuỗi thời gian. Diễn biến theo giờ của một coin là /liquidation/get_coin; tín hiệu đã chuẩn hóa có lịch sử dài là /liquidation/get_alpha.
Cửa sổ là cuốn chiếu, không phải ngày theo lịch, và là cùng khung mà /liquidation/get_coin dùng cho windows["24"].
Cache máy chủ: 5 phút.
Giá trị danh nghĩa USD được quy đổi tại thời điểm thu thập, nên có thể cộng các sàn với nhau.
Mọi coin được thu thập × mọi nguồn tỷ lệ long/short, tại thời điểm hiện tại. Mười nguồn: Binance, OKX và Gate.io mỗi sàn công bố ba loại — tất cả tài khoản, tài khoản của top trader, vị thế của top trader — còn Bybit chỉ công bố theo tài khoản. Các dòng được sắp xếp theo giá trị danh nghĩa hợp đồng mở trên Binance. Chỉ liệt kê những coin ánh xạ được vào một mục trong danh sách token của Blave; phản hồi khi dùng API key là bảng đầy đủ (full: true), còn bản studio ẩn danh chỉ có các dòng thuộc whitelist 30 coin của nó.
Tham số
Không có.
Ví dụ
Python
data = requests.get(f"{BASE_URL}/long_short_ratio/get_table", headers=headers, timeout=30).json()["data"]keys = [s["key"] for s in data["sources"] ifnot s["stale"]]btc = next(c for c in data["coins"] if c["token"] == "BTC")print({k: btc[k] for k in keys if btc[k] is notNone})#Live capture 2026-09-22 via the anonymous studio twin (/studio/charts/long_short_ratio/table) —#same inner shape; the API-key response wraps it in "data" and has full: true with every row.#{"coins": [{"binance_account": 0.8818, "binance_top_account": 1.0149, "binance_top_position": 2.2666,#"bybit_account": 1.0375, "gate_account": 0.7294, "gate_top_account": 0.6944,#"gate_top_position": 1.6436, "okx_account": 0.9084, "okx_top_account": 0.8655,#"okx_top_position": 1.0222, "token": "BTC", "token_id": 1}, ...],#"sources": [{"exchange": "binance", "key": "binance_account", "last_at": "2026-09-22T05:50:00+00:00",#"stale": false, "type": "account"}, ...,#{"exchange": "bybit", "key": "bybit_account", "last_at": "2026-09-22T05:50:00+00:00",#"stale": false, "type": "account"}],#"summary": {"binance_long_majority": 436, "binance_tokens": 509},#"tokens_shown": 30, "tokens_total": 611, "full": false, "updated_at": "2026-09-22T05:50:00+00:00"}
Thời điểm bắt đầu thu thập (bucket đầu tiên được lưu, đo trên BTC ngày 2026-09-22)
Hiện mọi nguồn đều đã lâu hơn 7 ngày mà bộ dữ liệu này phục vụ, nên không nguồn nào giới hạn truy vấn — các ngày này chỉ quan trọng khi bạn được báo rằng một nguồn "không có lịch sử".
Mẫu mới nhất của feed đó đã cũ hơn 1 giờ (so với hiện tại). updated_at ở cấp cao nhất là của nguồn mới nhất và không nói lên điều gì về từng nguồn riêng lẻ — hãy đánh giá một nguồn bằng last_at / stale của chính nó
summary.binance_tokens / .binance_long_majority
int
—
Số coin có tỷ lệ tài khoản Binance / trong số đó, bao nhiêu coin trên 1. Tính trên toàn bộ bảng, không phải trên các dòng được hiển thị
tokens_shown / tokens_total
int
—
Số dòng được trả về / số dòng trong bảng. Bằng nhau khi dùng API key
full
bool
—
true khi dùng API key; false ở bản studio ẩn danh
updated_at
string
ISO 8601 UTC
Bucket mới nhất trên các nguồn
"Top trader" là một nhóm đối tượng khác nhau ở mỗi sàn — đừng so sánh mức giá trị giữa các sàn.
Sàn giao dịch
Ai được tính là top trader (nguyên văn chính thức)
Binance
"the top 20% users with the highest margin balance"
OKX
"the top 5% of traders with the largest open position value"
Gate.io
Chưa từng công bố — tài liệu chỉ nêu tên các trường
Vì vậy binance_top_account cao hơn okx_top_account không nói lên trader lớn của sàn nào đang long nhiều hơn. Thay vào đó, hãy so sánh mỗi nguồn với lịch sử của chính nó.
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
503
{"error": "long short ratio data unavailable"}
Không có snapshot mới — thử lại sau; không bao giờ đọc thành thị trường trống
Ghi chú
Đây là lát cắt, không phải lịch sử. Để lấy chuỗi dữ liệu, dùng /long_short_ratio/get_coin (7 ngày) — bộ dữ liệu này không có endpoint lịch sử dài.
Độ chi tiết là 5 phút, nhưng mỗi nguồn công bố theo nhịp riêng — đừng mô tả là "cập nhật mỗi 5 phút".
Snapshot là bucket mới nhất mà mỗi nguồn đã công bố; bucket của Gate.io và OKX về chậm khoảng 10 phút.
Một coin, cả mười nguồn: giá trị 5 phút mới nhất của từng nguồn, chuỗi theo giờ trong 7 ngày của từng nguồn, và giá đóng cửa hợp đồng vĩnh cửu Binance trên cùng khung thời gian.
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
symbol
string · queryBắt buộc
Coin. Hậu tố đồng định giá bị loại bỏ; symbol trong phản hồi là tên coin đã chuẩn hóa
BTC, BTCUSDT, btc (≤ 32 ký tự)
Ví dụ
Python
params = {"symbol": "BTC"}data = requests.get(f"{BASE_URL}/long_short_ratio/get_coin", headers=headers, params=params, timeout=30).json()["data"]latest = data["latest"]["binance_top_position"] # null when Binance does not list the coinif latest is notNone:r = latest["value"]print("top-trader long share:", round(r / (1 + r), 4))#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"latest": {"binance_account": {"ts": "2026-09-22T05:50:00+00:00", "value": 0.8818},#"binance_top_account": {"ts": "2026-09-22T05:50:00+00:00", "value": 1.0149}, ... 10 keys},#"series": {"bucket_seconds": 3600, "days": 7, "price_symbol": "BTCUSDT", "price_multiplier": 1,#"provisional_from": 1790053200,#"timestamp": [..., 1790049600, 1790053200],#"binance_account": [..., 0.8699, 0.8818], "price": [..., 85424.7, 85495.8], ... one array per source},#"sources": [{"exchange": "binance", "key": "binance_account", "last_at": "2026-09-22T05:50:00+00:00",#"listed": true, "stale": false, "type": "account"}, ... 10 rows],#"symbol": "BTC", "token_id": 1, "updated_at": "2026-09-22T05:50:00+00:00"}
{value, ts} — mẫu 5 phút mới nhất của nguồn đó; null khi nguồn không niêm yết coin
series.bucket_seconds / .days
int
s / d
3600 / 7
series.timestamp
int[]
giây epoch
168 ô, cũ nhất → mới nhất, mỗi giờ một ô
series.<source key>
float[] / null
tỷ lệ
Mẫu cuối cùng của mỗi giờ; null với giờ không có mẫu. Cả trường là một null duy nhất (không phải mảng) với nguồn không niêm yết coin
series.price
float[] / null
USD
Giá đóng cửa hợp đồng vĩnh cửu Binance trên cùng khung thời gian. Là một null duy nhất (khi đó price_symbol / price_multiplier cũng là null) khi coin không có hợp đồng vĩnh cửu trên Binance
series.price_symbol / .price_multiplier
string / int
—
Giá lấy từ hợp đồng vĩnh cửu nào và hệ số nhân hợp đồng của nó (1000PEPEUSDT → 1000; price ÷ price_multiplier = giá mỗi coin)
series.provisional_from
int / null
giây epoch
Ô đầu tiên vẫn còn có thể thay đổi (các nguồn chốt số chậm đến ~10 phút); null khi không nguồn nào có dữ liệu
sources[]
object[]
—
Danh sách đầy đủ, cùng các trường với bảng cộng thêm listed
sources[].listed
bool
—
false = sàn đó không có feed này cho coin; các mục latest và series của nó là null
symbol / token_id / updated_at
—
—
Như trong bảng
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "symbol is required"}
symbol bị thiếu, để trống, dài quá 32 ký tự, hoặc không còn gì sau khi loại bỏ hậu tố đồng định giá
404
{"error": "<SYMBOL> is not a collected symbol"}
Không nguồn nào thu thập coin này — đây là câu trả lời, không phải lỗi tạm thời
503
{"error": "long short ratio data unavailable"}
Không đọc được một nguồn có niêm yết. null chỉ có nghĩa duy nhất là "sàn đó không niêm yết coin này"
Ghi chú
Bao phủ các feed tỷ lệ long/short của Binance, OKX, Gate.io và Bybit.
Lưu ý về "top trader" giữa các sàn ở /long_short_ratio/get_table cũng áp dụng tại đây.
7 ngày là toàn bộ lịch sử mà endpoint này phục vụ; không có start_date / end_date.
Về "bản studio ẩn danh" trong mọi ví dụ của các endpoint dữ liệu thô trên trang này: các trang studio (/studio/charts/...) phục vụ cùng payload từ cùng bộ dựng mà không cần key, và các ví dụ này được lấy từ đó. Chúng không thay thế cho các endpoint dùng API key: các bảng bị cắt còn 30 coin (full: false), và coin nằm ngoài whitelist của studio sẽ nhận 403 {"error_code": "ERR001", ..., "anon_whitelist": [...]} thay vì dữ liệu. Các endpoint dùng API key được mô tả ở đây không có whitelist và không cắt dòng.
Mọi coin được thu thập × năm sàn, tính bằng giá trị danh nghĩa USD. Cơ sở: chỉ hợp đồng vĩnh cửu ký quỹ bằng USDT, giá trị danh nghĩa USD, một phía. Sàn báo cáo cả hai phía sẽ được chia đôi (exchanges[].side_factor, Gate.io = 0.5). Vì mọi giá trị đều đã là giá trị danh nghĩa USD, các hợp đồng có hệ số nhân (1000PEPE và tương tự) cộng được giữa các sàn mà không cần quy đổi lại.
Tham số
Không có.
Ví dụ
Python
data = requests.get(f"{BASE_URL}/oi_imbalance/get_table", headers=headers, timeout=30).json()["data"]crowded = sorted((c for c in data["coins"] if c["oi_mcap"] is notNone), key=lambda c: -c["oi_mcap"])[:10]print(data["total"]["oi"], [(c["token"], round(c["oi_mcap"], 4)) for c in crowded])#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"coins": [{"token": "BTC", "token_id": 1, "oi_total": 18645450917.48, "chg_1h": -0.001775,#"chg_4h": -0.001046, "chg_24h": 0.128725, "market_cap": 1629947967503.241, "oi_mcap": 0.011439,#"by_exchange": {"binance": {"oi": 9417422808.02, "chg_1h": 2e-05, "chg_4h": 0.010203, "chg_24h": 0.067527},#"bingx": {"oi": 1328003926.8, ...},#"bybit": {"oi": 2569097877.96, "chg_1h": -0.008636, "chg_4h": -0.030159, "chg_24h": null},#"gate": {...}, "okx": {"oi": 2575361192.92, ..., "chg_24h": null}}}, ...],#"exchanges": [{"key": "binance", "oi": 24712717530.01, "side_factor": 1.0, "since": null, "full_7d": true,#"last_at": "2026-09-22T05:25:00+00:00", "stale": false}, ... 5 rows],#"total": {"oi": 47428938620.05, "chg_1h": -0.008919, "chg_4h": -0.010508, "chg_24h": 0.073881,#"n_exchanges": 5, "n_full_7d": 3},#"summary": {"oi_mcap_leader": "SAGA", "oi_mcap_leader_value": 1.718336},#"tokens_shown": 30, "tokens_total": 622, "full": false, "updated_at": "2026-09-22T05:30:00+00:00"}
Thời điểm bắt đầu thu thập (bucket đầu tiên được lưu, đo trên BTC ngày 2026-09-22)
Sàn giao dịch
Thu thập từ
binance
2021-12-01
bingx
2025-04-15
gate
2026-08-12
okx
2026-09-21
bybit
2026-09-21
OKX và Bybit là lý do n_full_7d bằng 3 trên 5 và chg_24h của chúng vẫn là null vào ngày 2026-09-22 — hãy đọc exchanges[].since / full_7d thay vì các ngày này, vốn sẽ lỗi thời.
Thay đổi dạng thập phân (0.0675 = +6.75 %). Mỗi cửa sổ chỉ tính các sàn có mốc so sánh tại thời điểm bắt đầu của cửa sổ đó, tử số và mẫu số trên cùng một tập sàn; null khi không sàn nào có
coins[].market_cap
float / null
USD
Vốn hóa thị trường; null khi không có giá trị dùng được
coins[].oi_mcap
float / null
tỷ lệ
oi_total ÷ market_cap; null khi token không có vốn hóa thị trường
coins[].by_exchange
object
—
{exchange: {oi, chg_1h, chg_4h, chg_24h}}, mỗi sàn một key; null khi coin không được niêm yết ở đó. null ở một cửa sổ nghĩa là sàn đó không có mốc so sánh xa đến vậy — feed còn mới hơn độ dài cửa sổ
exchanges[]
object[]
—
binance, okx, bingx, bybit, gate — oi, side_factor, since, full_7d, last_at, stale của toàn thị trường
exchanges[].since / .full_7d
string / bool
ngày
Ngày đầu tiên của feed khi nó có dưới 7 ngày lịch sử (full_7d: false), ngược lại là null / true. Chỉ mang tính tham khảo ở bảng này (bảng không có cửa sổ 7 ngày); ở /oi_imbalance/get_coin, feed như vậy không có mốc so sánh 7 ngày và bị loại khỏi series.total
total
object
—
oi, chg_1h/4h/24h, n_exchanges, n_full_7d của toàn thị trường
summary.oi_mcap_leader / _value
string / float
—
OI ÷ vốn hóa thị trường cao nhất trong top 100 coin theo OI
tokens_shown / tokens_total / full / updated_at
—
—
Như trong bảng tỷ lệ long/short
Không phải cùng một con số với chỉ báo OI 失衡./oi_imbalance/get_overview_data (và alpha oi_imbalance đứng sau các điều kiện của bộ lọc và cảnh báo) là số tổng hợp của ba sàn — Binance + OKX + BingX. Bảng này là năm sàn trên cơ sở nêu trên. Hai giá trị oi_total khác nhau, nên ngưỡng tinh chỉnh trên giá trị này không áp dụng được cho giá trị kia.
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
503
{"error": "open interest data unavailable"}
Job không có kết quả mới (bị thiếu hoặc cũ hơn một giờ) — không bao giờ là một bảng toàn số không
Ghi chú
chg_24h: null ở OKX / Bybit trong ví dụ trên là do quy tắc feed còn mới, không phải khoảng trống của thị trường: hai sàn này bắt đầu từ 2026-09-21, nên chưa có mốc so sánh 24 giờ.
Đây là lát cắt, không phải lịch sử. 7 ngày gần nhất của một coin (theo giờ, cả năm sàn) là /oi_imbalance/get_coin; lịch sử đủ dài để backtest cho một coin trên một sàn là /oi_imbalance/get_history.
Snapshot mang các thay đổi 1 giờ / 4 giờ / 24 giờ. Nó được dựng lại bởi một job theo lịch khoảng mỗi 15 phút từ các bucket nguồn 5 phút; bucket của Gate.io và OKX về chậm khoảng 10 phút.
Hợp đồng mở của một coin theo từng sàn, trên cùng cơ sở với bảng: giá trị hiện tại và tỷ trọng, bốn cửa sổ thay đổi kèm các sàn được tính trong từng cửa sổ, và một đường tổng theo giờ trong 7 ngày.
Tham số
symbol, giống hệt như ở /long_short_ratio/get_coin.
Danh sách đầy đủ năm sàn: key, oi (USD), share (trong oi_total), chg_1h/4h/24h/7d, side_factor, listed, since, full_7d, last_at, stale
exchanges[].listed
bool
—
false = coin không được niêm yết ở đó; các giá trị của nó là null
oi_total / market_cap / oi_mcap
float
USD / tỷ lệ
Như trong bảng
oi_mcap_rank / tokens_total
int / null
—
Thứ hạng theo oi_mcap trong lượt chạy gần nhất của job dựng bảng; null khi job đó không có kết quả mới
windows.<1h|4h|24h|7d>.chg / .chg_usd
float / null
tỷ lệ / USD
Thay đổi của tổng các sàn được tính
windows.<w>.exchanges
string[]
—
Những sàn nào được tính trong cửa sổ đó — feed còn mới sẽ vắng mặt, nên 24 giờ / 7 ngày có thể tính ít sàn hơn 1 giờ
series.timestamp
int[]
giây epoch
168 ô theo giờ, cũ nhất → mới nhất
series.total
float[] / null
USD
Tổng OI mỗi ô — chỉ các sàn trong series.total_exchanges (các feed full_7d) nằm trong đường này, nên không so sánh được về mức với oi_total. Một ô là null khi bất kỳ sàn nào trong số đó không có mẫu trong giờ đó; cả trường là null khi không sàn nào là full_7d cho coin
400 / 404 / 503 giống hệt /long_short_ratio/get_coin, với {"error": "open interest data unavailable"} khi 503.
Ghi chú
Bao phủ hợp đồng mở trên Binance, OKX, BingX, Bybit và Gate.io.
windows["1h"]["exchanges"] có năm mục trong khi windows["24h"] có ba là do quy tắc feed còn mới, không phải thiếu dữ liệu — hãy đọc danh sách đó trước khi so sánh các cửa sổ.
Lưu ý về OI 失衡 ở /oi_imbalance/get_table cũng áp dụng cho oi_total này.
Chỉ có bảy ngày. Để có chuỗi dài hơn dùng cho backtest, dùng /oi_imbalance/get_history (một sàn, tính bằng coin thay vì USD — cơ sở khác với oi_total).
Hợp đồng mở của một coin trên một sàn, dưới dạng chuỗi thời gian có thể backtest — cùng cơ sở với thẻ 未平倉量 trên dashboard Studio. alpha là hợp đồng mở một phía tính bằng coin, không phải USD. Các hợp đồng có hệ số nhân được quy đổi lại về coin (1000PEPE trả về số lượng PEPE). Mỗi bucket là giá trị đọc cuối cùng trong kỳ của nó — hợp đồng mở là đại lượng tồn, không bao giờ được cộng dồn.
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
symbol
string · queryBắt buộc
Coin, cùng quy tắc với /oi_imbalance/get_coin
BTC, BTCUSDT, btc
period
string · queryBắt buộc
Kích thước bucket. 1w trả về 400 (đơn vị không được hỗ trợ); 1m được đọc là 1min, nên trả về 400 vì thấp hơn 5min
{"data": {"timestamp", "alpha", "close", "exchanges"}}, các mảng song song, cũ nhất → mới nhất.
Trường
Kiểu
Đơn vị
Mô tả
timestamp
float[]
Giây Unix (UTC)
Thời điểm bắt đầu bucket
alpha
float[]
coin
Hợp đồng mở một phía trên oi_exchange, giá trị đọc cuối cùng của bucket
close
float[]
USDT
Giá hợp đồng vĩnh cửu Binance USDT-M — tính trên mỗi đơn vị hợp đồng, tức trên mỗi 1000 coin với 1000PEPE
exchanges
string[]
—
Sàn thực tế được đọc, ví dụ ["binance"]
alpha × close không phải là hợp đồng mở tính bằng USD đối với hợp đồng có hệ số nhân. Ở đó close là giá trên mỗi đơn vị hợp đồng (trên mỗi 1000 coin với 1000PEPE) trong khi alpha tính theo từng coin — hãy chia close cho hệ số nhân trước. Với các hợp đồng không có hệ số nhân như BTC, alpha × close ≈ hợp đồng mở tính bằng USD.
Gate.io: luôn gửi start_date ≥ 2026-03-28 — cửa sổ mặc định (end_date − 365 ngày) bắt đầu trước lịch sử của Gate và trả về 400.
Không phải cùng một con số với /oi_imbalance/get_table / get_coin (cộng năm sàn, USD) và cũng không phải chỉ báo OI 失衡 (/oi_imbalance/get_overview_data).
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "symbol is required"} / {"error": "period is required"}
Thiếu (ở đây là 400, không phải 403 như các endpoint chỉ báo)
400
{"error": "period must be at least 5min, in min / h / d units"}
period dưới 5min (kể cả 1m, được đọc là 1min) hoặc dùng đơn vị khác min / h / d (1w)
400
{"error": "invalid date format, expected YYYY-MM-DD"}
start_date / end_date sai định dạng
400
{"error": "start_date must not be after end_date"}
start_date > end_date
400
{"error": "oi_exchange must be one of binance, bybit, gate"}
oi_exchange nằm ngoài danh sách
400
{"error": "no <exchange> open interest for <TOKEN> at start_date; this exchange's history may start later — try a later start_date"}
Cửa sổ bắt đầu trước lịch sử của sàn đó (xem Dữ liệu từ). Không có start_date thì oi_exchange=gate luôn gặp lỗi này cho đến khi lịch sử của nó vượt 365 ngày (≈ 2027-03) — với Gate hãy luôn gửi start_date ≥ 2026-03-28
404
{"error": "<TOKEN> is not a collected symbol on <exchange>"}
Sàn đó không niêm yết coin, coin không có hợp đồng vĩnh cửu trên Binance, hoặc đã bị hủy niêm yết — đây là câu trả lời, không phải lỗi tạm thời
503
{"error": "<exchange> open interest data unavailable for <TOKEN>"}
Hiện không đọc được dữ liệu — thử lại
Ghi chú
Bao phủ hợp đồng mở trên Binance, Bybit và Gate.io; close là giá hợp đồng vĩnh cửu Binance USDT-M.
200 kèm các mảng rỗng nghĩa là không có bucket nào trong cửa sổ đó (ví dụ coin được niêm yết sau đó) — đừng cache nó như một kết quả "không có dữ liệu" vĩnh viễn.
Bucket cuối cùng tiếp tục thay đổi cho đến khi kỳ của nó đóng, khi end_date là hôm nay.
Với lịch sử dài hơn 365 ngày, hãy gửi mỗi năm một request rồi nối lại.
Độ phân giải là 5 phút. Chuỗi của mỗi sàn bắt đầu từ ngày Dữ liệu từ, hoặc từ ngày coin được niêm yết trên sàn đó nếu muộn hơn. Chỉ gồm các hợp đồng đang niêm yết.
Giá trị giao dịch mua và bán của taker (lệnh thị trường) theo từng coin, tính bằng USD, trên ba sàn: Binance lấy từ khối lượng quote taker mua của kline 5 phút (bán = tổng của nến trừ đi phần đó), OKX lấy từ khối lượng taker tính bằng USD của sàn, Gate.io lấy từ số hợp đồng taker × hệ số nhân và giá mark của cùng dòng đó. Chỉ hợp đồng vĩnh cửu — không có giao ngay — và được tổng hợp từ nến 5 phút, không phải từ từng lệnh khớp. Giá trị giao dịch do chính mỗi sàn báo cáo được sử dụng; khối lượng không bao giờ được nhân với giá mượn từ sàn khác.
Tham số
Không có.
Ví dụ
Python
data = requests.get(f"{BASE_URL}/taker_intensity/get_cvd_table", headers=headers, timeout=30).json()["data"]buying = sorted((c for c in data["coins"] if c["net_24h"] is notNone), key=lambda c: -c["net_24h"])[:10]print(data["total"]["net_24h"], [(c["token"], c["net_24h"]) for c in buying])#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"coins": [{"token": "BTC", "token_id": 1, "buy_24h": 24607245298.03, "sell_24h": 23128502231.73,#"net_1h": -212647361.27, "net_4h": -207128163.51, "net_24h": 1478743066.31,#"by_exchange": {"binance": {"buy_24h": 12663681424.94, "sell_24h": 12135756153.44,#"net_1h": -191133129.94, "net_4h": -217337267.5, "net_24h": 527925271.5},#"gate": {...}, "okx": {...}}}, ...],#"exchanges": [{"key": "binance", "buy_24h": 34978603608.55, "sell_24h": 35112588381.38,#"net_24h": -133984772.74, "last_at": "2026-09-22T05:25:00+00:00", "stale": false}, ... 3 rows],#"total": {"buy_24h": 63543431942.93, "sell_24h": 62491177680.21, "net_24h": 1052254262.8},#"tokens_shown": 30, "tokens_total": 591, "full": false, "updated_at": "2026-09-22T05:25:00+00:00"}
Thời điểm bắt đầu thu thập (bucket đầu tiên được lưu, đo trên BTC ngày 2026-09-22)
Sàn giao dịch
Trường nguồn
Thu thập từ
binance
kline 5 phút (giá trị giao dịch mua của taker)
2020-01-01
gate
contract_stats
2026-08-12
okx
taker_volume_usd
2026-09-21
OKX còn bị giới hạn thêm do sàn chỉ giữ 5 ngày, nên vẫn là full_7d: false cho đến một tuần sau ngày đó. Bảng này không mang since / full_7d (bảng không có cửa sổ 7 ngày) — hãy đọc chúng theo từng coin từ exchanges[] của /taker_intensity/get_cvd_coin, không đọc từ các ngày này.
{exchange: {buy_24h, sell_24h, net_1h, net_4h, net_24h}}, mỗi sàn một key; null khi coin không được niêm yết ở đó hoặc dữ liệu của sàn đó cho coin bị stale
exchanges[]
object[]
—
binance, okx, gate — buy_24h, sell_24h, net_24h, last_at, stale của toàn thị trường
exchanges[].stale
bool
—
Nến cuối cùng của feed đó đã cũ hơn một giờ: các cửa sổ của nó trả về null và nó bị loại khỏi các tổng thay vì đóng góp một tổng âm thầm bao phủ ít hơn cửa sổ
total
object
USD
buy_24h, sell_24h, net_24h của toàn thị trường trên các sàn có dữ liệu mới
tokens_shown / tokens_total / full / updated_at
—
—
Như trong các bảng dữ liệu thô khác
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
503
{"error": "cvd data unavailable"}
Job không có kết quả mới — không bao giờ là số không
Ghi chú
Không giống với alpha taker_intensity (/taker_intensity/get_alpha), vốn là tín hiệu đã chuẩn hóa kiểu z-score với nhiều năm lịch sử. Đây là giá trị giao dịch USD thô, tại thời điểm hiện tại.
Các cửa sổ là cuốn chiếu và kết thúc ở nến 5 phút đã đóng gần nhất, nên net_24h không phải là một ngày theo lịch.
Được dựng lại bởi một job theo lịch khoảng mỗi 15 phút từ các bucket nguồn 5 phút; bucket của Gate.io và OKX về chậm khoảng 10 phút.
Mua / bán / ròng của taker của một coin theo từng sàn (cùng cơ sở với bảng) cộng thêm giá trị ròng theo giờ trong 7 ngày và tổng lũy kế của nó — chính là đường CVD.
Tham số
symbol, giống hệt như ở /long_short_ratio/get_coin.
Danh sách đầy đủ: key, listed, windows (cùng bốn cửa sổ, theo từng sàn), since, full_7d, last_at, stale
exchanges[].full_7d
bool
—
false = ở sàn đó coin này có dưới 7 ngày lịch sử: cửa sổ 7 ngày của nó là null và nó bị loại khỏi tổng 7 ngày và khỏi chuỗi dữ liệu. OKX chỉ giữ 5 ngày, nên là false cho đến một tuần sau khi feed bắt đầu
series.timestamp
int[]
giây epoch
168 ô theo giờ, cũ nhất → mới nhất
series.net
float[]
USD
Dòng taker ròng theo từng giờ đồng hồ, cộng trên series.exchanges; null với giờ không có dữ liệu. Khi series.exchanges rỗng, mọi ô là null và cvd đi ngang ở 0 — khi đó đường này không mang thông tin
series.cvd
float[]
USD
Tổng lũy kế của net; cvd[0] = 0 — đường này thể hiện hình dạng, không phải mức tuyệt đối
Dòng CFTC hằng tuần mới nhất của từng hợp đồng trong bốn hợp đồng tương lai crypto trên CME, cộng thêm tổng standard + micro tính bằng coin cho mỗi tài sản. Cùng cấu trúc với một dòng của /cme_cot/get_history, không có price.
Mỗi hợp đồng một mục: key (btc, micro_btc, eth, micro_eth), name, cftc_code, coin, coin_per_contract (5 / 0.1 / 50 / 0.1), latest (một dòng, xem get_history; null nếu hợp đồng không có dòng nào)
combined[]
btc_combined, eth_combined: name, coin, components, units, micro_since, note, latest (một dòng gộp, tính bằng coin)
report
futures_only
units
Đơn vị của các vị thế trong contracts[].latest: hợp đồng (× coin_per_contract để ra coin)
source
Dòng ghi nguồn CFTC — hãy hiển thị kèm mọi số liệu bạn công bố
source_updated
Thời điểm CFTC cập nhật bộ dữ liệu lần cuối
fetched_at
Thời điểm Blave lấy dữ liệu (UTC)
stale
true = không kết nối được CFTC và bản sao lưu gần nhất được phục vụ
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
503
{"error": "CFTC data unavailable. Please retry shortly."}
Không kết nối được CFTC và không có bản sao đã lưu
Ghi chú
Để lấy lịch sử, dùng /cme_cot/get_history.
Vị thế được chốt tại thứ Ba (thứ Hai khi thứ Ba là ngày lễ của Hoa Kỳ) và được CFTC công bố vào thứ Sáu của tuần đó lúc 15:30 giờ miền Đông Hoa Kỳ; ngày lễ liên bang rơi vào thứ Tư–thứ Sáu sẽ dời việc công bố sang ngày làm việc kế tiếp, và việc chính phủ đóng cửa làm chậm công bố nhiều tuần.
Vị thế hằng tuần của một hợp đồng theo nhóm nhà giao dịch. Các dòng được ghi ngày theo ngày báo cáo — ngày chốt vị thế, thường là thứ Ba (thứ Hai khi thứ Ba là ngày lễ của Hoa Kỳ). Dữ liệu được công bố sau đó: thông thường là thứ Sáu của tuần đó lúc 15:30 ET; ngày lễ liên bang rơi vào thứ Tư–thứ Sáu sẽ dời việc công bố sang ngày làm việc kế tiếp, và việc chính phủ đóng cửa làm chậm công bố nhiều tuần (các báo cáo 2018-12-24 … 2019-02-26 được phát hành vào 2019-02-01 … 03-05; các báo cáo 2025-09-30 … 2026-01-20 vào 2025-11-19 … 2026-01-23 — CFTC Releases 7864-19 và 9138-25). Backtest không được hành động theo một dòng trước thời điểm dòng đó được công bố.
Tham số
Tên
Mô tả
Giá trị hợp lệ
Mặc định
contract
string · query
Hợp đồng đơn lẻ tính bằng hợp đồng; *_combined = standard + micro cộng lại tính bằng coin
btc, micro_btc, eth, micro_eth, btc_combined, eth_combined (không phân biệt hoa thường)
btc
start_date
string · query
Ngày báo cáo đầu tiên, bao gồm cả ngày đó. Bỏ qua = chỉ một năm gần nhất — hãy truyền một ngày sớm (ví dụ 2018-01-01) để lấy toàn bộ lịch sử
{"data": {"contract": {...}, "rows": [...], "price_source", "report", "units", "source", "source_updated", "fetched_at", "stale"}}, các dòng cũ nhất → mới nhất.
contract: key, name, coin, và cftc_code + coin_per_contract (hợp đồng đơn lẻ) hoặc components + micro_since + note (hợp đồng gộp).
Mỗi dòng:
Trường
Kiểu
Mô tả
date
string
Ngày báo cáo — thường là thứ Ba, là thứ Hai khi thứ Ba là ngày lễ của Hoa Kỳ
open_interest / open_interest_change
number
Tổng hợp đồng mở và thay đổi so với tuần trước
tff
object
Các nhóm dealer, asset_manager, leveraged_funds, other_reportables, nonreportable
legacy
object | null
Các nhóm non_commercial, commercial, nonreportable; null nếu CFTC không có dòng Legacy cho tuần đó
price
float | null
Giá đóng cửa ngày theo UTC của BTCUSDT / ETHUSDT giao ngay trên Binance vào ngày báo cáo; null khi không có
included
string[]
Chỉ với hợp đồng gộp: dòng này cộng những hợp đồng nào (["btc"] trước micro_since)
Mỗi nhóm: long, short, spread (không có với nonreportable / commercial), net (= long − short), cùng long_change, short_change, spread_change, net_change. Đơn vị: hợp đồng với hợp đồng đơn lẻ, coin với hợp đồng gộp. Các trường *_change là số liệu thay đổi so với tuần trước của chính CFTC, không phải chênh lệch giữa các dòng — CFTC có bỏ qua một số tuần (ví dụ khi chính phủ đóng cửa), nên đừng bao giờ tự lấy hiệu giữa các dòng.
Lỗi
Mã trạng thái
Nội dung phản hồi
Trường hợp
400
{"error": "contract must be one of btc, micro_btc, eth, micro_eth, btc_combined, eth_combined"}
Hợp đồng không xác định
400
{"error": "Invalid start_date, expected YYYY-MM-DD"} (hoặc end_date) / {"error": "start_date must not be after end_date"}
Ngày không hợp lệ / khoảng bị đảo ngược
503
{"error": "CFTC data unavailable. Please retry shortly."}
Không kết nối được CFTC và không có bản sao đã lưu
Ghi chú
*_combined có điểm gãy tại micro_since: vào tuần micro được thêm vào, các tổng nhảy bậc và *_change của tuần đó gồm toàn bộ vị thế đầu tiên của micro. Hãy bắt đầu backtest hợp đồng gộp sau micro_since, hoặc dùng hợp đồng đơn lẻ btc / eth.
Toàn bộ lịch sử BTC là ~440 dòng hằng tuần (~0.5 MB) — một request, không phân trang.
Giấy phép: dữ liệu CFTC thuộc phạm vi công cộng, nhưng CFTC đề nghị được ghi nhận — hãy giữ source bên cạnh mọi số liệu bạn hiển thị. Không được CFTC bảo trợ.
Ngày bắt đầu theo từng hợp đồng: btc 2018-04-10, micro_btc 2021-05-04, eth 2021-04-06, micro_eth 2021-12-14. Hợp đồng tương lai BTC của chính CME xuất hiện trong COT từ 2018-04-10, không phải từ lúc ra mắt vào 2017-12.
Cache máy chủ: 1 giờ.
price là giá đóng cửa ngày theo UTC của Binance giao ngay.
Để AI của bạn làm quant ngay trên máy tính của bạn
Blave Desktop miễn phí, mã nguồn mở và không cần đăng ký. Kết nối Claude Code hoặc Codex: nó viết chiến lược, chạy backtest và giao dịch tự động.
Đang tải. Khi bạn mở trình cài đặt, Windows sẽ hiện một cảnh báo bảo mật trước:
Nhấn vào liên kết bên dưới đoạn mô tả.
Bên dưới sẽ hiện thêm một nút mới, nhấn vào đó. Blave sẽ tự cài đặt và tự mở.
Lần mở đầu tiên cần chuẩn bị môi trường chạy, mất vài phút.
Windows cảnh báo vì trình cài đặt chưa có chữ ký mã (chúng tôi đang xin chứng chỉ), nên không nhận ra nhà phát hành. Mã nguồn công khai trên GitHub. Xem đầy đủ các bước
