API 규약

모든 엔드포인트에 공통으로 적용되는 규칙입니다. URL 구조, 응답 엔벨로프, 심볼, 단위, 타임스탬프, 페이지네이션, 캐싱을 다룹니다.

기본 URL과 버전 관리

모든 엔드포인트는 하나의 기본 URL 아래에 있으며 HTTPS GET으로 호출합니다. 현재 경로는 v1 버전입니다. v1 안에서는 추가 방식의 변경만 이루어집니다. 필드와 엔드포인트가 추가될 수 있지만 기존 필드의 이름, 타입, 의미는 유지됩니다. 호환성이 깨지는 변경은 새 경로로 제공하며 변경 내역에 먼저 공지합니다.

기본 URLhttps://www.coinboss.com/api

응답 엔벨로프

모든 JSON 응답에는 최상위 success 플래그가 있습니다. 자체 수집 데이터 레이어의 엔드포인트(/api/sd 아래 경로)는 다음 추가 블록을 공통으로 갖습니다.

필드	설명
success	호출이 성공하면 true입니다. 항상 확인하십시오.
schema	응답 구조의 식별자와 메이저 버전.
now	응답이 조립된 서버 시각(밀리초).
coverage	포함된 거래소, 사용 불가 거래소와 그 사유, 만료되어 제외된 거래소.
method	응답에 포함된 각 집계값의 산식 또는 규칙.
meta	소스, 타임스탬프, 구간, 품질 등급, 만료 플래그, 캐시 수명, 폴백 동작.

이전 엔드포인트는 success와 data 필드를 반환하며 coverage, method, meta가 없을 수 있습니다. 정확한 필드는 각 레퍼런스 페이지에 문서화되어 있습니다.

코인, 계약, 거래소

coin 파라미터에는 대문자 기초 심볼을 사용합니다. 예: BTC, PEPE.
1000PEPE, kPEPE 같은 승수 계약은 수량을 환산해 기초 코인에 병합합니다.
거래소 식별자는 소문자입니다. 예: binance, okx, bybit, hyperliquid.
계약 심볼은 거래소가 사용하는 이름 그대로 반환됩니다. 엔드포인트가 여러 유형을 함께 반환하는 경우 USDT 마진, USDC 마진, 코인 마진 계약과 만기 선물은 계약 유형 필드로 구분합니다.
암호화폐 자산과 티커가 같은 토큰화 주식 및 원자재 무기한 선물은 암호화폐 집계에서 제외됩니다.

단위

_usd로 끝나는 필드는 미국 달러 기준 명목가치입니다.
펀딩비는 퍼센트가 아니라 소수입니다. 0.0001은 0.01%를 뜻합니다. _8h로 끝나는 필드는 8시간 주기로 환산한 값이며, 원래 정산 주기는 원본 펀딩비 옆에 함께 반환됩니다.
_pct로 끝나는 필드는 백분율입니다. 1.5는 1.5%를 뜻합니다.
미결제약정은 필드 설명에 별도 언급이 없는 한 USD 기준 단방향 명목가치입니다. 양방향 수치를 공시하는 거래소는 method 블록에 표기됩니다.
일부 레거시 엔드포인트는 정밀도를 유지하기 위해 소수를 문자열로 반환합니다. 필드 표에는 타입이 string(decimal)로 표시됩니다.

타임스탬프

타임스탬프는 필드 설명에 별도 언급이 없는 한 UTC 기준 Unix epoch 밀리초입니다.
observed_at은 포함된 최신 레코드에 대한 거래소 자체 타임스탬프이며, 거래소가 제공하지 않으면 null입니다.
received_at은 CoinBoss 수집기가 해당 레코드를 저장한 시각입니다.
fetched_at은 응답이 조립된 시각입니다. 캐시된 응답이라면 호출 시각보다 최대 캐시 TTL만큼 이전일 수 있습니다.
일별 시계열은 UTC 기준 날짜 경계를 사용합니다.

구간과 주기

구간 파라미터는 1h, 4h, 12h, 24h 같은 짧은 토큰을 사용하며, 일부 엔드포인트는 3d, 7d, 30d, 90d도 지원합니다. 엔드포인트별 허용 값은 레퍼런스 페이지에 나와 있습니다.
알 수 없는 구간 값은 INVALID_PARAM으로 거부되거나 문서화된 기본값으로 대체됩니다. 어느 쪽인지는 파라미터별로 명시되어 있습니다.
시계열의 버킷 크기는 구간에 따라 달라지며 레퍼런스 페이지에 명시되어 있습니다.

페이지네이션과 정렬

목록 엔드포인트는 엔드포인트별 문서에 따라 limit과 offset 또는 page와 size를 사용합니다. 한도에는 상한이 있으며, 더 큰 값은 상한으로 줄어듭니다.
응답에 total이 있으면 페이지네이션 적용 전의 행 수를 뜻합니다.
엔드포인트에 sort 파라미터가 문서화되어 있지 않으면 정렬 순서는 고정입니다.

null, 0, 누락

null은 값을 알 수 없거나 사용할 수 없다는 뜻입니다. 0은 측정된 값이 0이라는 뜻입니다.
차트에서 null은 빈 구간으로 표시해야 합니다. 보간하지 마십시오.
필드 표에서 “없을 수 있음”으로 표시된 필드는 객체에서 아예 빠질 수 있습니다. null과 동일하게 처리하십시오.

캐싱

각 엔드포인트에는 서버 캐시 TTL이 있으며, 레퍼런스 페이지와 meta.cache_ttl_s에서 확인할 수 있습니다. X-Cache 헤더는 HIT, STALE 또는 MISS를 알려 줍니다.
대부분의 GET 엔드포인트 앞단에는 약 10초의 짧은 엣지 캐시가 있습니다.
TTL보다 빠르게 폴링해도 동일한 데이터가 반환되며 요청 한도만 소모됩니다.

WebSocket

WebSocketwss://www.coinboss.com/ws

스트림은 푸시 전용 JSON입니다. 각 메시지에는 type 필드가 있습니다.
연결이 끊기면 지연을 두고 재연결한 뒤 대응하는 HTTP 엔드포인트에서 백필하십시오.

기계 판독용 문서

카탈로그, 각 엔드포인트의 파라미터와 필드 표, 상태, 품질 매트릭스는 /api/meta 아래에서 JSON으로 제공되며, 카탈로그 전체는 OpenAPI 3 문서로도 제공됩니다.