공개 API의 버전은 v1입니다. 경로 접두사는 `/api`이며 버전 번호를 포함하지 않습니다.
카탈로그에는 날짜 기반의 자체 버전(`catalog_version`, 예: 2026.11.11)이 있습니다. 엔드포인트, 파라미터, 문서가 변경될 때마다 바뀝니다.
자체 데이터 레이어 엔드포인트의 모든 응답에는 `schema` ID(예: `sd.oi.v1`)가 포함됩니다. 새 ID는 기존 필드의 의미나 타입이 바뀔 때만 발급됩니다.
호환성
엔드포인트, 선택 파라미터, 응답 필드, enum 값, 거래소의 추가는 하위 호환 변경이며 언제든지 이루어질 수 있습니다. 클라이언트는 알지 못하는 필드를 무시해야 합니다.
필드의 삭제나 이름 변경, 타입이나 단위 변경, 선택 파라미터의 필수 전환은 호환성이 깨지는 변경입니다. 적용 전에 이곳에 공지합니다.
수정은 예외입니다. 잘못된 수치에 대한 수정, 또는 이전에 조용히 허용되던 잘못된 입력에 대한 수정은 즉시 배포되며 적용되는 당일에 여기에 기재됩니다. 클라이언트 코드를 변경해야 할 수 있는 경우에는 호환성이 깨지는 변경으로 표시됩니다.
커버리지가 개선되면(새 거래소나 계약 유형 추가) 수치가 달라질 수 있습니다. 커버리지는 항상 응답에 함께 보고되므로 합계를 비교하기 전에 `coverage`를 먼저 비교하십시오.
누락된 데이터는 `null`로 반환되고 `coverage.unavailable`에 나열되며, 0이나 추정값으로 대체하는 일은 없습니다. `null`을 0으로 처리하는 코드는 잘못된 결과를 냅니다.
사용 중단
`legacy`로 표시된 엔드포인트는 계속 동작하지만, 새로 작업할 때는 명시된 대체 엔드포인트를 사용해야 합니다.
레거시 엔드포인트는 이 변경 내역에 사용 중단 항목이 게시된 후 최소 90일이 지나야 삭제됩니다.
`beta`로 표시된 엔드포인트는 사이트 페이지에 데이터를 제공합니다. 필드 구성은 90일 사전 공지 없이 바뀔 수 있지만, 모든 변경 사항은 이곳에 기록됩니다.
변경 사항
추가2026.11.12하위 호환
`/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.
추가2026.11.12하위 호환
`/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.
변경2026.11.12하위 호환
`/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.
변경2026.11.12하위 호환
`/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.
변경2026.11.12하위 호환
업스트림 장애 시 HTTP 503으로 응답하고 JSON 오류 본문을 유지
기존에 HTTP 502 또는 504로 응답하던 실패 요청은 이제 `Retry-After` 헤더와 함께 503으로 응답합니다. API 앞단의 CDN이 502와 504 응답의 본문을 자체 텍스트로 바꿔 `code`와 `request_id`가 사라졌기 때문이며, 503은 변경 없이 그대로 전달됩니다. `code` 값은 이전과 같습니다.
한 엔드포인트 뒤의 업스트림 소스에 장애가 생겨도 더 이상 다른 엔드포인트에 영향을 주지 않습니다. 게이트웨이는 연결 오류와 타임아웃이 발생한 경우에만 다른 인스턴스로 재시도합니다.
`/api/sd/options/*`와 `/api/sd/cme/overview`는 중국어 한자로 표기한 코인 이름을 허용합니다. 해당 시장이 없는 코인에는 400 대신 집계값이 `null`인 HTTP 200으로 응답합니다.
펀딩비 정산 이력: Bybit, OKX, Gate, Bitget에서 거래가 가장 활발한 코인 150개(HTX는 40개)에 대해 30일 구간 안의 공백을 감지해 다시 채웁니다. 그 결과 더 많은 코인에서 `cum_7d`와 `cum_30d`가 완전해집니다.
수정2026.11.11하위 호환
청산 변동성 지수 수정; 소스를 사용할 수 없는 엔드포인트는 503으로 응답
`/api/indicators/cdri`: 일 단위 그룹화에서 밀리초 타임스탬프를 초로 읽어 일별 시계열이 비어 있었습니다. 이제 완전한 UTC 일 기준으로 최대 90일분의 청산 합계를 반환합니다. `current.days`(신규 필드)는 사용된 일수이며, 2일 미만이면 `current.cdri` / `current.liqCV`는 `null`입니다.
`/api/indicators/reddit-subs`: 소스가 요청을 거부하는 동안에는 HTTP 500 대신 코드 `UNAVAILABLE`과 함께 HTTP 503으로 응답합니다. 구독자 수는 소스가 양수를 반환할 때만 저장됩니다.
HTTP 5xx 응답의 오류 본문은 더 이상 레거시 `msg` 필드에 업스트림 오류 텍스트를 담지 않습니다. 이제 이 필드에는 `error`와 동일한 일반 메시지가 들어갑니다.
수정2026.11.11호환성 깨짐
갱신이 멈춘 레코드는 표시되고 합계에서 제외됩니다
`/api/coins/all` 및 `/api/coins/search`: 48시간 넘게 갱신되지 않은 코인 레코드는 `market_cap`과 `mcap_rank`를 `null`로, `is_stale: true`와 함께 반환하며 모든 최신 행 뒤에 정렬됩니다. 적용 중인 규칙은 `stale_rule`로 그대로 반환됩니다.
`/api/derivatives/coins-full`: 코인당 정확히 한 행입니다. 이전에는 여러 코인 레코드가 같은 심볼을 공유하면 레코드마다 한 행씩 생성되었습니다. 이제 행에는 48시간 이내에 갱신된 레코드 중 가장 큰 레코드의 이름, 시가총액, 순위가 담기며, 그런 레코드가 없으면 `null`입니다. `mcap_rank`는 새 필드입니다.
`/api/reserves/overview`: 모든 행에 `updated_at`과 `is_stale`이 있습니다. `total`은 이제 36시간 이내에 갱신된 거래소만 합산합니다. 이전 정의는 `total_including_stale`로 유지되며, 제외된 거래소는 `stale_exchanges`에 나열됩니다.
`/api/margin/rates` 및 `/api/margin-fee/matrix`: 금리 갱신이 멈춘 자산과 셀에는 `is_stale: true`가 붙습니다. 임계값과 개수는 최상위 수준에서 반환됩니다.
2026-10-28부터 2026-11-11까지의 일별 글로벌 시가총액 스냅샷을 다시 계산했습니다. 합계에서 있을 수 없는 시가총액(비트코인보다 큰 값)을 가진 레코드 두 건이 발견되었기 때문입니다. 수집기는 이제 이런 값을 `null`로 저장합니다.
변경2026.11.11하위 호환
소스 장애는 실패하거나 최신처럼 보이는 대신 응답에 표시됩니다
`/api/indicators/mempool/pools`: 채굴 풀 소스가 응답하지 않으면 HTTP 500 대신 마지막으로 저장된 결과가 `stale: true`, `cached_at`, `stale_reason`과 함께 반환됩니다.
`/api/etf/funds`: 새 `frozen_fields` 객체가 추가되었습니다. 2026-10-08에 소스가 게시를 중단한 펀드 단위 필드의 이름과 각 값의 기준 날짜를 담습니다.
`/api/indicators/halving`: 새 `current_difficulty` 객체(`value`, `as_of`, `source`)가 추가되었습니다. `difficulty`(난이도 조정 진행률)는 소스를 사용할 수 없는 동안 `null`로 유지됩니다.
`/api/browser/detect`: 체인 조회에 실패한 경우를 더 이상 활동 내역이 없는 주소로 보고하지 않습니다. 어떤 체인도 조회할 수 없었으면 `kind`는 `lookup_failed`입니다.
`/api/currency/flows`: 이제 문서에 엔드포인트가 실제로 제공하는 22개 구간(5분~1년)이 나열됩니다.
변경2026.11.11호환성 깨짐
지원하지 않는 파라미터 값은 기본 데이터 대신 400을 반환합니다
`/api/derivatives/kline`: `interval=4h`는 1h 캔들을 UTC 경계에 맞춰 합성한 실제 4시간 캔들을 반환합니다(이전에는 1h 캔들을 반환했습니다). `1h`, `4h`, `1d` 이외의 interval은 400을 반환합니다.
`/api/options/` 아래의 옵션 엔드포인트: 지원하지 않는 `currency`는 BTC 데이터 대신 400을 반환하며, 7개 엔드포인트 모두에서 `coin`을 별칭으로 사용할 수 있습니다.
`/api/etf/flows`, `/api/etf/detail`, `/api/etf/funds`, `/api/etf/holdings`: 지원하지 않는 `asset`은 BTC 데이터 대신 400을 반환합니다.
`/api/liquidations/coins`: 지원하지 않는 `range`는 24h 데이터 대신 400을 반환하며, 적용 중인 구간은 `range`로 그대로 반환됩니다.
`/api/liquidations`, `/api/liquidations/largest`, `/api/derivatives/coins-full`에서 `limit`은 상한 1000으로 제한됩니다. 숫자가 아닌 `limit`은 실패하지 않고 기본값을 사용합니다.
수정2026.11.11호환성 깨짐
일별 거래량 및 리서치 통계 수정
`/api/volume/coin`: `daily_30d`가 하루의 모든 롤링 24h 스냅샷을 더해 일별 거래량을 약 24배 부풀렸습니다. 이제 UTC 기준 각 날의 마지막 스냅샷을 사용합니다.
`topic=derivatives`를 지정한 `/api/research/stats`: `volume_24h_usd`도 같은 방식으로 부풀려져 있었으며 수정되었습니다.
같은 응답의 `avg_funding_rate_pct`는 이제 백분율이며, 이전에 반환하던 원시 소수 값의 약 100배입니다. 이 값에 100을 곱하던 코드는 수정하십시오.
수정2026.11.11하위 호환
이전 시장 엔드포인트는 갱신이 멈춘 행을 무시합니다
영향을 받는 엔드포인트: `/api/market/tickers`, `/api/market/volume-rank`, `/api/market/open-interest`, `/api/market/funding`, `/api/market/funding-spread`, `/api/market/long-short`, `/api/market/long-short-v2`, `/api/market/overview`, `/api/p3/volume/overview`, `/api/p3/perp-spot-volume`, `/api/volume/btc-ex-share`, `/api/derivatives/coins-full`.
행은 최신인 동안에만 집계됩니다: 시세는 1시간 이내, 미결제약정은 3시간 이내(CME: 120시간), 펀딩은 4시간 이내, 롱/숏 비율은 24시간 이내.
합계가 약간 낮아지고 일부 목록이 짧아집니다. 거래가 중단된 계약은 마지막 값 대신 `null` 가격을 표시합니다.
수정2026.11.11하위 호환
승수 계약을 기준 코인에 매칭
`/api/funding/coin`, `/api/funding/history`, `/api/funding/chart`, `/api/ls/coin`은 이제 코인의 배수 단위로 호가되는 계약(예: `1000PEPE`)을 기준 코인에 매칭하므로, 이런 코인에 더 많은 거래소가 나열됩니다.
미결제약정, 24h 명목 거래량, 풋/콜 비율, 맥스 페인, ATM IV, 25델타 스큐, IV 기간 구조는 CoinBoss가 Deribit, Binance, Bybit, OKX, Gate, Coincall의 계약 목록에서 계산합니다.
명목 거래량과 프리미엄 거래대금은 별개의 필드이며 서로 합산하는 일은 없습니다. 거래소가 공개하지 않는 열은 `null`이며 `coverage.field_gaps`에 나열됩니다.
히스토리는 1시간 단위이며 2026-11-11부터 시작합니다. 그 이전 시간대는 백필하지 않습니다.
추가2026.11.11하위 호환
1차 공시 자료 기반의 현물 ETF, CME, CFTC 데이터
발행사 공시로 구성한 `/api/sd/etf/overview`, `/api/sd/etf/funds`, `/api/sd/etf/history`를 추가했습니다. 합계는 CoinBoss가 수집할 수 있는 펀드만 포함하며, 그 밖의 펀드는 모두 사유와 함께 나열되고 `totals_scope`는 항상 `covered_funds_only`입니다.
펀드 자금 흐름은 CoinBoss가 발행 주식 수와 NAV(또는 순자산과 NAV)로 계산합니다. 사용한 산식은 펀드별로 `flow_method`에 반환됩니다.
`/api/sd/cme/overview`(CME 상품 8종의 일별 거래량과 미결제약정)와 `/api/sd/cme/cot`(트레이더 유형별 주간 CFTC 포지셔닝)를 추가했습니다.
CME 정산가는 아직 수집하지 않습니다. USD 수치는 출처가 표기된 기준 가격(`price_src`)을 사용하며, 이 때문에 overview는 PARTIAL로 표시됩니다.
무기한 선물 베이시스 = 같은 거래소의 (mark − index) ÷ index × 100; 현물-무기한 베이시스는 무기한 선물을 같은 거래소의 현물 시장과 비교하며, 만기 선물에는 연환산 값이 추가됩니다.
집계값은 OI 가중, 거래량 가중, 중앙값으로 제공됩니다. 포함 규칙을 충족하지 못한 행도 `excluded_reason`과 함께 반환됩니다.
1시간 단위 히스토리는 2026-11-11부터 시작합니다.
변경2026.11.11하위 호환
아이콘 맵이 공개 사이트 오리진을 사용합니다
`/api/coin-icons` 및 `/api/exchange-icons`는 다른 모든 공개 엔드포인트와 같은 오리진인 `https://www.coinboss.com`의 아이콘 URL을 반환합니다. 경로(`/api/coin-icon/{coin}`, `/api/exchange-icon/{exchange}`)는 변경되지 않았습니다.
사용 중단2026.11.11하위 호환
`/api/basis/list`와 `/api/cftc/cot`를 레거시로 지정
`/api/basis/list` 대신 `/api/sd/basis/rank`를, `/api/cftc/cot` 대신 `/api/sd/cme/cot`를 사용하십시오. 레거시 엔드포인트는 계속 동작합니다.
변경2026.11.11하위 호환
`/api/liquidation-events`는 이제 CoinBoss 자체 레코드만 제공
목록은 CoinBoss가 거래소 피드에서 수신한 청산 주문으로 구성됩니다. 히스토리는 2026-08-19부터 시작하며, 그 이전 날짜에는 행이 반환되지 않습니다.
필드 이름과 타입은 변경되지 않았습니다.
삭제2026.11.11하위 호환
운영용 엔드포인트는 더 이상 인터넷에서 접근할 수 없음
`/api/health/alerts`, `/api/health/server`, `/api/health/history`, `/api/health/ch-read`는 공개 요청에 404로 응답합니다. 이 엔드포인트들은 공개 API에 포함된 적이 없습니다.
서비스 상태는 `/api/meta/status`를, 데이터 신선도는 `/api/meta/quality`를 사용하십시오.