GETPartialPARTIAL
Order-book depth and slippage
Per-exchange order-book depth within ±0.5 / 1 / 2 % of mid, spread, and the slippage of a 10k / 100k / 1M USD market order, plus an aggregate per market type with its denominator.
GET
/api/sd/liquidityPartial coverage. For the most liquid coins, the public snapshots of several large venues do not reach the full band, so those venues are excluded from the aggregate and the aggregate understates total depth. `lower_bound_*` fields add the part that was observed. Always read `n_included` together with the depth value.
Request
Query parameters
| Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| coin | string | Required | — | — | Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400. Example: BTC |
| market | string | Optional | all | perp, spot, all | Market type. Perpetual and spot books are never added together. |
Example request
curl -s "https://www.coinboss.com/api/sd/liquidity?coin=BTC"Response fields
The field table is generated from real responses, so it lists exactly what the endpoint returns. Paths use a[] for array items and {*} for objects keyed by a dynamic name such as a coin or an exchange.
| Field | Type | Unit | Description |
|---|---|---|---|
| success | boolean | — | true when the request succeeded. On failure the body is `{ success: false, code, error, request_id }`. |
| schema | string | — | Schema id of this response. It changes only when an existing field changes meaning or type. |
| now | number | ms | Server time when the response was built. |
| coin | string | — | Coin symbol (upper case). |
| market | string | — | `perp` or `spot`. |
| venues | array | — | One row per exchange × market × contract. |
| venues[] | object | — | One row per exchange × market × contract. |
| venues[].exchange | string | — | Exchange id (lower case). |
| venues[].market | string | — | `perp` or `spot`. |
| venues[].symbol | string | — | Contract symbol in CoinBoss storage form. |
| venues[].quote | string | — | Quote currency of the market; USDT, USDC and USD are counted 1:1 as USD. |
| venues[].multiplier | number | — | Coins per quoted unit (1000 for `1000PEPE`-style contracts). Prices are already divided by it. |
| venues[].contract_value | number | — | Size of one contract: coins for linear contracts, USD for inverse contracts. |
| venues[].inverse | boolean | — | True for coin-margined contracts quoted in USD per contract. |
| venues[].mid | number | USD | (best bid + best ask) ÷ 2, price of one coin. |
| venues[].best_bid | number | USD | Best bid price of one coin. |
| venues[].best_ask | number | USD | Best ask price of one coin. |
| venues[].spread_bps | number | bp | (best ask − best bid) ÷ mid. |
| venues[].n_bids | number | — | Bid price levels in the snapshot. |
| venues[].n_asks | number | — | Ask price levels in the snapshot. |
| venues[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. |
| venues[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. |
| venues[].book_complete_bid | boolean | — | True when the whole bid side of the book was returned. |
| venues[].book_complete_ask | boolean | — | True when the whole ask side of the book was returned. |
| venues[].bands | object | — | Depth per band; the keys `0.5`, `1` and `2` are the distance from mid in percent. |
| venues[].bands.1 | object | — | Band of this distance from mid, in percent. |
| venues[].bands.1.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. |
| venues[].bands.1.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. |
| venues[].bands.1.complete | boolean | — | True when both sides of the snapshot reach the band edge. Incomplete rows are left out of aggregates. |
| venues[].bands.2 | object | — | Band of this distance from mid, in percent. |
| venues[].bands.2.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. |
| venues[].bands.2.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. |
| venues[].bands.2.complete | boolean | — | True when both sides of the snapshot reach the band edge. Incomplete rows are left out of aggregates. |
| venues[].bands.0.5 | object | — | Band of this distance from mid, in percent. |
| venues[].bands.0.5.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. |
| venues[].bands.0.5.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. |
| venues[].bands.0.5.complete | boolean | — | True when both sides of the snapshot reach the band edge. Incomplete rows are left out of aggregates. |
| venues[].slippage | object | — | Slippage of a market order; the keys `10000`, `100000` and `1000000` are the order size in USD. |
| venues[].slippage.10000 | object | — | Market order of this size in USD. |
| venues[].slippage.10000.buy_bps | number | bp | Average fill price of a market buy relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.10000.sell_bps | number|null | bp | Average fill price of a market sell relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.10000.buy_flag | null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].slippage.10000.sell_flag | string|null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].slippage.100000 | object | — | Market order of this size in USD. |
| venues[].slippage.100000.buy_bps | number|null | bp | Average fill price of a market buy relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.100000.sell_bps | number|null | bp | Average fill price of a market sell relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.100000.buy_flag | string|null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].slippage.100000.sell_flag | string|null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].slippage.1000000 | object | — | Market order of this size in USD. |
| venues[].slippage.1000000.buy_bps | number|null | bp | Average fill price of a market buy relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.1000000.sell_bps | number|null | bp | Average fill price of a market sell relative to mid (includes half the spread); `null` when the snapshot cannot fill the order. |
| venues[].slippage.1000000.buy_flag | string|null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].slippage.1000000.sell_flag | string|null | — | `insufficient_book` when the order cannot be filled from the snapshot, `upper_bound` when an aggregated bucket was used, otherwise `null`. |
| venues[].book_bid_usd | number | USD | Notional of all bids contained in the snapshot. |
| venues[].book_ask_usd | number | USD | Notional of all asks contained in the snapshot. |
| venues[].agg_step_bps | number|null | bp | Widest price-aggregation bucket used inside ±2 %; `null` when only raw levels were used. |
| venues[].layers | number | — | Number of snapshots stitched together for this row. |
| venues[].observed_at | number|null | ms | Timestamp given by the source for the data. |
| venues[].received_at | number | ms | Time the CoinBoss collector received the data. |
| venues[].lag_ms | number|null | ms | Receive time minus the book timestamp of the venue; `null` when the venue gives none. |
| venues[].age_s | number | s | Seconds since the row was received. |
| venues[].fresh_window_s | number | s | A row older than this is stale. |
| venues[].is_stale | boolean | — | True when the data is older than its fresh window. |
| venues[].tier | string | — | Collection tier: `A` for the most traded coins, `B` for the rest. |
| venues[].period_s | number | s | Collection period of the row. |
| aggregate | object | — | Totals per market type. Perpetual and spot are never added together. |
| aggregate.perp | object | — | Aggregate over perpetual books; `null` when there is no row. may be absent |
| aggregate.perp.n_rows | number | — | Rows found, including stale ones. may be absent |
| aggregate.perp.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.perp.mid_median | number | USD | Median mid price of the fresh rows. may be absent |
| aggregate.perp.spread_bps_min | number | bp | Tightest spread among the fresh rows. may be absent |
| aggregate.perp.bands | object | — | Depth per band; the keys `0.5`, `1` and `2` are the distance from mid in percent. may be absent |
| aggregate.perp.bands.1 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.perp.bands.1.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.1.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.1.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.perp.bands.1.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.perp.bands.1.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.1.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.1.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.1.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.1.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.perp.bands.1.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.perp.bands.1.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.perp.bands.1.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.perp.bands.1.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.1.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.1.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| aggregate.perp.bands.2 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.perp.bands.2.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.2.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.2.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.perp.bands.2.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.perp.bands.2.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.2.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.2.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.2.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.2.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.perp.bands.2.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.perp.bands.2.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.perp.bands.2.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.perp.bands.2.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.2.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.2.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| aggregate.perp.bands.0.5 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.perp.bands.0.5.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.0.5.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.perp.bands.0.5.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.perp.bands.0.5.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.perp.bands.0.5.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.0.5.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.perp.bands.0.5.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.perp.bands.0.5.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.0.5.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.perp.bands.0.5.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| aggregate.spot | object | — | Aggregate over spot books; `null` when there is no row. may be absent |
| aggregate.spot.n_rows | number | — | Rows found, including stale ones. may be absent |
| aggregate.spot.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.spot.mid_median | number | USD | Median mid price of the fresh rows. may be absent |
| aggregate.spot.spread_bps_min | number | bp | Tightest spread among the fresh rows. may be absent |
| aggregate.spot.bands | object | — | Depth per band; the keys `0.5`, `1` and `2` are the distance from mid in percent. may be absent |
| aggregate.spot.bands.1 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.spot.bands.1.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.1.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.1.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.spot.bands.1.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.spot.bands.1.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.1.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.1.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.1.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.1.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.spot.bands.1.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.spot.bands.1.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.spot.bands.1.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.spot.bands.1.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.1.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.1.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| aggregate.spot.bands.2 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.spot.bands.2.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.2.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.2.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.spot.bands.2.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.spot.bands.2.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.2.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.2.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.2.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.2.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.spot.bands.2.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.spot.bands.2.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.spot.bands.2.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.spot.bands.2.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.2.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.2.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| aggregate.spot.bands.0.5 | object | — | Band of this distance from mid, in percent. may be absent |
| aggregate.spot.bands.0.5.bid_depth_usd | number | USD | Resting bid notional between mid and the lower band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.0.5.ask_depth_usd | number | USD | Resting ask notional between mid and the upper band edge. A lower bound when `complete` is false. may be absent |
| aggregate.spot.bands.0.5.n_included | number | — | Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value. may be absent |
| aggregate.spot.bands.0.5.n_fresh | number | — | Fresh rows. may be absent |
| aggregate.spot.bands.0.5.included_exchanges | array | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.0.5.included_exchanges[] | string | — | Sources whose fresh data is included. may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete | array | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete[] | object | — | Fresh rows left out of the band because their snapshot does not reach the band edge. may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete[].exchange | string | — | Exchange id (lower case). may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete[].symbol | string | — | Contract symbol in CoinBoss storage form. may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete[].reach_bid_pct | number | % | Distance from mid to the farthest bid level in the snapshot. may be absent |
| aggregate.spot.bands.0.5.excluded_incomplete[].reach_ask_pct | number | % | Distance from mid to the farthest ask level in the snapshot. may be absent |
| aggregate.spot.bands.0.5.lower_bound_bid_usd | number | USD | Bid depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.0.5.lower_bound_ask_usd | number | USD | Ask depth including the observed part of incomplete rows. A floor, not an estimate. may be absent |
| aggregate.spot.bands.0.5.uses_aggregated_buckets | boolean | — | True when an included row used price-aggregated buckets, which makes the sum a lower bound. may be absent |
| coverage | object | — | What is and is not included in the numbers. Compare this before comparing totals with another source. |
| coverage.included_exchanges | array | — | Sources whose fresh data is included. |
| coverage.included_exchanges[] | string | — | Sources whose fresh data is included. |
| coverage.unavailable | array | — | Sources that could not be included, each with a reason. They are never counted as 0. empty in the samples used to generate this table |
| coverage.stale_excluded | array | — | Rows left out because their last update is outside the fresh window. empty in the samples used to generate this table |
| coverage.no_market | array | — | Exchange × market pairs that are collected but hold no row for this coin. empty in the samples used to generate this table |
| method | object | — | Plain-text statement of the formulas used for this response, one entry per field. |
| method.mid | string | — | Formula note for `mid`, plain text. |
| method.spread_bps | string | — | Formula note for `spread_bps`, plain text. |
| method.bid_depth_usd | string | — | Formula note for `bid_depth_usd`, plain text. |
| method.ask_depth_usd | string | — | Formula note for `ask_depth_usd`, plain text. |
| method.complete | string | — | Formula note for `complete`, plain text. |
| method.reach_pct | string | — | Formula note for `reach_pct`, plain text. |
| method.slippage_bps | string | — | Formula note for `slippage_bps`, plain text. |
| method.agg_step_bps | string | — | Formula note for `agg_step_bps`, plain text. |
| method.aggregate | string | — | Formula note for `aggregate`, plain text. |
| method.fresh | string | — | Formula note for `fresh`, plain text. |
| method.lag_ms | string | — | Formula note for `lag_ms`, plain text. |
| method.no_market | string | — | Formula note for `no_market`, plain text. |
| meta | object | — | Lineage and freshness of this response. |
| meta.schema | string | — | Schema id of this response. It changes only when an existing field changes meaning or type. |
| meta.source | array | — | Upstream public endpoints the data was collected from. |
| meta.source[] | object | — | Upstream public endpoints the data was collected from. |
| meta.source[].exchange | string | — | Exchange id (lower case). |
| meta.source[].market | string | — | `perp` or `spot`. |
| meta.source[].endpoint | string | — | Public endpoint of the source the collector reads (shown for lineage; clients never call it). |
| meta.observed_at | number | ms | Timestamp given by the source for the data. |
| meta.received_at | number | ms | Time the CoinBoss collector received the data. |
| meta.fetched_at | number | ms | Time this response was assembled. |
| meta.window | string | — | Time window the numbers cover. |
| meta.quality | string | — | FRESH, PARTIAL, STALE, BROKEN or UNAVAILABLE, judged from data timestamps and coverage. |
| meta.is_stale | boolean | — | True when the data is older than its fresh window. |
| meta.cache_ttl_s | number | s | Cache lifetime of this response. |
| meta.fallback | string | — | What the endpoint returns when the collector or a source fails. |
| meta.collector_heartbeat_age_s | number | s | Seconds since the collector last reported that it is running. |
Generated 2026-11-11 23:28 UTC from 4 real responses.
Example response
/api/sd/liquidity?coin=BTC · Real response captured 2026-11-13 03:58:06 UTC. Long arrays and maps are shortened for display: venues had 39 items; meta.source had 38 items; coverage.included_exchanges had 24 items; aggregate.perp.bands.1.included_exchanges had 19 items; aggregate.perp.bands.2.included_exchanges had 16 items; aggregate.spot.bands.1.included_exchanges had 14 items.
- "success"true
- "schema""coinboss.sd.liquidity/1"
- "now"1794542286066
- "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"1794542285214
- "received_at"1794542285776
- "fetched_at"1794542286066
- "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"9
Verified samples
Besides the example above, the probe calls this endpoint with these parameters and checks the schema each time.
| Parameters | HTTP | Latency | Result |
|---|---|---|---|
| coin=ETH&market=spot | 200 | 3 ms | Pass PARTIAL |
| coin=PEPE&market=perp | 200 | 4 ms | Pass FRESH |
| coin=SOL | 200 | 4 ms | Pass PARTIAL |
| — | 400 | 1 ms | Pass returns the expected error |
Checked 2026-11-13 03:58:06 UTC
Details
- Authentication
- None. Public endpoint.
- Rate limit
- 1200 requests per minute per IP
- Server cache
- 15s
- Edge micro-cache
- 10s
- Update frequency
- Snapshots every 120 seconds for the most traded coins and every 600 seconds for the rest (a few venues: 300 / 1200 seconds). A row is fresh for three collection periods, at least 300 seconds.
- Window
- Latest snapshot per contract.
- Data sources
- Public REST order-book snapshots of 24 exchanges (perpetual and spot markets), collected and stored by CoinBoss (sd_book_latest, sd_book_hist). Depth and slippage are computed by CoinBoss from the raw price levels.
- Exchange coverage
- 24 exchanges, 38 exchange × market lanes. Where a public snapshot does not reach ±0.5 / 1 / 2 % from mid (level cap of the venue), that band is flagged `complete: false`, its value is a lower bound and it is left out of the aggregate; `n_included` / `n_fresh` give the denominator and `excluded_incomplete` lists what was left out.
- Pagination
- No paging; one row per exchange × market × contract.
- Sorting
- Perpetual rows first, then spot; inside each by ±1 % depth (bid + ask) descending.
- Units
- 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.
- Method
- 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.
- Timestamps
- Unix epoch milliseconds (UTC) unless the field description says otherwise
- Response format
- json
- Stability
- Stable
- Available since
- 2026-11-11
Live status
PartialChecked 2026-11-13 03:58:06 UTCHTTP 2007 msSchema matchesNewest data point 0s old
The endpoint reports data quality PARTIAL — For the most liquid coins, the public snapshots of several large venues do not reach the full band, so those venues are excluded from the aggregate and the aggregate understates total depth. `lower_bound_*` fields add the part that was observed. Always read `n_included` together with the depth value.
Availability, last 30 days
100% of 407 checks passed
Errors
Failed calls share one shape on every endpoint. The full list is on the errors page. Errors and rate limits →
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| INVALID_PARAM | 400 | A required parameter is missing or a value is not accepted. `param` names the parameter when it is known. | Do not retry unchanged; fix the request. |
| UNAUTHORIZED | 401 | The `CB-API-KEY` header was sent but the key is unknown or revoked. Public data needs no key — drop the header or use a valid key. | Do not retry unchanged. |
| FORBIDDEN | 403 | The route is not part of the public API (internal or account-only). | Do not retry. |
| NOT_FOUND | 404 | Unknown route, or the requested coin / exchange / fund does not exist. | Do not retry; check the path and identifiers against the catalog. |
| RATE_LIMITED | 429 | More requests than the per-minute limit. `Retry-After` gives the seconds to wait. | Wait for `Retry-After`, then retry with backoff. |
| INTERNAL | 500 | Unexpected server error. The message is generic by design; quote `request_id` when reporting it. | Retry once after a few seconds; report it with the request id if it persists. |
| UPSTREAM_FAILED | 503 | The data source behind this endpoint did not answer in time. No stale or substitute numbers are returned in its place. | Retry with backoff; check the status page. |
| UNAVAILABLE | 501 / 503 | The dataset is temporarily not ready (cache warming) or the endpoint has no lawful public source yet. | Retry later; the catalog marks endpoints that are unavailable by design. |
| REQUEST_FAILED | 200 | Some older endpoints answer HTTP 200 with `success: false`. Always check `success`, not only the HTTP status. | Depends on the message; treat as a failed request. |
Try it
GET
/api/sd/liquidityPartialParameters
string — Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400.
string · default all — Market type. Perpetual and spot books are never added together.
Request URL
https://www.coinboss.com/api/sd/liquidity?coin=BTCChoose an endpoint and press “Send request”. The response, headers and timing will appear here.
More in this category
- Order-book depth and slippage /api/sd/liquidity
- Order-book depth history /api/sd/liquidity/history
- Coins ranked by order-book depth /api/sd/liquidity/rank
- Large resting-order monitor /api/indicators/large-orderbook