24h Volume—Open Interest—24h Liquidations$1.36B24h Long/Short—BTC Dominance—ETH Dominance—
App
Language ▾
$ USD ▾
/api/sd/liquidity/history
GETPartialFRESH

Order-book depth history

Time series of aggregated bid and ask depth within one band for a coin, for all covered exchanges or one exchange. Each point states how many contracts it contains.

GET/api/sd/liquidity/history
Partial coverage. Collection started on 2026-11-11, so longer ranges are filled progressively. Missing buckets are absent, not interpolated; a change in `n_included` between two points means the set of contributing contracts changed.

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
coinstringRequired——Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400. Example: BTC
marketstringOptionalperpperp, spotMarket type. Perpetual and spot books are never added together.
bandstringOptional10.5, 1, 2Distance from mid price in percent.
rangestringOptional24h24h, 7d, 30dLook-back range: 24h (30-minute points), 7d (2-hour points) or 30d (6-hour points).
exchangestringOptional——One exchange id covered for this market (for example `gate`). Default: all exchanges. An exchange that is not covered returns 400.

Example request

curl -s "https://www.coinboss.com/api/sd/liquidity/history?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.

FieldTypeUnitDescription
successboolean—true when the request succeeded. On failure the body is `{ success: false, code, error, request_id }`.
schemastring—Schema id of this response. It changes only when an existing field changes meaning or type.
nownumbermsServer time when the response was built.
coinstring—Coin symbol (upper case).
marketstring—`perp` or `spot`.
band_pctnumber%Band selected: distance from mid.
rangestring—Look-back range applied.
exchangestring|null—Exchange id (lower case).
interval_snumbersSpacing of the points.
pointsarray—Series points, oldest first.
points[]object—Series points, oldest first.
points[].tnumbermsStart of the time bucket.
points[].bid_depth_usdnumberUSDResting bid notional between mid and the lower band edge. A lower bound when `complete` is false.
points[].ask_depth_usdnumberUSDResting ask notional between mid and the upper band edge. A lower bound when `complete` is false.
points[].n_includednumber—Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value.
points[].n_rowsnumber—Rows found, including stale ones.
points[].midnumberUSD(best bid + best ask) ÷ 2, price of one coin.
points[].uses_aggregated_bucketsboolean—True when an included row used price-aggregated buckets, which makes the sum a lower bound.
points_expectednumber—Number of points the range holds when complete.
first_tnumbermsTime of the first point returned.
last_tnumbermsTime of the last point returned.
exchange_pointsobject—Number of points each exchange appears in (the key is the exchange id). dynamic keys: deribit,aster,backpack,bitfinex,bitget,bitunix
exchange_points.{*}number—Number of points each exchange appears in (the key is the exchange id).
coverageobject—What is and is not included in the numbers. Compare this before comparing totals with another source.
coverage.included_exchangesarray—Sources whose fresh data is included.
coverage.included_exchanges[]string—Sources whose fresh data is included.
coverage.unavailablearray—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_excludedarray—Rows left out because their last update is outside the fresh window. empty in the samples used to generate this table
methodobject—Plain-text statement of the formulas used for this response, one entry per field.
method.bid_depth_usdstring—Formula note for `bid_depth_usd`, plain text.
method.ask_depth_usdstring—Formula note for `ask_depth_usd`, plain text.
method.completestring—Formula note for `complete`, plain text.
method.historystring—Formula note for `history`, plain text.
method.exchange_pointsstring—Formula note for `exchange_points`, plain text.
metaobject—Lineage and freshness of this response.
meta.schemastring—Schema id of this response. It changes only when an existing field changes meaning or type.
meta.sourcearray—Upstream public endpoints the data was collected from.
meta.source[]object—Upstream public endpoints the data was collected from.
meta.source[].exchangestring—Exchange id (lower case).
meta.source[].marketstring—`perp` or `spot`.
meta.source[].endpointstring—Public endpoint of the source the collector reads (shown for lineage; clients never call it).
meta.observed_atnull—Timestamp given by the source for the data.
meta.received_atnumbermsTime the CoinBoss collector received the data.
meta.fetched_atnumbermsTime this response was assembled.
meta.windowstring—Time window the numbers cover.
meta.qualitystring—FRESH, PARTIAL, STALE, BROKEN or UNAVAILABLE, judged from data timestamps and coverage.
meta.is_staleboolean—True when the data is older than its fresh window.
meta.cache_ttl_snumbersCache lifetime of this response.
meta.fallbackstring—What the endpoint returns when the collector or a source fails.
meta.collector_heartbeat_age_snumbersSeconds since the collector last reported that it is running.

Generated 2026-11-11 23:00 UTC from 3 real responses.

Example response

/api/sd/liquidity/history?coin=BTC · Real response captured 2026-11-13 04:02:45 UTC. Long arrays and maps are shortened for display: points had 48 items; meta.source had 19 items; exchange_points had 19 items; coverage.included_exchanges had 19 items.

  • {
    • "success": true,
    • "schema": "coinboss.sd.liquidity/1",
    • "now": 1794542565889,
    • "coin": "BTC",
    • "market": "perp",
    • "band_pct": 1,
    • "range": "24h",
    • "exchange": null,
    • "interval_s": 1800,
    • "points": [
      • { … 7 },
      • { … 7 }
      ],
    • "points_expected": 48,
    • "first_t": 1794457800000,
    • "last_t": 1794542400000,
    • "exchange_points": {
      • "deribit": 96,
      • "aster": 48
      },
    • "coverage": {
      • "included_exchanges": [ … 8 ],
      • "unavailable": [],
      • "stale_excluded": []
      },
    • "method": {
      • "bid_depth_usd": "sum of resting bid notional with price >= mid * (1 - band%), in USD; notional = price * size * contract_value (inverse contracts: size * contract_value); USDT /…",
      • "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; when false the depth values are lower b…",
      • "history": "sd_book_hist keeps the first snapshot of every 15-minute bucket per contract; each returned point takes, per contract, the first stored snapshot inside the poin…",
      • "exchange_points": "number of returned points in which each exchange had a row that was complete for the band; a changing venue set moves the aggregate, so compare n_included acros…"
      },
    • "meta": {
      • "schema": "coinboss.sd.liquidity/1",
      • "source": [ … 2 ],
      • "observed_at": null,
      • "received_at": 1794542400000,
      • "fetched_at": 1794542565889,
      • "window": "24h",
      • "quality": "FRESH",
      • "is_stale": false,
      • "cache_ttl_s": 120,
      • "fallback": "history is append-only (first snapshot of each 15-minute bucket per contract, 30-day retention); buckets the collector missed are simply absent, never interpola…",
      • "collector_heartbeat_age_s": 3
      }
    }

Verified samples

Besides the example above, the probe calls this endpoint with these parameters and checks the schema each time.

ParametersHTTPLatencyResult
band=2&coin=ETH&market=spot2006 msPass FRESH
coin=SOL&exchange=gate2002 msPass FRESH
band=3&coin=BTC4001 msPass 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
2m
Edge micro-cache
10s
Update frequency
A snapshot is stored every 15 minutes per contract; each point uses the earliest snapshot in its bucket (a point-in-time value, not an average).
Window
24h / 7d / 30d.
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; `range` bounds the number of points (48 / 84 / 120).
Sorting
Time ascending.
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.
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 04:02:45 UTCHTTP 20012 msSchema matchesNewest data point 3m old

Collection started on 2026-11-11, so longer ranges are filled progressively. Missing buckets are absent, not interpolated; a change in `n_included` between two points means the set of contributing contracts changed.

Availability, last 30 days

100% of 408 checks passed

Errors

Failed calls share one shape on every endpoint. The full list is on the errors page. Errors and rate limits →

CodeHTTPMeaningWhat to do
INVALID_PARAM400A 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.
UNAUTHORIZED401The `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.
FORBIDDEN403The route is not part of the public API (internal or account-only).Do not retry.
NOT_FOUND404Unknown route, or the requested coin / exchange / fund does not exist.Do not retry; check the path and identifiers against the catalog.
RATE_LIMITED429More requests than the per-minute limit. `Retry-After` gives the seconds to wait.Wait for `Retry-After`, then retry with backoff.
INTERNAL500Unexpected 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_FAILED503The 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.
UNAVAILABLE501 / 503The 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_FAILED200Some 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/liquidity/historyPartial
Parameters

string — Coin symbol, case-insensitive (for example `BTC`). Missing or malformed values return 400.

string · default perp — Market type. Perpetual and spot books are never added together.

string · default 1 — Distance from mid price in percent.

string · default 24h — Look-back range: 24h (30-minute points), 7d (2-hour points) or 30d (6-hour points).

string — One exchange id covered for this market (for example `gate`). Default: all exchanges. An exchange that is not covered returns 400.

Request URLhttps://www.coinboss.com/api/sd/liquidity/history?coin=BTC
Choose an endpoint and press “Send request”. The response, headers and timing will appear here.