API REFERENCE

괴리율 랭킹

V3 산식(성장 × √규모 × 수급)으로 계산한 점수가 높은 순으로 종목을 정렬해서 반환해요. 산식 본문과 백테스트 검증 결과도 함께 와요. 데일리 시그널 알람이나 "오늘의 TOP N" 발송에 써요.

요청

http

GET /api/public/v2/rankings?market=KR&bands=mega,xlarge,large&limit=50 HTTP/1.1
Host: www.bulliza.com
Authorization: Bearer rfk_live_<your-key>

쿼리 파라미터

이름	타입	기본값	설명
`market`	string	`KR`	`KR` \| `US` \| `KR,US` 동시
`bands`	string	`mega,xlarge,large`	시총 구간 콤마 — 아래 표 참고
`limit`	number	50	반환할 종목 수 (1 ~ 200)

시총 구간 (bands)

키	구간
`mega`	메가캡 — 20조+ (KR) / $200B+ (US)
`xlarge`	초대형 — 5조 ~ 20조 / $50B ~ $200B
`large`	대형 — 1조 ~ 5조 / $10B ~ $50B
`mid`	중형 — 3천억 ~ 1조 / $3B ~ $10B
`small`	소형 — 3천억 미만 / $3B 미만

응답

필드	타입	설명
`market`	string	요청한 시장
`bands`	string[]	요청한 시총 구간
`rows`	object[]	종목 배열 — gapPct desc 정렬
`rows[].ticker`	string	종목 코드
`rows[].name`	string	종목명
`rows[].marketCap`	number	시가총액
`rows[].currentPrice`	number	현재가
`rows[].targetPrice`	number	산식 기반 적정가
`rows[].gapPct`	number	괴리율 %
`rows[].score`	number	V3 산식 점수
`rows[].yoy`	number	순이익 전년대비 %
`rows[].ttmNiEok`	number	TTM 순이익 (억원)
`rows[].supplyPct`	number	수급 점수 %
`rows[].momentumPct`	number	이익 모멘텀 % (최근 분기 yoy)
`totalCount`	number	필터 통과한 전체 종목 수
`formula`	object	산식 본문 (점수·괴리율·적정가·백테스트)
`updatedAt`	ISO 8601	캐시 갱신 시각 (매시 갱신)

json

{
  "market": "KR",
  "bands": ["mega", "xlarge", "large"],
  "rows": [
    {
      "ticker": "005930", "name": "삼성전자",
      "marketCap": 18854249, "currentPrice": 322500,
      "targetPrice": 380000, "gapPct": 17.8,
      "score": 234, "yoy": 134.4,
      "ttmNiEok": 842090, "supplyPct": -0.01, "momentumPct": 100
    }
    // ...
  ],
  "totalCount": 240,
  "formula": {
    "score": "max(0, min(yoy, +300%)/100) × √(TTM 순이익 억) × (1 + 수급%/30) × (1 + 이익모멘텀)",
    "expectedReturn": "-2.25 + 1.05 × √점수",
    "targetPrice": "현재가 × (1 + 괴리율%/100)",
    "gap": "정렬 = 상승여력 높은 순",
    "backtest": "괴리율 파라미터는 2023-02 ~ 2026-05 KOSPI 전 시총구간 1년 수익 백테스트로 산출 (상승여력 ≈ 1년 기준)"
  },
  "updatedAt": "2026-06-15T13:00:00.000Z",
  "disclaimer": "본 응답은 공개된 산식으로..."
}

호출 예시

bash

# KOSPI 1조+ TOP 10
curl -H "Authorization: Bearer rfk_live_<your-key>" \
  "https://bulliza.com/api/public/v2/rankings?market=KR&bands=mega,xlarge,large&limit=10"

# 미국 메가캡 TOP 20
curl -H "Authorization: Bearer rfk_live_<your-key>" \
  "https://bulliza.com/api/public/v2/rankings?market=US&bands=mega,xlarge&limit=20"

캐시는 매시 갱신돼요

랭킹 계산에 5~15초 걸리지만 응답은 100ms 이하로 와요 — DB 캐시에서 읽어요. cache-warm cron 이 매시 정각에 미리 갱신하기 때문에 사용자는 항상 신선한 데이터를 받아요.

다음 단계