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

Coins ranked by order-book depth

Coins ranked by aggregated order-book depth (bid + ask) within one band, with the number of contracts included and the tightest spread.

GET/api/sd/liquidity/rank

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
marketstringOptionalperpperp, spotMarket type. Perpetual and spot books are never added together.
bandstringOptional10.5, 1, 2Distance from mid price in percent.
limitintegerOptional50≥ 1 · ≤ 200Number of rows.

Example request

curl -s "https://www.coinboss.com/api/sd/liquidity/rank"

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.
marketstring—`perp` or `spot`.
band_pctnumber%Band selected: distance from mid.
limitnumber—Row limit applied.
total_coinsnumber—Coins that have at least one order-book row.
rowsarray—One row per coin.
rows[]object—One row per coin.
rows[].coinstring—Coin symbol (upper case).
rows[].bid_depth_usdnumberUSDResting bid notional between mid and the lower band edge. A lower bound when `complete` is false.
rows[].ask_depth_usdnumberUSDResting ask notional between mid and the upper band edge. A lower bound when `complete` is false.
rows[].total_depth_usdnumberUSDBid depth + ask depth of the band, used only as the ranking key.
rows[].n_includednumber—Rows included in the depth sum: fresh and complete for the band. Read it together with the depth value.
rows[].n_freshnumber—Fresh rows.
rows[].n_rowsnumber—Rows found, including stale ones.
rows[].mid_mediannumberUSDMedian mid price of the fresh rows.
rows[].spread_bps_minnumberbpTightest spread among the fresh rows.
rows[].included_exchangesarray—Sources whose fresh data is included.
rows[].included_exchanges[]string—Sources whose fresh data is included.
rows[].uses_aggregated_bucketsboolean—True when an included row used price-aggregated buckets, which makes the sum a lower bound.
rows[].ranknumber—Position in the ranking; `null` when the row has no value to rank.
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.
coverage.stale_excluded[]object—Rows left out because their last update is outside the fresh window.
coverage.stale_excluded[].exchangestring—Exchange id (lower case).
coverage.stale_excluded[].age_snumbersSeconds since the row was received.
coverage.n_fresh_rowsnumber—Fresh rows across all coins.
coverage.n_stale_rowsnumber—Stale rows across all coins.
coverage.n_incomplete_rowsnumber—Fresh rows whose snapshot does not reach the band edge.
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.aggregatestring—Formula note for `aggregate`, plain text.
method.freshstring—Formula note for `fresh`, plain text.
method.rankstring—Formula note for `rank`, 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_atnumbermsTimestamp 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/rank · Real response captured 2026-11-13 01:42:45 UTC. Long arrays and maps are shortened for display: rows had 50 items; meta.source had 23 items; coverage.stale_excluded had 22 items; rows[].included_exchanges had 19 items; coverage.included_exchanges had 23 items.

  • {
    • "success": true,
    • "schema": "coinboss.sd.liquidity/1",
    • "now": 1794534165469,
    • "market": "perp",
    • "band_pct": 1,
    • "limit": 50,
    • "total_coins": 89,
    • "rows": [
      • { … 12 },
      • { … 12 }
      ],
    • "coverage": {
      • "included_exchanges": [ … 8 ],
      • "unavailable": [],
      • "stale_excluded": [ … 2 ],
      • "n_fresh_rows": 1475,
      • "n_stale_rows": 85,
      • "n_incomplete_rows": 9
      },
    • "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…",
      • "aggregate": "per market and band: sum over rows that are fresh AND complete for that band; n_included / n_fresh is the denominator; lower_bound_* additionally adds the incom…",
      • "fresh": "a row is fresh when now - received_at <= max(3 * period_s, 300s); stale rows are listed in coverage.stale_excluded; rows older than 24h are dropped",
      • "rank": "coins ordered by bid_depth_usd + ask_depth_usd of the chosen market and band, aggregated as in aggregate; coins with no fresh complete row carry nulls and sort …"
      },
    • "meta": {
      • "schema": "coinboss.sd.liquidity/1",
      • "source": [ … 2 ],
      • "observed_at": 1794534165217,
      • "received_at": 1794534165268,
      • "fetched_at": 1794534165469,
      • "window": "latest",
      • "quality": "PARTIAL",
      • "is_stale": false,
      • "cache_ttl_s": 30,
      • "fallback": "stale rows (older than max(3 * period_s, 300s)) are left out; coins whose rows are all stale or incomplete keep their place in the list with null depth",
      • "collector_heartbeat_age_s": 5
      }
    }

Verified samples

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

ParametersHTTPLatencyResult
market=spot2006 msPass PARTIAL
band=0.5&limit=102008 msPass PARTIAL
limit=04002 msPass returns the expected error

Checked 2026-11-13 01:28:04 UTC

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
30s
Edge micro-cache
10s
Update frequency
Same collection cycle as `/api/sd/liquidity`.
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; `limit` caps the number of rows (max 200).
Sorting
`total_depth_usd` descending; coins without any complete, fresh row come last with `rank: null`.
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 01:42:45 UTCHTTP 2009 msSchema matchesNewest data point 0s old

The endpoint reports data quality PARTIAL

Availability, last 30 days

100% of 380 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/rankPartial
Parameters

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

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

integer · default 50 · min 1 · max 200 — Number of rows.

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