Che cosa è cambiato nell'API, la versione attuale e le regole di compatibilità.
v1Versione attuale
2026.11.12Revisione del catalogo
Versionamento e compatibilità
Versionamento
L'API pubblica è alla versione v1. Il prefisso del percorso è `/api` e non contiene un numero di versione.
Il catalogo ha una propria versione basata sulla data (`catalog_version`, per esempio 2026.11.11). Cambia ogni volta che cambiano endpoint, parametri o documentazione.
Ogni risposta degli endpoint del livello dati proprio contiene un ID `schema` (per esempio `sd.oi.v1`). Un nuovo ID viene emesso solo quando un campo esistente cambia significato o tipo.
Compatibilità
L'aggiunta di endpoint, parametri facoltativi, campi di risposta, valori di enumerazione o exchange è una modifica retrocompatibile e può avvenire in qualsiasi momento. I client devono ignorare i campi che non conoscono.
La rimozione o la ridenominazione di un campo, la modifica del suo tipo o della sua unità, oppure rendere obbligatorio un parametro facoltativo è una modifica incompatibile. Viene annunciata qui prima del rilascio.
Le correzioni sono l'eccezione: la correzione di un numero errato, o di un input non valido che in passato veniva accettato senza segnalazioni, viene rilasciata immediatamente ed è elencata qui il giorno stesso dell'entrata in produzione, contrassegnata come incompatibile quando il codice dei client può richiedere modifiche.
I numeri possono cambiare perché la copertura migliora (viene aggiunto un nuovo exchange o tipo di contratto). La copertura è sempre riportata nella risposta, quindi confrontare `coverage` prima di confrontare i totali.
I dati mancanti vengono restituiti come `null` ed elencati in `coverage.unavailable`; non vengono mai sostituiti da 0 o da una stima. Il codice che tratta `null` come 0 produrrà risultati errati.
Deprecazione
Gli endpoint contrassegnati come `legacy` continuano a funzionare, ma per i nuovi sviluppi va usato il sostituto indicato.
Un endpoint legacy viene rimosso non prima di 90 giorni dalla comparsa della relativa voce di deprecazione in questo registro delle modifiche.
Gli endpoint contrassegnati come `beta` alimentano le pagine del sito; il loro insieme di campi può cambiare senza il preavviso di 90 giorni, e ogni modifica viene comunque elencata qui.
Modifiche
Aggiunto2026.11.12Retrocompatibile
`/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.
Aggiunto2026.11.12Retrocompatibile
`/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.
Modificato2026.11.12Retrocompatibile
`/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.
Modificato2026.11.12Retrocompatibile
`/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.
Modificato2026.11.12Retrocompatibile
Gli errori della fonte a monte rispondono con HTTP 503 e conservano il corpo di errore JSON
Le richieste non riuscite che prima rispondevano con HTTP 502 o 504 ora rispondono con 503 e un header `Retry-After`. La CDN posta davanti all'API sostituiva il corpo delle risposte 502 e 504 con un proprio testo, eliminando così `code` e `request_id`; un 503 passa invece inalterato. I valori di `code` sono gli stessi di prima.
Il malfunzionamento di una fonte a monte dietro un endpoint non si ripercuote più sugli altri endpoint: il gateway riprova su un'altra istanza solo in caso di errori di connessione e timeout.
`/api/sd/options/*` e `/api/sd/cme/overview` accettano nomi di monete scritti in caratteri cinesi. Una moneta priva di un mercato di questo tipo riceve HTTP 200 con aggregati `null` anziché 400.
Storico dei regolamenti del finanziamento: le lacune all'interno della finestra di 30 giorni vengono rilevate e colmate per le 150 monete più scambiate su Bybit, OKX, Gate e Bitget (40 su HTX), così `cum_7d` e `cum_30d` sono completi per un numero maggiore di monete.
Corretto2026.11.11Retrocompatibile
Indice di variabilità delle liquidazioni riparato; con fonte non disponibile la risposta è 503
`/api/indicators/cdri`: la serie giornaliera era vuota perché il raggruppamento per giorno leggeva il timestamp in millisecondi come secondi. Ora restituisce fino a 90 giorni UTC completi di totali delle liquidazioni; `current.days` (nuovo campo) è il numero di giorni utilizzati, mentre `current.cdri` / `current.liqCV` sono `null` quando esistono meno di due giorni.
`/api/indicators/reddit-subs`: risponde con HTTP 503 e codice `UNAVAILABLE` finché la sua fonte rifiuta le richieste, anziché con HTTP 500. Il numero di iscritti viene memorizzato solo quando la fonte restituisce un numero positivo.
I corpi di errore delle risposte HTTP 5xx non riportano più il testo d'errore della fonte a monte nel campo legacy `msg`; questo campo contiene ora lo stesso messaggio generico di `error`.
Corretto2026.11.11Incompatibile
I record che hanno smesso di aggiornarsi vengono contrassegnati ed esclusi dai totali
`/api/coins/all` e `/api/coins/search`: un record di moneta non aggiornato da oltre 48 ore restituisce `market_cap` e `mcap_rank` come `null` con `is_stale: true` ed è ordinato dopo tutte le righe aggiornate. La regola in vigore è riportata in `stale_rule`.
`/api/derivatives/coins-full`: esattamente una riga per moneta. Un simbolo condiviso da più record di monete produceva in passato una riga per record; ora la riga riporta nome, capitalizzazione di mercato e posizione in classifica del record più grande aggiornato nelle ultime 48 ore, oppure `null` quando non ce n'è alcuno. `mcap_rank` è un nuovo campo.
`/api/reserves/overview`: ogni riga ha `updated_at` e `is_stale`. `total` ora somma solo gli exchange aggiornati nelle ultime 36 ore; la definizione precedente è mantenuta come `total_including_stale` e gli exchange esclusi sono elencati in `stale_exchanges`.
`/api/margin/rates` e `/api/margin-fee/matrix`: gli asset e le celle il cui tasso ha smesso di aggiornarsi riportano `is_stale: true`; soglie e conteggi sono restituiti al primo livello.
Le istantanee giornaliere della capitalizzazione di mercato globale dal 2026-10-28 al 2026-11-11 sono state ricalcolate dopo che nella somma erano stati trovati due record con una capitalizzazione di mercato impossibile (superiore a quella di Bitcoin). I collector ora memorizzano `null` per questi valori.
Modificato2026.11.11Retrocompatibile
Le interruzioni delle fonti vengono segnalate nella risposta, anziché causare un errore o far apparire i dati come aggiornati
`/api/indicators/mempool/pools`: quando la fonte sulle mining pool non risponde, viene restituito l'ultimo risultato memorizzato con `stale: true`, `cached_at` e `stale_reason` anziché HTTP 500.
`/api/etf/funds`: nuovo oggetto `frozen_fields` che indica i campi a livello di fondo la cui fonte ha smesso di pubblicare il 2026-10-08, con la data a cui si riferisce ciascun valore.
`/api/indicators/halving`: nuovo oggetto `current_difficulty` (`value`, `as_of`, `source`). `difficulty` (avanzamento del retarget) resta `null` finché la sua fonte non è disponibile.
`/api/browser/detect`: una ricerca su una chain non riuscita non viene più segnalata come un indirizzo senza attività. `kind` è `lookup_failed` quando non è stato possibile interrogare alcuna chain.
`/api/currency/flows`: la documentazione ora elenca le 22 finestre che l'endpoint serve realmente (da 5 minuti a 1 anno).
Modificato2026.11.11Incompatibile
I valori di parametro non supportati restituiscono 400 anziché i dati predefiniti
`/api/derivatives/kline`: `interval=4h` restituisce vere candele a 4 ore costruite dalle candele a 1h sui confini UTC (in passato restituiva candele a 1h). Qualsiasi intervallo diverso da `1h`, `4h` o `1d` restituisce 400.
Endpoint delle opzioni sotto `/api/options/`: un valore `currency` non supportato restituisce 400 anziché i dati di BTC, e `coin` è accettato come alias su tutti e sette gli endpoint.
`/api/etf/flows`, `/api/etf/detail`, `/api/etf/funds` e `/api/etf/holdings`: un valore `asset` non supportato restituisce 400 anziché i dati di BTC.
`/api/liquidations/coins`: un valore `range` non supportato restituisce 400 anziché i dati a 24h, e la finestra in vigore è riportata in `range`.
`limit` è limitato a 1000 su `/api/liquidations`, `/api/liquidations/largest` e `/api/derivatives/coins-full`. Un `limit` non numerico usa il valore predefinito anziché generare un errore.
Corretto2026.11.11Incompatibile
Corretti il volume giornaliero e le statistiche di ricerca
`/api/volume/coin`: `daily_30d` sommava tutte le istantanee mobili a 24h di un giorno e sovrastimava il volume giornaliero di circa 24 volte. Ora prende l'ultima istantanea di ogni giorno UTC.
`/api/research/stats` con `topic=derivatives`: `volume_24h_usd` presentava la stessa sovrastima ed è stato corretto.
`avg_funding_rate_pct` nella stessa risposta è ora una percentuale, circa 100 volte la frazione grezza restituita in precedenza. Adeguare il codice che lo moltiplicava per 100.
Corretto2026.11.11Retrocompatibile
Gli endpoint di mercato meno recenti ignorano le righe che hanno smesso di aggiornarsi
Le righe vengono conteggiate solo finché sono aggiornate: ticker entro 1 ora, open interest entro 3 ore (CME: 120 ore), finanziamento entro 4 ore, rapporti long/short entro 24 ore.
I totali sono leggermente più bassi e alcuni elenchi sono più corti. I contratti che hanno smesso di essere scambiati mostrano prezzi `null` anziché il loro ultimo valore.
Corretto2026.11.11Retrocompatibile
Contratti con moltiplicatore abbinati alla moneta base
`/api/funding/coin`, `/api/funding/history`, `/api/funding/chart` e `/api/ls/coin` ora abbinano alla moneta base i contratti quotati in multipli di una moneta (per esempio `1000PEPE`), per cui queste monete elencano più exchange.
Aggiunto2026.11.11Retrocompatibile
Dati sulle opzioni da sei exchange
Nuovi `/api/sd/options/overview`, `/api/sd/options/expiries`, `/api/sd/options/strikes`, `/api/sd/options/chain` e `/api/sd/options/history`.
Open interest, volume nozionale a 24h, rapporti put/call, max pain, IV ATM, skew 25-delta e struttura a termine dell'IV sono calcolati da CoinBoss dagli elenchi dei contratti di Deribit, Binance, Bybit, OKX, Gate e Coincall.
Il volume nozionale e il controvalore dei premi sono campi separati e non vengono mai sommati. Le colonne che un exchange non pubblica sono `null` ed elencate in `coverage.field_gaps`.
Lo storico è orario e parte dal 2026-11-11; le ore precedenti non vengono ricostruite.
Aggiunto2026.11.11Retrocompatibile
Dati su ETF spot, CME e CFTC dalle pubblicazioni primarie
Nuovi `/api/sd/etf/overview`, `/api/sd/etf/funds` e `/api/sd/etf/history`, costruiti dalle informative degli emittenti. I totali coprono i fondi che CoinBoss è in grado di raccogliere; ogni altro fondo è elencato con il motivo e `totals_scope` è sempre `covered_funds_only`.
Il flusso dei fondi è calcolato da CoinBoss dalle quote in circolazione e dal NAV (oppure dal patrimonio netto e dal NAV). La formula usata è restituita per ciascun fondo in `flow_method`.
Nuovi `/api/sd/cme/overview` (volume giornaliero e open interest di otto prodotti CME) e `/api/sd/cme/cot` (posizionamento settimanale CFTC per categoria di trader).
I prezzi di regolamento del CME non sono ancora raccolti. I valori in USD usano un prezzo di riferimento etichettato (`price_src`) e per questo motivo la panoramica è contrassegnata come PARTIAL.
Aggiunto2026.11.11Retrocompatibile
Profondità del book degli ordini e slippage
Nuovi `/api/sd/liquidity`, `/api/sd/liquidity/history` e `/api/sd/liquidity/rank`.
La profondità entro ±0.5 %, ±1 % e ±2 % dal prezzo mid e lo slippage di ordini a mercato da 10k / 100k / 1M USD sono calcolati da istantanee reali dei book degli ordini di 24 exchange, separatamente per i mercati perpetui e spot.
Un'istantanea che non raggiunge una fascia è contrassegnata con `complete: false`, riportata come limite inferiore ed esclusa dall'aggregato. `n_included` indica quanti book contiene un totale.
`/api/indicators/large-orderbook` è il risultato di un modello, non un book degli ordini; per la liquidità presente nel book usare i nuovi endpoint.
Aggiunto2026.11.11Retrocompatibile
Base dai prezzi mark e dell'indice degli exchange
Nuovi `/api/sd/basis`, `/api/sd/basis/history` e `/api/sd/basis/rank`.
Base del perpetuo = (mark − index) ÷ index × 100 sullo stesso exchange; la base spot-perpetuo confronta il perpetuo con il mercato spot dello stesso exchange; i contratti a scadenza aggiungono un valore annualizzato.
Gli aggregati sono forniti ponderati per OI, ponderati per volume e come mediana. Le righe che non rispettano le regole di inclusione vengono comunque restituite con `excluded_reason`.
Lo storico orario parte dal 2026-11-11.
Modificato2026.11.11Retrocompatibile
Le mappe delle icone usano l'origine del sito pubblico
`/api/coin-icons` e `/api/exchange-icons` restituiscono URL delle icone su `https://www.coinboss.com`, la stessa origine di tutti gli altri endpoint pubblici. I percorsi (`/api/coin-icon/{coin}`, `/api/exchange-icon/{exchange}`) restano invariati.
Deprecato2026.11.11Retrocompatibile
`/api/basis/list` e `/api/cftc/cot` contrassegnati come legacy
Usare `/api/sd/basis/rank` al posto di `/api/basis/list` e `/api/sd/cme/cot` al posto di `/api/cftc/cot`. Gli endpoint legacy continuano a funzionare.
Modificato2026.11.11Retrocompatibile
`/api/liquidation-events` ora fornisce solo i record di CoinBoss
L'elenco è costruito dagli ordini di liquidazione che CoinBoss ha ricevuto dai feed degli exchange. Il suo storico parte dal 2026-08-19; le date precedenti non restituiscono righe.
I nomi e i tipi dei campi sono invariati.
Rimosso2026.11.11Retrocompatibile
Gli endpoint operativi non sono più raggiungibili da Internet
`/api/health/alerts`, `/api/health/server`, `/api/health/history` e `/api/health/ch-read` rispondono 404 alle richieste pubbliche. Non hanno mai fatto parte dell'API pubblica.
Usare `/api/meta/status` per lo stato del servizio e `/api/meta/quality` per la freschezza dei dati.
Aggiunto2026.11.11Retrocompatibile
Centro sviluppatori e metadati dell'API leggibili dalle macchine
Nuovi `/api/meta/catalog`, `/api/meta/endpoint`, `/api/meta/status`, `/api/meta/quality`, `/api/meta/changelog` e `/api/meta/openapi`.
Le tabelle dei campi e le risposte di esempio nella documentazione sono generate da risposte reali da una sonda dell'API che chiama ogni endpoint pubblico ogni 5 minuti.
Lo stato degli endpoint (available / partial / degraded / down / unavailable) ora deriva da queste chiamate reali, non dallo stato dei processi.
Modificato2026.11.11Retrocompatibile
Corpo di errore uniforme e ID delle richieste
Ogni risposta contiene un header `X-Request-Id`; i corpi di errore lo ripetono come `request_id`.
I corpi di errore sono ora `{ success: false, code, error, request_id }` su tutti gli endpoint. `error` resta una stringa, quindi i client esistenti continuano a funzionare.
Le route `/api/*` sconosciute rispondono con un 404 JSON (`NOT_FOUND`) anziché con una pagina HTML.
Le risposte HTTP 429 includono `Retry-After`.
I messaggi degli errori 5xx sono generici; i dettagli interni non vengono più riportati.
Aggiunto2026.11.11Retrocompatibile
Endpoint del livello dati proprio con copertura e qualità in ogni risposta
Nuovi `/api/sd/oi`, `/api/sd/funding`, `/api/sd/liquidations`, `/api/sd/volume`, `/api/sd/ls`, `/api/sd/coin` e `/api/sd/quality`.
L'open interest riporta separatamente i contratti USDT / USDC / con margine in coin / a scadenza e indica quali exchange dichiarano valori bilaterali.
Il finanziamento viene restituito grezzo, con il relativo intervallo, normalizzato a 8h e annualizzato; gli exchange il cui contratto non è attivo sono esclusi ed elencati.
Deprecato2026.11.11Retrocompatibile
`/api/market/long-short` contrassegnato come legacy
Usare `/api/market/long-short-v2` per la vista a elenco oppure `/api/sd/ls` per i rapporti per account / per posizioni / taker di ciascun exchange.
Modificato2026.10.31Retrocompatibile
I campi delle icone restituiscono percorsi della stessa origine
Campi come `image_url` / `icon` ora contengono un percorso di CoinBoss (`/api/coin-icon/...`) anziché un URL di terze parti.
Una moneta priva di un'icona verificata restituisce `null`; i client devono mostrare un proprio segnaposto.
Corretto2026.10.24Retrocompatibile
Le righe obsolete non entrano più negli aggregati
I totali di open interest, finanziamento e long/short usano solo le righe aggiornate entro la finestra di freschezza (più lunga per il CME, che pubblica ogni giorno).
I contratti rimossi dal listino smettono di contribuire ai totali non appena il loro ultimo aggiornamento esce dalla finestra.
Endpoint legacy
Mantenuti per compatibilità. Continuano a funzionare; le nuove integrazioni dovrebbero usare l'endpoint sostitutivo.
Mantenuto per le integrazioni esistenti. Usare `/api/market/long-short-v2` (aggiunge un filtro per exchange) oppure `/api/sd/ls` (per exchange, con account / posizioni / taker tenuti separati).
`apr_pct` è `basis_pct × 3 × 365`, una semplice estrapolazione della base attuale del perpetuo come se venisse pagata ogni 8 ore; non è un rendimento da finanziamento né da contratto a scadenza. `/api/sd/basis` riporta separatamente la base mark-indice, spot-perpetuo e dei contratti a scadenza.