GET部分可用PARTIAL
訂單簿深度與滑點
各交易所在中間價 ±0.5 / 1 / 2 % 範圍內的訂單簿深度、買賣價差，以及 10k / 100k / 1M USD 市價單的滑點；另依市場類型提供彙總值及其分母。
GET
/api/sd/liquidity部分覆蓋. 對流動性最高的幣種而言，數家大型交易所的公開快照無法涵蓋整個價格區間，因此這些交易所不計入彙總值，彙總值也會低估總深度。`lower_bound_*` 欄位會加上已觀測到的部分。請務必將 `n_included` 與深度值一併解讀。
請求
查詢參數
| 名稱 | 型別 | 必填 | 預設值 | 可用值 | 說明 |
|---|---|---|---|---|---|
| coin | string | 必填 | — | — | 幣種代號，不分大小寫（例如 `BTC`）。缺少或格式錯誤時回傳 400。 範例: BTC |
| market | string | 選填 | all | perp, spot, all | 市場類型。永續合約與現貨的訂單簿絕不相加。 |
請求範例
curl -s "https://www.coinboss.com/api/sd/liquidity?coin=BTC"回應欄位
欄位表由真實回應產生，因此列出的正是端點實際回傳的內容。路徑中的 a[] 代表陣列元素，{*} 代表以動態名稱（例如幣種或交易所）為鍵的物件。
| 欄位 | 型別 | 單位 | 說明 |
|---|---|---|---|
| success | boolean | — | 請求成功時為 true。失敗時回應內容為 `{ success: false, code, error, request_id }`。 |
| schema | string | — | 此回應的結構描述 ID。只有在既有欄位的意義或型別改變時才會變更。 |
| now | number | ms | 建立回應時的伺服器時間。 |
| coin | string | — | 幣種代號（大寫）。 |
| market | string | — | `perp` 或 `spot`。 |
| venues | array | — | 每個「交易所 × 市場 × 合約」一列。 |
| venues[] | object | — | 每個「交易所 × 市場 × 合約」一列。 |
| venues[].exchange | string | — | 交易所 ID（小寫）。 |
| venues[].market | string | — | `perp` 或 `spot`。 |
| venues[].symbol | string | — | CoinBoss 儲存格式的合約代號。 |
| venues[].quote | string | — | 該市場的計價貨幣；USDT、USDC 與 USD 皆以 1:1 計為 USD。 |
| venues[].multiplier | number | — | 每個報價單位所代表的幣數（`1000PEPE` 這類合約為 1000）。價格已除以此值。 |
| venues[].contract_value | number | — | 一張合約的規模：正向合約以幣計，反向合約以 USD 計。 |
| venues[].inverse | boolean | — | 每張合約以 USD 計價的幣本位合約為 true。 |
| venues[].mid | number | USD | (best bid + best ask) ÷ 2，一枚幣的價格。 |
| venues[].best_bid | number | USD | 一枚幣的最佳買價。 |
| venues[].best_ask | number | USD | 一枚幣的最佳賣價。 |
| venues[].spread_bps | number | bp | (best ask − best bid) ÷ mid。 |
| venues[].n_bids | number | — | 快照中的買盤價格檔位數。 |
| venues[].n_asks | number | — | 快照中的賣盤價格檔位數。 |
| venues[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 |
| venues[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 |
| venues[].book_complete_bid | boolean | — | 訂單簿的整個買盤側皆已回傳時為 true。 |
| venues[].book_complete_ask | boolean | — | 訂單簿的整個賣盤側皆已回傳時為 true。 |
| venues[].bands | object | — | 各價格區間的深度；鍵 `0.5`、`1` 與 `2` 為距中間價的百分比距離。 |
| venues[].bands.1 | object | — | 距中間價此百分比距離的價格區間。 |
| venues[].bands.1.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.1.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.1.complete | boolean | — | 快照的買賣兩側皆涵蓋到價格區間邊緣時為 true。不完整的資料列不計入彙總值。 |
| venues[].bands.2 | object | — | 距中間價此百分比距離的價格區間。 |
| venues[].bands.2.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.2.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.2.complete | boolean | — | 快照的買賣兩側皆涵蓋到價格區間邊緣時為 true。不完整的資料列不計入彙總值。 |
| venues[].bands.0.5 | object | — | 距中間價此百分比距離的價格區間。 |
| venues[].bands.0.5.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.0.5.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 |
| venues[].bands.0.5.complete | boolean | — | 快照的買賣兩側皆涵蓋到價格區間邊緣時為 true。不完整的資料列不計入彙總值。 |
| venues[].slippage | object | — | 市價單的滑點；鍵 `10000`、`100000` 與 `1000000` 為以 USD 計的訂單規模。 |
| venues[].slippage.10000 | object | — | 此 USD 規模的市價單。 |
| venues[].slippage.10000.buy_bps | number | bp | 市價買單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.10000.sell_bps | number|null | bp | 市價賣單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.10000.buy_flag | null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].slippage.10000.sell_flag | string|null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].slippage.100000 | object | — | 此 USD 規模的市價單。 |
| venues[].slippage.100000.buy_bps | number|null | bp | 市價買單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.100000.sell_bps | number|null | bp | 市價賣單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.100000.buy_flag | string|null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].slippage.100000.sell_flag | string|null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].slippage.1000000 | object | — | 此 USD 規模的市價單。 |
| venues[].slippage.1000000.buy_bps | number|null | bp | 市價買單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.1000000.sell_bps | number|null | bp | 市價賣單的平均成交價相對於中間價的偏離（包含一半的買賣價差）；快照不足以成交該訂單時為 `null`。 |
| venues[].slippage.1000000.buy_flag | string|null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].slippage.1000000.sell_flag | string|null | — | 快照不足以成交該訂單時為 `insufficient_book`，使用了價格合併區間時為 `upper_bound`，否則為 `null`。 |
| venues[].book_bid_usd | number | USD | 快照所含全部買盤掛單的名義價值。 |
| venues[].book_ask_usd | number | USD | 快照所含全部賣盤掛單的名義價值。 |
| venues[].agg_step_bps | number|null | bp | ±2 % 範圍內所用最寬的價格合併區間；僅使用原始價格檔位時為 `null`。 |
| venues[].layers | number | — | 為此資料列拼接而成的快照數量。 |
| venues[].observed_at | number|null | ms | 來源為該資料提供的時間戳記。 |
| venues[].received_at | number | ms | CoinBoss 採集器收到資料的時間。 |
| venues[].lag_ms | number|null | ms | 接收時間減去交易所提供的訂單簿時間戳記；交易所未提供時間戳記時為 `null`。 |
| venues[].age_s | number | s | 距收到該資料列的秒數。 |
| venues[].fresh_window_s | number | s | 存在時間超過此值的資料列即視為過期。 |
| venues[].is_stale | boolean | — | 資料已超出其新鮮視窗時為 true。 |
| venues[].tier | string | — | 採集層級：`A` 為交易最活躍的幣種，`B` 為其餘幣種。 |
| venues[].period_s | number | s | 此資料列的採集週期。 |
| aggregate | object | — | 各市場類型的合計。永續合約與現貨絕不相加。 |
| aggregate.perp | object | — | 永續合約訂單簿的彙總值；沒有資料列時為 `null`。 可能不存在 |
| aggregate.perp.n_rows | number | — | 找到的資料列數，包含過期者。 可能不存在 |
| aggregate.perp.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.perp.mid_median | number | USD | 新鮮資料列中間價的中位數。 可能不存在 |
| aggregate.perp.spread_bps_min | number | bp | 新鮮資料列中最窄的買賣價差。 可能不存在 |
| aggregate.perp.bands | object | — | 各價格區間的深度；鍵 `0.5`、`1` 與 `2` 為距中間價的百分比距離。 可能不存在 |
| aggregate.perp.bands.1 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.perp.bands.1.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.1.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.1.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.perp.bands.1.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.perp.bands.1.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.1.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.1.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.1.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.1.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.1.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| aggregate.perp.bands.2 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.perp.bands.2.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.2.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.2.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.perp.bands.2.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.perp.bands.2.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.2.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.2.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.2.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.2.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.2.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| aggregate.perp.bands.0.5 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.perp.bands.0.5.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.0.5.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.perp.bands.0.5.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.perp.bands.0.5.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.perp.bands.0.5.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.0.5.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.0.5.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.perp.bands.0.5.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.0.5.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.perp.bands.0.5.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| aggregate.spot | object | — | 現貨訂單簿的彙總值；沒有資料列時為 `null`。 可能不存在 |
| aggregate.spot.n_rows | number | — | 找到的資料列數，包含過期者。 可能不存在 |
| aggregate.spot.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.spot.mid_median | number | USD | 新鮮資料列中間價的中位數。 可能不存在 |
| aggregate.spot.spread_bps_min | number | bp | 新鮮資料列中最窄的買賣價差。 可能不存在 |
| aggregate.spot.bands | object | — | 各價格區間的深度；鍵 `0.5`、`1` 與 `2` 為距中間價的百分比距離。 可能不存在 |
| aggregate.spot.bands.1 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.spot.bands.1.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.1.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.1.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.spot.bands.1.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.spot.bands.1.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.1.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.1.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.1.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.1.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.1.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| aggregate.spot.bands.2 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.spot.bands.2.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.2.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.2.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.spot.bands.2.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.spot.bands.2.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.2.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.2.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.2.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.2.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.2.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| aggregate.spot.bands.0.5 | object | — | 距中間價此百分比距離的價格區間。 可能不存在 |
| aggregate.spot.bands.0.5.bid_depth_usd | number | USD | 中間價與價格區間下緣之間的買盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.0.5.ask_depth_usd | number | USD | 中間價與價格區間上緣之間的賣盤掛單名義價值。`complete` 為 false 時為下限。 可能不存在 |
| aggregate.spot.bands.0.5.n_included | number | — | 計入深度加總的資料列數：須為新鮮且在該價格區間內完整。請與深度值一併解讀。 可能不存在 |
| aggregate.spot.bands.0.5.n_fresh | number | — | 新鮮的資料列數。 可能不存在 |
| aggregate.spot.bands.0.5.included_exchanges | array | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.0.5.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete | array | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete[] | object | — | 因快照未涵蓋到價格區間邊緣而被排除在該區間之外的新鮮資料列。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete[].exchange | string | — | 交易所 ID（小寫）。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete[].symbol | string | — | CoinBoss 儲存格式的合約代號。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete[].reach_bid_pct | number | % | 中間價到快照中最遠買盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.0.5.excluded_incomplete[].reach_ask_pct | number | % | 中間價到快照中最遠賣盤檔位的距離。 可能不存在 |
| aggregate.spot.bands.0.5.lower_bound_bid_usd | number | USD | 包含不完整資料列已觀測部分的買盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.0.5.lower_bound_ask_usd | number | USD | 包含不完整資料列已觀測部分的賣盤深度。這是下限，而非估計值。 可能不存在 |
| aggregate.spot.bands.0.5.uses_aggregated_buckets | boolean | — | 有任一納入的資料列使用了價格合併區間時為 true，此時加總值為下限。 可能不存在 |
| coverage | object | — | 數字中納入與未納入的內容。與其他來源比較合計值之前，請先比對這一項。 |
| coverage.included_exchanges | array | — | 新鮮資料已被納入的來源。 |
| coverage.included_exchanges[] | string | — | 新鮮資料已被納入的來源。 |
| coverage.unavailable | array | — | 無法納入的來源，各附原因。它們絕不會以 0 計入。 在產生此表所用的樣本中為空 |
| coverage.stale_excluded | array | — | 因最近一次更新超出新鮮視窗而被排除的資料列。 在產生此表所用的樣本中為空 |
| coverage.no_market | array | — | 有採集、但沒有此幣種資料列的「交易所 × 市場」組合。 在產生此表所用的樣本中為空 |
| method | object | — | 此回應所用公式的純文字說明，每個欄位一項。 |
| method.mid | string | — | `mid` 的公式說明，純文字。 |
| method.spread_bps | string | — | `spread_bps` 的公式說明，純文字。 |
| method.bid_depth_usd | string | — | `bid_depth_usd` 的公式說明，純文字。 |
| method.ask_depth_usd | string | — | `ask_depth_usd` 的公式說明，純文字。 |
| method.complete | string | — | `complete` 的公式說明，純文字。 |
| method.reach_pct | string | — | `reach_pct` 的公式說明，純文字。 |
| method.slippage_bps | string | — | `slippage_bps` 的公式說明，純文字。 |
| method.agg_step_bps | string | — | `agg_step_bps` 的公式說明，純文字。 |
| method.aggregate | string | — | `aggregate` 的公式說明，純文字。 |
| method.fresh | string | — | `fresh` 的公式說明，純文字。 |
| method.lag_ms | string | — | `lag_ms` 的公式說明，純文字。 |
| method.no_market | string | — | `no_market` 的公式說明，純文字。 |
| meta | object | — | 此回應的資料歷程與新鮮度。 |
| meta.schema | string | — | 此回應的結構描述 ID。只有在既有欄位的意義或型別改變時才會變更。 |
| meta.source | array | — | 資料採集所用的上游公開端點。 |
| meta.source[] | object | — | 資料採集所用的上游公開端點。 |
| meta.source[].exchange | string | — | 交易所 ID（小寫）。 |
| meta.source[].market | string | — | `perp` 或 `spot`。 |
| meta.source[].endpoint | string | — | 採集器讀取的來源公開端點（僅供說明資料歷程；用戶端不會直接呼叫它）。 |
| meta.observed_at | number | ms | 來源為該資料提供的時間戳記。 |
| meta.received_at | number | ms | CoinBoss 採集器收到資料的時間。 |
| meta.fetched_at | number | ms | 此回應組裝完成的時間。 |
| meta.window | string | — | 數字涵蓋的時間視窗。 |
| meta.quality | string | — | FRESH、PARTIAL、STALE、BROKEN 或 UNAVAILABLE，依資料時間戳記與覆蓋範圍判定。 |
| meta.is_stale | boolean | — | 資料已超出其新鮮視窗時為 true。 |
| meta.cache_ttl_s | number | s | 此回應的快取存活時間。 |
| meta.fallback | string | — | 採集器或來源發生故障時，此端點回傳的內容。 |
| meta.collector_heartbeat_age_s | number | s | 距採集器上次回報仍在運作的秒數。 |
產生於 2026-11-11 23:28 UTC，依據 4 筆真實回應。
回應範例
/api/sd/liquidity?coin=BTC · 真實回應，擷取於 2026-11-13 04:02:45 UTC。 較長的陣列與對應表已截短顯示：venues 原有 39 個項目; meta.source 原有 38 個項目; coverage.included_exchanges 原有 24 個項目; aggregate.perp.bands.1.included_exchanges 原有 19 個項目; aggregate.perp.bands.2.included_exchanges 原有 16 個項目; aggregate.spot.bands.1.included_exchanges 原有 13 個項目。
- "success"true
- "schema""coinboss.sd.liquidity/1"
- "now"1794542565757
- "coin""BTC"
- "market""all"
- "venues"
- "aggregate"
- "perp"
- "spot"
- "coverage"
- "included_exchanges"
- "unavailable"
- "stale_excluded"
- "no_market"
- "method"
- "mid""(best_bid + best_ask) / 2 of the venue order book, normalised to the USD price of ONE coin (1000PEPE / kPEPE style contr…"
- "spread_bps""(best_ask - best_bid) / mid * 1e4"
- "bid_depth_usd""sum of resting bid notional with price >= mid * (1 - band%), in USD; notional = price * size * contract_value (inverse c…"
- "ask_depth_usd""sum of resting ask notional with price <= mid * (1 + band%), in USD; same notional rule as bid_depth_usd"
- "complete""true when BOTH sides of the snapshot reach the band edge (reach_pct >= band) or the whole side of the book was returned;…"
- "reach_pct""distance in % between mid and the farthest price level contained in the snapshot on that side"
- "slippage_bps""market order of N USD walked through the book: buy = (avg_fill / mid - 1) * 1e4, sell = (1 - avg_fill / mid) * 1e4, meas…"
- "agg_step_bps""widest price-aggregation bucket (in bps of mid) used inside +-2% for venues whose REST only exposes a shallow raw book (…"
- "aggregate""per market and band: sum over rows that are fresh AND complete for that band; n_included / n_fresh is the denominator; l…"
- "fresh""a row is fresh when now - received_at <= max(3 * period_s, 300s); stale rows are listed in coverage.stale_excluded; rows…"
- "lag_ms""received_at - venue timestamp of the book (null when the venue gives none); Gate spot books deeper than 100 levels are v…"
- "no_market""covered venue/market pairs that are being collected but hold no row for this coin: not listed there, or the contract was…"
- "meta"
- "schema""coinboss.sd.liquidity/1"
- "source"
- "observed_at"1794542554621
- "received_at"1794542554947
- "fetched_at"1794542565757
- "window""latest"
- "quality""PARTIAL"
- "is_stale"false
- "cache_ttl_s"15
- "fallback""on collector failure the last stored row is served with is_stale=true and left out of the aggregate; rows older than 24h…"
- "collector_heartbeat_age_s"3
已驗證的樣本
除了上方的範例之外，探針還會以下列參數呼叫此端點，並在每次呼叫時檢查結構描述。
| 參數 | HTTP | 延遲 | 結果 |
|---|---|---|---|
| coin=ETH&market=spot | 200 | 3 ms | 通過 PARTIAL |
| coin=PEPE&market=perp | 200 | 4 ms | 通過 FRESH |
| coin=SOL | 200 | 4 ms | 通過 PARTIAL |
| — | 400 | 1 ms | 通過 回傳預期的錯誤 |
檢查於 2026-11-13 03:58:06 UTC
詳細資訊
- 身分驗證
- 無。公開端點。
- 速率限制
- 每個 IP 每分鐘 1200 次請求
- 伺服器快取
- 15s
- 邊緣微快取
- 10s
- 更新頻率
- 成交最活躍的幣種每 120 秒擷取一次快照，其餘每 600 秒（少數交易所為 300 / 1200 秒）。資料列在三個採集週期內視為新鮮，最短 300 秒。
- 時間視窗
- 每個合約的最新快照。
- 資料來源
- 24 家交易所（永續合約與現貨市場）的公開 REST 訂單簿快照，由 CoinBoss 採集並儲存（sd_book_latest、sd_book_hist）。深度與滑點由 CoinBoss 依原始價格檔位自行計算。
- 交易所覆蓋範圍
- 24 家交易所，38 條「交易所 × 市場」通道。若公開快照未能涵蓋距中間價 ±0.5 / 1 / 2 % 的範圍（受交易所的檔位數上限所限），該價格區間會標記為 `complete: false`，其數值為下限，且不計入彙總值；`n_included` / `n_fresh` 提供分母，`excluded_incomplete` 則列出被排除的項目。
- 分頁
- 不分頁；每個「交易所 × 市場 × 合約」一列。
- 排序
- 永續合約資料列在前，現貨在後；各自再依 ±1 % 深度（買盤 + 賣盤）降冪排列。
- 單位
- Depth in USD notional, bid and ask side reported separately and never added. Spread and slippage in basis points (1 bp = 0.01 %). USDT / USDC / USD quotes are counted 1:1 as USD.
- 計算方法
- mid = (best bid + best ask) ÷ 2. Depth = Σ price × size of all levels between mid and mid ± x %. Slippage = (average fill price of a market order of N USD − mid) ÷ mid, in bp; `null` with flag `insufficient_book` when the snapshot cannot fill the order (no extrapolation), flag `upper_bound` when an aggregated price bucket was used.
- 時間戳記
- Unix epoch 毫秒（UTC），除非欄位說明另有註明
- 回應格式
- json
- 穩定性
- 穩定版
- 上線時間
- 2026-11-11
即時狀態
部分可用檢查於 2026-11-13 04:02:45 UTCHTTP 2006 ms結構描述相符最新資料點距今 11s
端點回報的資料品質為 PARTIAL — 對流動性最高的幣種而言，數家大型交易所的公開快照無法涵蓋整個價格區間，因此這些交易所不計入彙總值，彙總值也會低估總深度。`lower_bound_*` 欄位會加上已觀測到的部分。請務必將 `n_included` 與深度值一併解讀。
近 30 天可用率
408 次檢查中有 100% 通過
錯誤
所有端點的失敗回應都採用同一種結構。完整清單請見錯誤頁面。 錯誤與速率限制 →
| 錯誤碼 | HTTP | 意義 | 處理方式 |
|---|---|---|---|
| INVALID_PARAM | 400 | 缺少必填參數，或某個值不被接受。已知時，`param` 會指出是哪個參數。 | 請勿原樣重試；請修正請求。 |
| UNAUTHORIZED | 401 | 已送出 `CB-API-KEY` 標頭，但金鑰未知或已撤銷。公開資料不需要金鑰——請移除該標頭或改用有效的金鑰。 | 請勿原樣重試。 |
| FORBIDDEN | 403 | 此路由不屬於公開 API（內部或僅限帳戶使用）。 | 請勿重試。 |
| NOT_FOUND | 404 | 未知的路由，或所請求的幣種／交易所／基金不存在。 | 請勿重試；請對照目錄檢查路徑與識別碼。 |
| RATE_LIMITED | 429 | 請求數超過每分鐘上限。`Retry-After` 會指出需等待的秒數。 | 等待 `Retry-After` 指定的時間後，再以退避策略重試。 |
| INTERNAL | 500 | 非預期的伺服器錯誤。訊息刻意保持籠統；回報時請附上 `request_id`。 | 幾秒後重試一次；若問題持續，請附上請求 ID 回報。 |
| UPSTREAM_FAILED | 503 | 此端點背後的資料來源未及時回應。不會以過期或替代的數字代替回傳。 | 以退避策略重試；並查看狀態頁面。 |
| UNAVAILABLE | 501 / 503 | 資料集暫時尚未就緒（快取預熱中），或此端點目前尚無合法的公開來源。 | 稍後重試；目錄會標示出設計上即無法使用的端點。 |
| REQUEST_FAILED | 200 | 部分舊版端點會以 HTTP 200 回應但帶有 `success: false`。請務必檢查 `success`，而不只是 HTTP 狀態碼。 | 視訊息而定；請當作失敗的請求處理。 |
試用
GET
/api/sd/liquidity部分可用參數
string — Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400.
string · 預設 all — Market type. Perpetual and spot books are never added together.
請求 URL
https://www.coinboss.com/api/sd/liquidity?coin=BTC選擇一個端點並按下「送出請求」。回應內容、標頭與耗時會顯示在這裡。
此分類的其他端點
- 訂單簿深度與滑點 /api/sd/liquidity
- 訂單簿深度歷史 /api/sd/liquidity/history
- 依訂單簿深度排行的幣種 /api/sd/liquidity/rank
- 大額掛單監控 /api/indicators/large-orderbook