What changed in the API, the current version and the compatibility rules.
v1Current version
2026.11.12Catalog revision
Versioning and compatibility
Versioning
The public API is version v1. The path prefix is `/api` and does not carry a version number.
The catalog has its own date-based version (`catalog_version`, for example 2026.11.11). It changes whenever endpoints, parameters or documentation change.
Each response of the self-data endpoints carries a `schema` id (for example `sd.oi.v1`). A new id is issued only when an existing field changes meaning or type.
Compatibility
Adding endpoints, optional parameters, response fields, enum values or exchanges is a non-breaking change and can happen at any time. Clients must ignore fields they do not know.
Removing or renaming a field, changing its type or unit, or making an optional parameter required is a breaking change. It is announced here before it ships.
Corrections are the exception: a fix for a wrong number, or for invalid input that used to be accepted silently, ships immediately and is listed here on the day it goes live, marked as breaking when client code may need to change.
Numbers can change because coverage improves (a new exchange or contract type is added). Coverage is always reported in the response, so compare `coverage` before comparing totals.
Missing data is returned as `null` and listed under `coverage.unavailable`; it is never replaced by 0 or an estimate. Code that treats `null` as 0 will be wrong.
Deprecation
Endpoints marked `legacy` keep working, but new work should use the listed replacement.
A legacy endpoint is removed no sooner than 90 days after its deprecation entry appears in this changelog.
Endpoints marked `beta` serve site pages; their field set can change without the 90-day notice, and every change is still listed here.
Changes
Added2026.11.12Backward compatible
`/api/currency/ex-table`: `market=perpetual`, `delivery` and `all`, plus one status vocabulary
New values of `market`: `perpetual` (perpetual contracts), `delivery` (dated futures) and `all` (spot, perpetual and delivery markets of the coin in one list). They return one row per market and number `rank` inside the requested view.
Every per-market row carries `market_status` (`ACTIVE`, `EXPIRING`, `EXPIRED`, `NO_QUOTE`, `STALE`), `reason_code` (`NO_QUOTE`, `EXPIRED`, `STALE`, `UNAVAILABLE` or null), `source_at`, `quality`, `is_stale`, `expires_in_s`, `symbol` and `base`. The state is derived from the contract specification of the exchange (expiry) and from the time the ticker was received. `status` and `status_reason` are unchanged.
`EXPIRING` marks a contract that still trades and expires within 24 hours (`meta.expiring_window_s`). Rows that are not `ACTIVE` or `EXPIRING` return `price: null`; no price is carried over from an earlier quote or from another contract.
`meta` adds `market_status_counts`, `type_counts` and `type_rankable`. The row order is the same for every caller: rankable rows by `volume_usd` descending, then rows without a quote, expired contracts last.
Added2026.11.12Backward compatible
`/api/liquidation-events` adds event / account counts and BTC high, low and range
New fields on every row: `btc_high`, `btc_low`, `btc_range` (USD, high − low) and `btc_range_pct` ((high − low) / low × 100), with `btc_range_meta`. Prices are the median of the UTC daily high / low on Binance (BTC/USDT), Coinbase (BTC/USD) and Kraken (BTC/USD) spot. The fields are null unless all three venues have a final daily candle.
New fields on `coinboss` rows: `liquidation_count` (de-duplicated liquidation events; not people) and `account_count` (distinct liquidated accounts on exchanges that expose an account identifier, currently Hyperliquid only; `quality` is `PARTIAL`), each with a `_meta` object giving source, window, quality and coverage. Both are null on baseline rows.
CoinBoss does not publish a liquidated-trader (people) count; `coverage.metrics.people_count.quality` is `UNAVAILABLE`. `liquidated_traders` and `btc_amplitude` are unchanged: they stay the text recorded in the third-party source and are not copied into the new fields.
Changed2026.11.12Backward compatible
`/api/currency/ex-table`: per-contract rows carry their own quote and a `status`
With `group=pair`, every contract row now uses the ticker of that contract. Before, only the main contract of each exchange had a price and the other rows returned `price: null`.
New row fields with `group=pair` and `market=spot`: `status` (`active`, `no_quote`, `not_provided`, `expired`), `status_reason`, `market_type`, `expiry_ts`, `expiry_date`, `native_symbol`, `quote`, `margin_type`, `price_source`, `price_at` and `rank`; the response adds `meta` (freshness window, volume window and unit, sort rule, row counts per status).
Rows that are not `active` return `price: null` and are never filled from another contract. `volume_usd` on such rows is `0` only when the exchange reports zero 24h turnover, otherwise `null`.
Order with `group=pair`: `active` rows first by `volume_usd` descending (these carry `rank`), then rows without a live quote by `oi_usd` descending, expired contracts last. `contract_type` now follows the exchange contract specification, so dated contracts on Deribit, Bybit, Gate and KuCoin are reported as `delivery`; `expiry` is set for all of them.
Requests without `group` return the same rows and fields as before.
Changed2026.11.12Backward compatible
`/api/liquidation-events` returns the Top 10 with a `source` field
This corrects the 2026-11-11 entry below. The historical baseline rows (third-party public historical records) are served again, as recorded and without recalculation.
Rows recorded by CoinBoss are UTC daily totals from its own collectors. A day is added only when its total is greater than the 10th place of the list at that time. Every row carries `source` (`historical_baseline` or `coinboss`) and `basis`.
The list is sorted by `total_usd` and returns 10 rows. New fields: `data[].total_usd` (same value as `amount_usd`), `data[].source`, `data[].basis` and `threshold_usd`. `coverage` is split into `coverage.baseline` and `coverage.coinboss`; the `coverage.source`, `coverage.from` and `coverage.note` fields introduced on 2026-11-11 moved under them.
Changed2026.11.12Backward compatible
Upstream failures answer HTTP 503 and keep the JSON error body
Failed requests that used to answer HTTP 502 or 504 now answer 503 with a `Retry-After` header. The CDN in front of the API replaced the body of 502 and 504 answers with its own text, which removed `code` and `request_id`; a 503 passes through unchanged. The `code` values are the same as before.
A failing upstream source behind one endpoint no longer affects other endpoints: the gateway retries another instance only on connection errors and timeouts.
`/api/sd/options/*` and `/api/sd/cme/overview` accept coin names written in Chinese characters. A coin without such a market gets HTTP 200 with `null` aggregates instead of 400.
Funding settlement history: gaps inside the 30-day window are detected and refilled for the 150 most traded coins on Bybit, OKX, Gate and Bitget (40 on HTX), so `cum_7d` and `cum_30d` are complete for more coins.
Fixed2026.11.11Backward compatible
Liquidation-variability index repaired; unavailable source answers 503
`/api/indicators/cdri`: the daily series was empty because the day grouping read the millisecond timestamp as seconds. It now returns up to 90 complete UTC days of liquidation totals; `current.days` (new field) is the number of days used, and `current.cdri` / `current.liqCV` are `null` when fewer than two days exist.
`/api/indicators/reddit-subs`: answers HTTP 503 with code `UNAVAILABLE` while its source refuses requests, instead of HTTP 500. A subscriber count is stored only when the source returns a positive number.
Error bodies of HTTP 5xx answers no longer carry upstream error text in the legacy `msg` field; it now holds the same generic message as `error`.
Fixed2026.11.11Breaking
Records that stopped updating are flagged and left out of totals
`/api/coins/all` and `/api/coins/search`: a coin record not updated for more than 48 hours returns `market_cap` and `mcap_rank` as `null` with `is_stale: true`, and sorts after all current rows. The rule in effect is echoed as `stale_rule`.
`/api/derivatives/coins-full`: exactly one row per coin. A symbol shared by several coin records used to produce one row per record; the row now carries the name, market cap and rank of the largest record updated within 48 hours, or `null` when there is none. `mcap_rank` is a new field.
`/api/reserves/overview`: every row has `updated_at` and `is_stale`. `total` now sums only exchanges updated within 36 hours; the previous definition is kept as `total_including_stale`, and the excluded exchanges are listed in `stale_exchanges`.
`/api/margin/rates` and `/api/margin-fee/matrix`: assets and cells whose rate stopped updating carry `is_stale: true`; thresholds and counts are returned at the top level.
Daily global market-cap snapshots from 2026-10-28 to 2026-11-11 were recomputed after two records with an impossible market cap (larger than Bitcoin) were found in the sum. The collectors now store `null` for such values.
Changed2026.11.11Backward compatible
Source outages are reported in the response instead of failing or looking current
`/api/indicators/mempool/pools`: when the mining-pool source does not answer, the last stored result is returned with `stale: true`, `cached_at` and `stale_reason` instead of HTTP 500.
`/api/etf/funds`: new `frozen_fields` object naming the fund-level fields whose source stopped publishing on 2026-10-08, with the date each value refers to.
`/api/indicators/halving`: new `current_difficulty` object (`value`, `as_of`, `source`). `difficulty` (retarget progress) stays `null` while its source is unavailable.
`/api/browser/detect`: a chain lookup that failed is no longer reported as an address without activity. `kind` is `lookup_failed` when no chain could be queried.
`/api/currency/flows`: the documentation now lists the 22 windows the endpoint really serves (5 minutes to 1 year).
Changed2026.11.11Breaking
Unsupported parameter values return 400 instead of default data
`/api/derivatives/kline`: `interval=4h` returns real 4-hour candles built from 1h candles on UTC boundaries (it used to return 1h candles). Any interval other than `1h`, `4h` or `1d` returns 400.
Options endpoints under `/api/options/`: an unsupported `currency` returns 400 instead of BTC data, and `coin` is accepted as an alias on all seven endpoints.
`/api/etf/flows`, `/api/etf/detail`, `/api/etf/funds` and `/api/etf/holdings`: an unsupported `asset` returns 400 instead of BTC data.
`/api/liquidations/coins`: an unsupported `range` returns 400 instead of 24h data, and the window in effect is echoed as `range`.
`limit` is capped at 1000 on `/api/liquidations`, `/api/liquidations/largest` and `/api/derivatives/coins-full`. A non-numeric `limit` uses the default instead of failing.
Fixed2026.11.11Breaking
Daily volume and research statistics corrected
`/api/volume/coin`: `daily_30d` added up every rolling-24h snapshot of a day and overstated daily volume about 24 times. It now takes the last snapshot of each UTC day.
`/api/research/stats` with `topic=derivatives`: `volume_24h_usd` had the same overstatement and is corrected.
`avg_funding_rate_pct` in the same response is now a percentage, about 100 times the raw fraction it returned before. Adjust any code that multiplied it by 100.
Fixed2026.11.11Backward compatible
Older market endpoints ignore rows that stopped updating
Rows are counted only while they are current: tickers within 1 hour, open interest within 3 hours (CME: 120 hours), funding within 4 hours, long/short ratios within 24 hours.
Totals are slightly lower and some lists are shorter. Contracts that stopped trading show `null` prices instead of their last value.
Fixed2026.11.11Backward compatible
Multiplier contracts matched to their base coin
`/api/funding/coin`, `/api/funding/history`, `/api/funding/chart` and `/api/ls/coin` now match contracts quoted in multiples of a coin (for example `1000PEPE`) to the base coin, so these coins list more exchanges.
Added2026.11.11Backward compatible
Options data from six venues
New `/api/sd/options/overview`, `/api/sd/options/expiries`, `/api/sd/options/strikes`, `/api/sd/options/chain` and `/api/sd/options/history`.
Open interest, 24h notional volume, put/call ratios, max pain, ATM IV, 25-delta skew and the IV term structure are computed by CoinBoss from the contract lists of Deribit, Binance, Bybit, OKX, Gate and Coincall.
Notional volume and premium turnover are separate fields and are never added together. Columns a venue does not publish are `null` and listed under `coverage.field_gaps`.
History is hourly and starts on 2026-11-11; earlier hours are not back-filled.
Added2026.11.11Backward compatible
Spot ETF, CME and CFTC data from primary publications
New `/api/sd/etf/overview`, `/api/sd/etf/funds` and `/api/sd/etf/history`, built from issuer disclosures. Totals cover the funds CoinBoss can collect; every other fund is listed with the reason, and `totals_scope` is always `covered_funds_only`.
Fund flow is computed by CoinBoss from shares outstanding and NAV (or net assets and NAV). The formula used is returned per fund in `flow_method`.
New `/api/sd/cme/overview` (daily volume and open interest of eight CME products) and `/api/sd/cme/cot` (weekly CFTC positioning by trader category).
CME settlement prices are not collected yet. USD figures use a labelled reference price (`price_src`), and the overview is marked PARTIAL for that reason.
Added2026.11.11Backward compatible
Order-book depth and slippage
New `/api/sd/liquidity`, `/api/sd/liquidity/history` and `/api/sd/liquidity/rank`.
Depth within ±0.5 %, ±1 % and ±2 % of mid and the slippage of 10k / 100k / 1M USD market orders are computed from real order-book snapshots of 24 exchanges, for perpetual and spot markets separately.
A snapshot that does not reach a band is flagged `complete: false`, reported as a lower bound and left out of the aggregate. `n_included` tells how many books a total contains.
`/api/indicators/large-orderbook` is a model output, not an order book; use the new endpoints for resting liquidity.
Added2026.11.11Backward compatible
Basis from exchange mark and index prices
New `/api/sd/basis`, `/api/sd/basis/history` and `/api/sd/basis/rank`.
Perpetual basis = (mark − index) ÷ index × 100 on the same exchange; spot-perpetual basis compares the perpetual with the spot market of the same exchange; delivery contracts add an annualised value.
Aggregates are given OI-weighted, volume-weighted and as a median. Rows that fail the inclusion rules are still returned with `excluded_reason`.
Hourly history starts on 2026-11-11.
Changed2026.11.11Backward compatible
Icon maps use the public site origin
`/api/coin-icons` and `/api/exchange-icons` return icon URLs on `https://www.coinboss.com`, the same origin as every other public endpoint. The paths (`/api/coin-icon/{coin}`, `/api/exchange-icon/{exchange}`) are unchanged.
Deprecated2026.11.11Backward compatible
`/api/basis/list` and `/api/cftc/cot` marked legacy
Use `/api/sd/basis/rank` instead of `/api/basis/list`, and `/api/sd/cme/cot` instead of `/api/cftc/cot`. The legacy endpoints keep working.
Changed2026.11.11Backward compatible
`/api/liquidation-events` now serves CoinBoss records only
The list is built from liquidation orders CoinBoss received from exchange feeds. Its history starts on 2026-08-19; earlier dates return no rows.
Field names and types are unchanged.
Removed2026.11.11Backward compatible
Operational endpoints are no longer reachable from the internet
`/api/health/alerts`, `/api/health/server`, `/api/health/history` and `/api/health/ch-read` answer 404 for public requests. They were never part of the public API.
Use `/api/meta/status` for service status and `/api/meta/quality` for data freshness.
Added2026.11.11Backward compatible
Developer center and machine-readable API metadata
New `/api/meta/catalog`, `/api/meta/endpoint`, `/api/meta/status`, `/api/meta/quality`, `/api/meta/changelog` and `/api/meta/openapi`.
Field tables and example responses in the documentation are generated from real responses by an API probe that calls every public endpoint every 5 minutes.
Endpoint status (available / partial / degraded / down / unavailable) now comes from those real calls, not from process state.
Changed2026.11.11Backward compatible
Uniform error body and request ids
Every response carries an `X-Request-Id` header; error bodies repeat it as `request_id`.
Error bodies are now `{ success: false, code, error, request_id }` on all endpoints. `error` stays a string, so existing clients keep working.
Unknown `/api/*` routes answer JSON 404 (`NOT_FOUND`) instead of an HTML page.
HTTP 429 responses include `Retry-After`.
Messages of 5xx errors are generic; internal details are no longer echoed.
Added2026.11.11Backward compatible
Self-data endpoints with coverage and quality in every response
New `/api/sd/oi`, `/api/sd/funding`, `/api/sd/liquidations`, `/api/sd/volume`, `/api/sd/ls`, `/api/sd/coin` and `/api/sd/quality`.
Open interest reports USDT / USDC / coin-margined / delivery contracts separately and states which venues report double-sided figures.
Funding is returned raw, with its interval, normalised to 8h and annualised; venues whose contract is not live are excluded and listed.
Deprecated2026.11.11Backward compatible
`/api/market/long-short` marked legacy
Use `/api/market/long-short-v2` for the list view or `/api/sd/ls` for per-exchange account / position / taker ratios.
Changed2026.10.31Backward compatible
Icon fields return same-origin paths
Fields such as `image_url` / `icon` now contain a CoinBoss path (`/api/coin-icon/...`) instead of a third-party URL.
A coin without a verified icon returns `null`; clients should render their own placeholder.
Fixed2026.10.24Backward compatible
Stale rows no longer enter aggregates
Totals for open interest, funding and long/short only use rows updated inside the freshness window (longer for CME, which publishes daily).
Delisted contracts stop contributing to totals once their last update leaves the window.
Legacy endpoints
Kept for compatibility. They keep working; new integrations should use the replacement.
Kept for existing integrations. Use `/api/market/long-short-v2` (adds an exchange filter) or `/api/sd/ls` (per-exchange, account / position / taker kept separate).
`apr_pct` is `basis_pct × 3 × 365`, a simple extrapolation of the current perpetual basis as if it were paid every 8 hours; it is not a funding or delivery yield. `/api/sd/basis` reports mark-index, spot-perp and delivery basis separately.