O que mudou na API, a versão atual e as regras de compatibilidade.
v1Versão atual
2026.11.12Revisão do catálogo
Versionamento e compatibilidade
Versionamento
A API pública está na versão v1. O prefixo de caminho é `/api` e não traz número de versão.
O catálogo tem sua própria versão baseada em data (`catalog_version`, por exemplo 2026.11.11). Ela muda sempre que os endpoints, os parâmetros ou a documentação mudam.
Cada resposta dos endpoints de coleta própria traz um ID de `schema` (por exemplo, `sd.oi.v1`). Um novo ID só é emitido quando um campo existente muda de significado ou de tipo.
Compatibilidade
Adicionar endpoints, parâmetros opcionais, campos de resposta, valores de enum ou corretoras é uma mudança retrocompatível e pode acontecer a qualquer momento. Os clientes devem ignorar os campos que não conhecem.
Remover ou renomear um campo, alterar seu tipo ou sua unidade, ou tornar obrigatório um parâmetro opcional é uma mudança incompatível. Ela é anunciada aqui antes de entrar em produção.
Correções são a exceção: a correção de um número errado, ou de uma entrada inválida que antes era aceita silenciosamente, é lançada imediatamente e listada aqui no dia em que entra em produção, marcada como incompatível quando o código do cliente pode precisar de mudanças.
Os números podem mudar porque a cobertura melhora (uma nova corretora ou um novo tipo de contrato é adicionado). A cobertura é sempre reportada na resposta; portanto, compare `coverage` antes de comparar totais.
Dados ausentes são retornados como `null` e listados em `coverage.unavailable`; nunca são substituídos por 0 nem por uma estimativa. Um código que trate `null` como 0 produzirá resultados errados.
Descontinuação
Os endpoints marcados como `legacy` continuam funcionando, mas novos desenvolvimentos devem usar o substituto indicado.
Um endpoint legado só é removido depois de decorridos pelo menos 90 dias desde que sua entrada de descontinuação apareceu neste registro de alterações.
Os endpoints marcados como `beta` atendem páginas do site; seu conjunto de campos pode mudar sem o aviso de 90 dias, e ainda assim toda mudança é listada aqui.
Alterações
Adicionado2026.11.12Retrocompatível
`/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.
Adicionado2026.11.12Retrocompatível
`/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.
Alterado2026.11.12Retrocompatível
`/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.
Alterado2026.11.12Retrocompatível
`/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.
Alterado2026.11.12Retrocompatível
Falhas da origem respondem HTTP 503 e mantêm o corpo de erro em JSON
As requisições com falha que antes respondiam HTTP 502 ou 504 agora respondem 503 com um cabeçalho `Retry-After`. A CDN à frente da API substituía o corpo das respostas 502 e 504 pelo próprio texto, o que eliminava `code` e `request_id`; um 503 passa sem alterações. Os valores de `code` são os mesmos de antes.
A falha de uma fonte de origem por trás de um endpoint não afeta mais os outros endpoints: o gateway só tenta outra instância em caso de erro de conexão ou de tempo limite esgotado.
`/api/sd/options/*` e `/api/sd/cme/overview` aceitam nomes de moedas escritos em caracteres chineses. Uma moeda sem esse mercado recebe HTTP 200 com agregados `null` em vez de 400.
Histórico de liquidações de financiamento: as lacunas dentro da janela de 30 dias são detectadas e preenchidas para as 150 moedas mais negociadas na Bybit, OKX, Gate e Bitget (40 na HTX), de modo que `cum_7d` e `cum_30d` ficam completos para mais moedas.
Corrigido2026.11.11Retrocompatível
Índice de variabilidade de liquidações corrigido; com a fonte indisponível, a resposta é 503
`/api/indicators/cdri`: a série diária estava vazia porque o agrupamento por dia lia o timestamp em milissegundos como segundos. Agora retorna até 90 dias UTC completos de totais de liquidações; `current.days` (campo novo) é o número de dias usados, e `current.cdri` / `current.liqCV` são `null` quando existem menos de dois dias.
`/api/indicators/reddit-subs`: responde HTTP 503 com o código `UNAVAILABLE` enquanto sua fonte recusar requisições, em vez de HTTP 500. O número de inscritos só é armazenado quando a fonte retorna um número positivo.
Os corpos de erro das respostas HTTP 5xx não trazem mais o texto de erro da origem no campo legado `msg`; ele agora contém a mesma mensagem genérica de `error`.
Corrigido2026.11.11Incompatível
Registros que pararam de ser atualizados são sinalizados e ficam fora dos totais
`/api/coins/all` e `/api/coins/search`: um registro de moeda sem atualização há mais de 48 horas retorna `market_cap` e `mcap_rank` como `null` com `is_stale: true` e é ordenado depois de todas as linhas atuais. A regra em vigor é repetida como `stale_rule`.
`/api/derivatives/coins-full`: exatamente uma linha por moeda. Um símbolo compartilhado por vários registros de moeda produzia uma linha por registro; agora a linha traz o nome, a capitalização de mercado e a posição do maior registro atualizado nas últimas 48 horas, ou `null` quando não há nenhum. `mcap_rank` é um campo novo.
`/api/reserves/overview`: toda linha tem `updated_at` e `is_stale`. `total` agora soma somente as corretoras atualizadas nas últimas 36 horas; a definição anterior é mantida como `total_including_stale`, e as corretoras excluídas são listadas em `stale_exchanges`.
`/api/margin/rates` e `/api/margin-fee/matrix`: os ativos e as células cuja taxa parou de ser atualizada trazem `is_stale: true`; os limiares e as contagens são retornados no nível superior.
Os snapshots diários da capitalização de mercado global de 2026-10-28 a 2026-11-11 foram recalculados depois que dois registros com uma capitalização de mercado impossível (maior que a do Bitcoin) foram encontrados na soma. Os coletores agora armazenam `null` para esses valores.
Alterado2026.11.11Retrocompatível
Indisponibilidades das fontes são reportadas na resposta, em vez de causar falha ou parecer dados atuais
`/api/indicators/mempool/pools`: quando a fonte de pools de mineração não responde, o último resultado armazenado é retornado com `stale: true`, `cached_at` e `stale_reason`, em vez de HTTP 500.
`/api/etf/funds`: novo objeto `frozen_fields`, que nomeia os campos em nível de fundo cuja fonte parou de publicar em 2026-10-08, com a data a que cada valor se refere.
`/api/indicators/halving`: novo objeto `current_difficulty` (`value`, `as_of`, `source`). `difficulty` (progresso do reajuste) permanece `null` enquanto a sua fonte está indisponível.
`/api/browser/detect`: uma consulta a uma rede que falhou não é mais reportada como um endereço sem atividade. `kind` é `lookup_failed` quando nenhuma rede pôde ser consultada.
`/api/currency/flows`: a documentação agora lista as 22 janelas que o endpoint realmente serve (de 5 minutos a 1 ano).
Alterado2026.11.11Incompatível
Valores de parâmetro não suportados retornam 400 em vez de dados padrão
`/api/derivatives/kline`: `interval=4h` retorna candles reais de 4 horas, montados a partir de candles de 1h nos limites UTC (antes retornava candles de 1h). Qualquer intervalo diferente de `1h`, `4h` ou `1d` retorna 400.
Endpoints de opções em `/api/options/`: um `currency` não suportado retorna 400 em vez de dados do BTC, e `coin` é aceito como alias em todos os sete endpoints.
`/api/etf/flows`, `/api/etf/detail`, `/api/etf/funds` e `/api/etf/holdings`: um `asset` não suportado retorna 400 em vez de dados do BTC.
`/api/liquidations/coins`: um `range` não suportado retorna 400 em vez de dados de 24h, e a janela em vigor é repetida como `range`.
`limit` é limitado a 1000 em `/api/liquidations`, `/api/liquidations/largest` e `/api/derivatives/coins-full`. Um `limit` não numérico usa o padrão em vez de falhar.
Corrigido2026.11.11Incompatível
Volume diário e estatísticas de pesquisa corrigidos
`/api/volume/coin`: `daily_30d` somava todos os snapshots de 24h móveis de um dia e superestimava o volume diário em cerca de 24 vezes. Agora ele usa o último snapshot de cada dia UTC.
`/api/research/stats` com `topic=derivatives`: `volume_24h_usd` tinha a mesma superestimação e foi corrigido.
`avg_funding_rate_pct` na mesma resposta agora é um percentual, cerca de 100 vezes a fração bruta que retornava antes. Ajuste qualquer código que o multiplicava por 100.
Corrigido2026.11.11Retrocompatível
Endpoints de mercado mais antigos ignoram linhas que pararam de ser atualizadas
As linhas são contadas somente enquanto estão atuais: tickers dentro de 1 hora, contratos em aberto dentro de 3 horas (CME: 120 horas), financiamento dentro de 4 horas, razões long/short dentro de 24 horas.
Os totais ficam ligeiramente menores e algumas listas ficam mais curtas. Os contratos que pararam de ser negociados mostram preços `null` em vez do último valor.
Corrigido2026.11.11Retrocompatível
Contratos com multiplicador associados à sua moeda base
`/api/funding/coin`, `/api/funding/history`, `/api/funding/chart` e `/api/ls/coin` agora associam à moeda base os contratos cotados em múltiplos de uma moeda (por exemplo, `1000PEPE`), de modo que essas moedas listam mais corretoras.
Adicionado2026.11.11Retrocompatível
Dados de opções de seis corretoras
Novos: `/api/sd/options/overview`, `/api/sd/options/expiries`, `/api/sd/options/strikes`, `/api/sd/options/chain` e `/api/sd/options/history`.
Contratos em aberto, volume nocional de 24h, razões put/call, max pain, IV ATM, skew de 25 delta e a estrutura a termo da IV são calculados pela CoinBoss a partir das listas de contratos de Deribit, Binance, Bybit, OKX, Gate e Coincall.
O volume nocional e o volume de prêmios são campos separados e nunca são somados. As colunas que uma corretora não publica são `null` e ficam listadas em `coverage.field_gaps`.
O histórico é horário e começa em 2026-11-11; as horas anteriores não são preenchidas retroativamente.
Adicionado2026.11.11Retrocompatível
Dados de ETFs à vista, da CME e da CFTC a partir de publicações primárias
Novos: `/api/sd/etf/overview`, `/api/sd/etf/funds` e `/api/sd/etf/history`, construídos a partir das divulgações dos emissores. Os totais abrangem os fundos que a CoinBoss consegue coletar; todos os demais fundos são listados com o motivo, e `totals_scope` é sempre `covered_funds_only`.
O fluxo dos fundos é calculado pela CoinBoss a partir das cotas em circulação e do NAV (ou do patrimônio líquido e do NAV). A fórmula usada é retornada por fundo em `flow_method`.
Novos: `/api/sd/cme/overview` (volume diário e contratos em aberto de oito produtos da CME) e `/api/sd/cme/cot` (posicionamento semanal da CFTC por categoria de trader).
Os preços de ajuste da CME ainda não são coletados. Os valores em USD usam um preço de referência rotulado (`price_src`), e por isso a visão geral é marcada como PARTIAL.
Adicionado2026.11.11Retrocompatível
Profundidade do livro de ofertas e slippage
Novos: `/api/sd/liquidity`, `/api/sd/liquidity/history` e `/api/sd/liquidity/rank`.
A profundidade dentro de ±0.5 %, ±1 % e ±2 % do preço médio e o slippage de ordens a mercado de 10k / 100k / 1M USD são calculados a partir de snapshots reais do livro de ofertas de 24 corretoras, separadamente para os mercados de perpétuos e spot.
Um snapshot que não alcança uma faixa é marcado com `complete: false`, reportado como limite inferior e deixado de fora do agregado. `n_included` informa quantos livros compõem um total.
`/api/indicators/large-orderbook` é a saída de um modelo, não um livro de ofertas; use os novos endpoints para a liquidez em espera no livro.
Adicionado2026.11.11Retrocompatível
Base a partir dos preços de marcação e do índice das corretoras
Novos: `/api/sd/basis`, `/api/sd/basis/history` e `/api/sd/basis/rank`.
Base dos perpétuos = (mark − index) ÷ index × 100 na mesma corretora; a base perpétuo vs. spot compara o perpétuo com o mercado spot da mesma corretora; os contratos com vencimento trazem também um valor anualizado.
Os agregados são fornecidos ponderados por OI, ponderados por volume e como mediana. As linhas que não passam nas regras de inclusão continuam sendo retornadas, com `excluded_reason`.
O histórico horário começa em 2026-11-11.
Alterado2026.11.11Retrocompatível
Os mapas de ícones usam a origem pública do site
`/api/coin-icons` e `/api/exchange-icons` retornam URLs de ícones em `https://www.coinboss.com`, a mesma origem de todos os demais endpoints públicos. Os caminhos (`/api/coin-icon/{coin}`, `/api/exchange-icon/{exchange}`) permanecem inalterados.
Descontinuado2026.11.11Retrocompatível
`/api/basis/list` e `/api/cftc/cot` marcados como legados
Use `/api/sd/basis/rank` em vez de `/api/basis/list` e `/api/sd/cme/cot` em vez de `/api/cftc/cot`. Os endpoints legados continuam funcionando.
Alterado2026.11.11Retrocompatível
`/api/liquidation-events` agora serve apenas registros da CoinBoss
A lista é montada a partir das ordens de liquidação que a CoinBoss recebeu dos feeds das corretoras. Seu histórico começa em 2026-08-19; datas anteriores não retornam linhas.
Os nomes e os tipos dos campos não mudaram.
Removido2026.11.11Retrocompatível
Os endpoints operacionais não são mais acessíveis pela internet
`/api/health/alerts`, `/api/health/server`, `/api/health/history` e `/api/health/ch-read` respondem 404 a requisições públicas. Eles nunca fizeram parte da API pública.
Use `/api/meta/status` para o status do serviço e `/api/meta/quality` para a atualidade dos dados.
Adicionado2026.11.11Retrocompatível
Central do desenvolvedor e metadados da API legíveis por máquina
Novos: `/api/meta/catalog`, `/api/meta/endpoint`, `/api/meta/status`, `/api/meta/quality`, `/api/meta/changelog` e `/api/meta/openapi`.
As tabelas de campos e os exemplos de resposta da documentação são gerados a partir de respostas reais por uma sonda da API que chama todos os endpoints públicos a cada 5 minutos.
O status dos endpoints (available / partial / degraded / down / unavailable) agora vem dessas chamadas reais, e não do estado dos processos.
Alterado2026.11.11Retrocompatível
Corpo de erro uniforme e IDs de requisição
Toda resposta traz um cabeçalho `X-Request-Id`; os corpos de erro o repetem como `request_id`.
Os corpos de erro agora são `{ success: false, code, error, request_id }` em todos os endpoints. `error` continua sendo uma string, portanto os clientes existentes continuam funcionando.
Rotas `/api/*` desconhecidas respondem 404 em JSON (`NOT_FOUND`) em vez de uma página HTML.
As respostas HTTP 429 incluem `Retry-After`.
As mensagens dos erros 5xx são genéricas; detalhes internos não são mais expostos.
Adicionado2026.11.11Retrocompatível
Endpoints da camada de dados de coleta própria, com cobertura e qualidade em todas as respostas
Novos: `/api/sd/oi`, `/api/sd/funding`, `/api/sd/liquidations`, `/api/sd/volume`, `/api/sd/ls`, `/api/sd/coin` e `/api/sd/quality`.
Os contratos em aberto são reportados separadamente para contratos USDT / USDC / com margem em cripto / com vencimento, com a indicação de quais corretoras reportam números bilaterais.
O financiamento é retornado bruto, com seu intervalo, normalizado para 8h e anualizado; as corretoras cujo contrato não está ativo são excluídas e listadas.
Descontinuado2026.11.11Retrocompatível
`/api/market/long-short` marcado como legado
Use `/api/market/long-short-v2` para a visão em lista ou `/api/sd/ls` para as razões por contas / por posições / taker de cada corretora.
Alterado2026.10.31Retrocompatível
Os campos de ícone retornam caminhos de mesma origem
Campos como `image_url` / `icon` agora contêm um caminho da CoinBoss (`/api/coin-icon/...`) em vez de uma URL de terceiros.
Uma moeda sem ícone verificado retorna `null`; os clientes devem renderizar seu próprio placeholder.
Corrigido2026.10.24Retrocompatível
Linhas desatualizadas não entram mais nos agregados
Os totais de contratos em aberto, financiamento e long/short usam apenas as linhas atualizadas dentro da janela de atualidade (mais longa para a CME, que publica diariamente).
Contratos deslistados deixam de contribuir para os totais assim que sua última atualização sai da janela.
Endpoints legados
Mantidos por compatibilidade. Continuam funcionando; novas integrações devem usar o substituto.
Mantido para integrações existentes. Use `/api/market/long-short-v2` (adiciona um filtro de corretora) ou `/api/sd/ls` (por corretora, com contas / posições / taker mantidos em separado).
`apr_pct` é `basis_pct × 3 × 365`, uma extrapolação simples da base atual do perpétuo, como se ela fosse paga a cada 8 horas; não é um rendimento de financiamento nem de contrato com vencimento. `/api/sd/basis` informa separadamente as bases marcação-índice, spot-perpétuo e de contratos com vencimento.