공개 API

인증 없음 · 분당 60회 · JSON · 색인(JSON)

화면이 보여주는 값을 그대로 기계가 읽습니다. 시그널과 그 시그널의 과거 성과, 지금 어떤 규칙이 통하는 장인지까지 같은 계산을 씁니다.

빨리 써보기

curl -s "https://maedong.kr/api/v1/regime" | jq '.label, .lists[:3]'
curl -s "https://maedong.kr/api/v1/signals?signal=high-52w&limit=5"
curl -s "https://maedong.kr/api/v1/signals/high-52w/stats?window=recent60"
curl -s "https://maedong.kr/api/v1/stock/005930/signals?from=2026-01-01"
curl -s "https://maedong.kr/api/v1/market"

실시간 데이터가 아닙니다. 모든 응답의 meta 에 아래 세 값이 있으니 그대로 인용하세요.

data_date: 시세가 들어 있는 가장 최근 거래일. 장 마감 뒤 오후 4시 전후부터는 그날 속보 시세라 당일 날짜가 되고, 다음 영업일 오전 11시 30분 전후에 확정 시세가 같은 날짜를 덮어씁니다. 지금 값이 속보인지는 /api/v1/status 의 provisional 로 봅니다.
lag_business_days: 오늘(한국 시각)에서 data_date 까지 영업일 수. 속보가 들어온 저녁에는 0 이고, 다음 날 오후 4시 전후 그날 속보가 들어오기 전까지는 1 입니다. 연휴나 수집 지연이면 더 커집니다.
next_update: data_date 다음 거래일의 확정 시세가 들어올 예상 시각. 그 거래일의 속보는 그날 오후 4시 전후에 먼저 들어옵니다.
엔드포인트마다 다른 점: /macro·/macro/{series} 는 행마다 날짜가 따로 있습니다(월·분기 계열은 기간 마지막 날, meta.data_date 는 시세 기준일). /stock/{code}/flow 의 수급은 시세보다 늦게(저녁) 들어와 가장 최근 날이 비어 있을 수 있습니다. 응답의 meta.note 가 그 엔드포인트의 규칙을 적습니다.

단위 규약

이름만 보고 단위를 알 수 있게

접미사	뜻	예
`_pct`	퍼센트(%)avg_pct · change_pct · win_rate_pct · avg_gain_pct · avg_loss_pct	`avg_pct` · `change_pct` · `win_rate_pct` · `avg_gain_pct` · `avg_loss_pct`
`_pp`	퍼센트포인트(%p)excess_pp · yield_gap_pp	`excess_pp` · `yield_gap_pp`
`_krw`	원open_krw · high_krw · low_krw · close_krw · entry_krw · value_krw · market_cap_krw	`open_krw` · `high_krw` · `low_krw` · `close_krw` · `entry_krw` · `value_krw` · `market_cap_krw`
없음	배수·건수·비율 그 자체per · pbr · n · payoff_ratio	`per` · `pbr` · `n` · `payoff_ratio`

진입가는 entry_krw 입니다. 목록은 date 의 마감 뒤에 계산되므로 그 날짜의 open_krw·close_krw 로는 체결할 수 없습니다 — 도달 가능한 체결가는 다음 거래일의 시가이고, 그 값을 entry_krw(날짜는 entry_date)로 같이 드립니다. 직접 구할 수 없어서 같이 냅니다: 골든크로스처럼 하루짜리 시그널은 그 종목이 다음 날 목록에 없습니다. entry_date 가 null 이면 다음 거래일이 아직 지나지 않은 것이고, 그때는 진입가를 알 수 없는 것이 맞습니다. 거래가 없던 값은 0 이 아니라 null 로 나갑니다.

수급·공매도 목록은 그날 수급이 아직 들어오지 않았으면(평일 마감 뒤 저녁 6시 30분쯤까지) total 이 null 이고 data_pending: true 가 붙습니다. 그때 빈 items 는 '해당 없음' 이 아닙니다.

관계식 — excess_pp = avg_pct - market_avg_pct. 목록 평균에서 같은 날들의 전 종목 평균(거래대금 10억 이상)을 뺀 값입니다. 판정은 전체 기간 20거래일 excess_pp 가 ±0.5%p 를 벗어나는지로 매깁니다.

시그널 36종

has_stats 가 false 면 과거 성과를 집계하지 않습니다

slug	이름	묶음	성과
`value-surge`	거래대금 급증이례 시그널	이례 시그널	집계
`value-top`	거래대금 상위순위	순위	집계
`gainers`	상승률 상위순위	순위	집계
`losers`	하락률 상위순위	순위	집계
`high-52w`	52주 신고가이례 시그널	이례 시그널	집계
`low-52w`	52주 신저가이례 시그널	이례 시그널	집계
`market-cap`	시가총액 상위순위	순위	집계
`large-gainers`	대형주 상승률 상위순위	순위	집계
`turnover`	회전율 상위순위	순위	집계
`gap-up`	갭 상승이례 시그널	이례 시그널	집계
`streak-up`	연속 상승이례 시그널	이례 시그널	집계
`low-per`	저PER팩터	팩터	집계
`momentum-12-1`	12-1 모멘텀 상위팩터	팩터	집계
`momentum-weighted`	가중 모멘텀 상위팩터	팩터	집계
`drawdown-52w`	52주 고점 대비 낙폭 상위팩터	팩터	집계
`surge-pullback`	급증 뒤 되돌림반전 후보	반전 후보	집계
`turnover-gapdown`	과열 뒤 갭하락반전 후보	반전 후보	집계
`low52-surge`	신저가 부근 거래대금 급증반전 후보	반전 후보	집계
`high-dividend`	고배당팩터	팩터	집계
`disparity-hot`	20일선 과열반전 후보	반전 후보	집계
`disparity-cold`	20일선 과냉반전 후보	반전 후보	집계
`golden-cross`	골든크로스차트 이론	차트 이론	집계
`ma-stack`	정배열 진입차트 이론	차트 이론	집계
`box-breakout`	박스권 상단 돌파차트 이론	차트 이론	집계
`trend-breakout`	추세 돌파차트 이론	차트 이론	집계
`rsi-oversold`	RSI 과매도차트 이론	차트 이론	집계
`golden-cross-flow`	골든크로스 + 외국인·기관 순매수차트 × 수급	차트 × 수급	집계
`ma-stack-flow`	정배열 진입 + 외국인·기관 순매수차트 × 수급	차트 × 수급	집계
`dry-surge`	조용하다 돈이 몰린반전 후보	반전 후보	집계
`foreign-buy-streak`	외국인 연속 순매수수급	수급	집계
`accumulation`	안 올랐는데 계속 산수급	수급	집계
`distribution`	올랐는데 계속 판수급	수급	집계
`both-buy`	기관·외국인 동반 순매수수급	수급	집계
`retail-only`	개인만 받는수급	수급	집계
`short-surge`	공매도 비중 급증수급	수급	집계
`short-top`	공매도 비중 상위수급	수급	집계

모든 목록의 성과를 집계합니다. 재무(PER·배당)로 뽑는 목록은 그날 공시돼 있던 재무만 씁니다 — 사업보고서 제출기한이 3월 말이라 4월부터 그 직전 사업연도를 쓰고, 그 이전 날짜에는 한 해 더 앞의 것을 씁니다. 그래서 과거를 다시 세워도 그때 알 수 없던 것이 섞이지 않습니다. 붙일 재무가 아예 없는 2020년 4월 이전은 비어 있습니다.

상태 플래그

가격제한폭이 없는 종목을 다른 종목과 같은 자에 놓지 않도록

code	label	뜻
`liquidation`	정리매매가격제한폭이 없다 — 등락률을 다른 종목과 같은 자에 놓을 수 없다	가격제한폭이 없다 — 등락률을 다른 종목과 같은 자에 놓을 수 없다
`delisting`	상장폐지 예정상장폐지 절차가 진행 중이다 — 아직 제한폭 안에서 거래된다	상장폐지 절차가 진행 중이다 — 아직 제한폭 안에서 거래된다
`halted`	거래정지거래소가 막았다 — 정지 공시의 최신 상태가 정지이고 그날 거래량도 0인 종목	거래소가 막았다 — 정지 공시의 최신 상태가 정지이고 그날 거래량도 0인 종목
`no_trade`	무거래그날 한 주도 거래되지 않았다 — 정지일 수도 있고 유동성이 없을 수도 있다	그날 한 주도 거래되지 않았다 — 정지일 수도 있고 유동성이 없을 수도 있다

한 종목에 여러 개가 붙을 수 있습니다. 라벨은 다듬을 수 있지만 code 는 계약이라 바꾸지 않습니다 — 분기는 code 로 하세요. liquidation 종목은 상승률·하락률 순위에서 제외하고 응답의 excluded 에 따로 담습니다.

GET /api/v1/signals

기준일의 목록 구성원. signal 을 생략하면 목록 카탈로그(규칙·전체 건수)를 준다

파라미터	설명
`date`	기준일 YYYY-MM-DD. 생략하면 최신 거래일
`signal`	목록 slug. 생략하면 건수 색인
`limit`	1~200, 기본 50
`cursor`	이전 응답의 next_cursor 를 그대로

curl -s "https://maedong.kr/api/v1/signals?signal=value-surge&limit=2"

{
  "date": "2026-10-28",
  "signal": "value-surge",
  "label": "거래대금 급증",
  "rule": "최근 20영업일 평균 거래대금보다 2배 이상 돈이 몰린 종목. 매매 주체는 몰라도 돈이 몰린 곳은 보인다.",
  "metric_label": "20일 평균 대비",
  "count": 2,
  "total": 82,
  "items": [
    {
      "code": "396470",
      "name": "워트",
      "market": "KOSDAQ",
      "open_krw": 6160,
      "high_krw": 7440,
      "low_krw": 6140,
      "close_krw": 6410,
      "entry_krw": null,
      "change_pct": 6.13,
      "value_krw": 32661540345,
      "market_cap_krw": 103300000000,
      "metric_text": "×42.4",
      "flags": []
    },
    {
      "code": "050110",
      "name": "캠시스",
      "market": "KOSDAQ",
      "open_krw": 7500,
      "high_krw": 8450,
      "low_krw": 6640,
      "close_krw": 6800,
      "entry_krw": null,
      "change_pct": -3.55,
      "value_krw": 13859699740,
      "market_cap_krw": 39700000000,
      "metric_text": "×39.9",
      "flags": []
    }
  ],
  "entry_date": null,
  "entry_note": "이 목록은 date 의 마감 뒤에 계산되므로 open_krw·close_krw 로는 체결할 수 없습니다. 도달 가능한 체결가는 entry_krw(= entry_date 의 시가)입니다. entry_date 가 null 이면 다음 거래일이 아직 지나지 않았고, 그때는 진입가를 알 수 없습니다.",
  "next_cursor": "2",
  "excluded": [],
  "meta": {
    "as_of": "2026-10-29T00:03:14+09:00",
    "data_date": "2026-10-28",
    "lag_business_days": 1,
    "next_update": "10월 30일(금) 오전 11시 30분 전후",
    "source": "공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART · 한국거래소 통계정보",
    "license": "출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다",
    "disclaimer": "전일 마감 데이터이며 투자 참고용입니다. 특정 종목의 매수·매도를 권유하지 않습니다."
  }
}

count 는 **이 응답에 담긴** 종목 수, total 은 **조건에 맞는 전체** 종목 수다 — 페이지를 끝까지 넘기지 않고도 규모를 알 수 있다. '상위 N' 형 목록(거래대금 상위 등)은 조건이 아니라 정렬이라 total 이 null 이다. next_cursor 가 null 이면 마지막 페이지다. excluded 에는 순위에서 뺀 정리매매 종목이 담긴다.

GET /api/v1/signals/{signal}/stats

그 시그널이 뜬 종목이 이후 어땠는지

파라미터	설명
`window`	all(전체 기간) 또는 recent60(최근 60시그널일)

curl -s "https://maedong.kr/api/v1/signals/value-surge/stats"

{
  "signal": "value-surge",
  "label": "거래대금 급증",
  "window": "all",
  "entry": "close",
  "since": "2020-01-03",
  "signal_days": 1652,
  "verdict": "시장 하회",
  "verdict_band_pp": 0.5,
  "horizons": [
    {
      "trading_days": 1,
      "n": 33010,
      "avg_pct": -0.16,
      "median_pct": -0.7,
      "win_rate_pct": 41.6,
      "market_avg_pct": 0.02,
      "market_win_rate_pct": 44.7,
      "excess_pp": -0.18,
      "avg_gain_pct": 5.88,
      "avg_loss_pct": -4.71,
      "payoff_ratio": 1.25,
      "market_avg_gain_pct": 3.23,
      "market_avg_loss_pct": -2.51,
      "market_payoff_ratio": 1.29
    },
    {
      "trading_days": 5,
      "n": 33003,
      "avg_pct": -0.64,
      "median_pct": -2.32,
      "win_rate_pct": 39.1,
      "market_avg_pct": 0.1,
      "market_win_rate_pct": 45.0,
      "excess_pp": -0.74,
      "avg_gain_pct": 11.73,
      "avg_loss_pct": -8.68,
      "payoff_ratio": 1.35,
      "market_avg_gain_pct": 7.27,
      "market_avg_loss_pct": -5.43,
      "market_payoff_ratio": 1.34
    },
    {
      "trading_days": 20,
      "n": 33012,
      "avg_pct": -0.85,
      "median_pct": -4.92,
      "win_rate_pct": 36.9,
      "market_avg_pct": 0.34,
      "market_win_rate_pct": 43.4,
      "excess_pp": -1.19,
      "avg_gain_pct": 21.23,
      "avg_loss_pct": -13.89,
      "payoff_ratio": 1.53,
      "market_avg_gain_pct": 14.79,
      "market_avg_loss_pct": -10.26,
      "market_payoff_ratio": 1.44
    }
  ],
  "distribution_20d": {
    "median": -4.92,
    "q1": -14.32,
    "q3": 6.01,
    "min": -97.2,
    "max": 581.1
  },
  "basis": "시그널이 난 날 종가에 사고 N거래일 뒤 종가에 판 것으로 계산 · 거래비용 미반영",
  "payoff_basis": "avg_gain_pct·avg_loss_pct 는 N거래일 수익률 중 오른 건·내린 건의 평균(시장 대비 아님). payoff_ratio = avg_gain / |avg_loss|. market_* 는 같은 날들 전 종목(거래대금 10억 이상)의 같은 값이다. 판정은 excess_pp 로 낸다",
  "meta": {
    "as_of": "2026-10-29T00:03:14+09:00",
    "data_date": "2026-10-28",
    "lag_business_days": 1,
    "next_update": "10월 30일(금) 오전 11시 30분 전후",
    "source": "공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART · 한국거래소 통계정보",
    "license": "출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다",
    "disclaimer": "전일 마감 데이터이며 투자 참고용입니다. 특정 종목의 매수·매도를 권유하지 않습니다."
  }
}

horizons 는 1·5·20거래일이다. median_pct 는 평균이 대박 한 건에 끌릴 때를 위해 같이 준다.

GET /api/v1/stock/{code}/signals

이 종목에 언제 어느 시그널이 떴고 그 뒤 어땠는지

파라미터	설명
`from / to`	기간 YYYY-MM-DD
`limit`	1~200, 기본 100

curl -s "https://maedong.kr/api/v1/stock/005930/signals?limit=2"

{
  "code": "005930",
  "name": "삼성전자",
  "market": "KOSPI",
  "flags": [],
  "count": 2,
  "hits": [
    {
      "date": "2026-10-27",
      "signal": "both-buy",
      "label": "기관·외국인 동반 순매수",
      "ret_1d_pct": null,
      "ret_5d_pct": null,
      "ret_20d_pct": null
    },
    {
      "date": "2026-10-27",
      "signal": "market-cap",
      "label": "시가총액 상위",
      "ret_1d_pct": null,
      "ret_5d_pct": null,
      "ret_20d_pct": null
    }
  ],
  "note": "수익률이 null 이면 아직 그 거래일이 지나지 않았습니다.",
  "meta": {
    "as_of": "2026-10-29T00:03:14+09:00",
    "data_date": "2026-10-28",
    "lag_business_days": 1,
    "next_update": "10월 30일(금) 오전 11시 30분 전후",
    "source": "공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART · 한국거래소 통계정보",
    "license": "출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다",
    "disclaimer": "전일 마감 데이터이며 투자 참고용입니다. 특정 종목의 매수·매도를 권유하지 않습니다."
  }
}

ret_*_pct 가 null 이면 아직 그 거래일이 지나지 않았다.

GET /api/v1/regime

지금 어떤 규칙이 통하는 장인가

파라미터	설명
`as_of`	기준일. 생략하면 최신
`window`	비교 창(거래일) 20~250, 기본 60

curl -s "https://maedong.kr/api/v1/regime"

{
  "window_trading_days": 60,
  "signal_window": {
    "from": "2026-06-30",
    "to": "2026-09-28"
  },
  "settle_lag_trading_days": 20,
  "label": "무엇을 사도 시장을 못 이긴 구간",
  "axes": [
    {
      "name": "반전",
      "excess_pp": -0.66,
      "lists": 5,
      "note": "빠진 것을 살 때 통한다"
    },
    {
      "name": "대형·우량",
      "excess_pp": -4.8,
      "lists": 3,
      "note": "큰 종목으로 돈이 몰릴 때 통한다"
    },
    {
      "name": "돌파 추종",
      "excess_pp": -4.86,
      "lists": 3,
      "note": "신고가·연속 상승을 따라갈 때 통한다"
    },
    {
      "name": "단기 과열 추격",
      "excess_pp": -7.33,
      "lists": 4,
      "note": "급등 당일에 살 때 통한다"
    }
  ],
  "lists": [
    {
      "signal": "low-52w",
      "label": "52주 신저가",
      "n": 526,
      "avg_pct": 6.29,
      "excess_pp": 5.61
    },
    {
      "signal": "disparity-cold",
      "label": "20일선 과냉",
      "n": 999,
      "avg_pct": 4.64,
      "excess_pp": 4.01
    },
    {
      "signal": "low52-surge",
      "label": "신저가 부근 거래대금 급증",
      "n": 427,
      "avg_pct": 3.7,
      "excess_pp": 3.07
    },
    {
      "signal": "rsi-oversold",
      "label": "RSI 과매도",
      "n": 1117,
      "avg_pct": 3.6,
      "excess_pp": 2.97
    },
    {
      "signal": "accumulation",
      "label": "안 올랐는데 계속 산",
      "n": 951,
      "avg_pct": 2.29,
      "excess_pp": 1.67
    },
    {
      "signal": "momentum-12-1",
      "label": "12-1 모멘텀 상위",
      "n": 1220,
      "avg_pct": 1.85,
      "excess_pp": 1.23
    },
    {
      "signal": "drawdown-52w",
      "label": "52주 고점 대비 낙폭 상위",
      "n": 1220,
      "avg_pct": 1.78,
      "excess_pp": 1.15
    },
    {
      "signal": "low-per",
      "label": "저PER",
      "n": 1220,
      "avg_pct": 1.28,
      "excess_pp": 0.66
    },
    {
      "signal": "surge-pullback",
      "label": "급증 뒤 되돌림",
      "n": 865,
      "avg_pct": 0.94,
      "excess_pp": 0.26
    },
    {
      "signal": "short-top",
      "label": "공매도 비중 상위",
      "n": 1220,
      "avg_pct": 0.64,
      "excess_pp": 0.01
    },
    {
      "signal": "dry-surge",
      "label": "조용하다 돈이 몰린",
      "n": 493,
      "avg_pct": 0.25,
      "excess_pp": -0.38
    },
    {
      "signal": "short-surge",
      "label": "공매도 비중 급증",
      "n": 810,
      "avg_pct": -0.26,
      "excess_pp": -0.89
    },
    {
      "signal": "retail-only",
      "label": "개인만 받는",
      "n": 1220,
      "avg_pct": -0.28,
      "excess_pp": -0.91
    },
    {
      "signal": "high-dividend",
      "label": "고배당",
      "n": 1220,
      "avg_pct": -0.37,
      "excess_pp": -1.0
    },
    {
      "signal": "distribution",
      "label": "올랐는데 계속 판",
      "n": 1124,
      "avg_pct": -1.92,
      "excess_pp": -2.55
    },
    {
      "signal": "golden-cross-flow",
      "label": "골든크로스 + 외국인·기관 순매수",
      "n": 399,
      "avg_pct": -2.14,
      "excess_pp": -2.69
    },
    {
      "signal": "foreign-buy-streak",
      "label": "외국인 연속 순매수",
      "n": 1220,
      "avg_pct": -2.1,
      "excess_pp": -2.73
    },
    {
      "signal": "golden-cross",
      "label": "골든크로스",
      "n": 1001,
      "avg_pct": -2.28,
      "excess_pp": -2.91
    },
    {
      "signal": "both-buy",
      "label": "기관·외국인 동반 순매수",
      "n": 1216,
      "avg_pct": -2.66,
      "excess_pp": -3.29
    },
    {
      "signal": "large-gainers",
      "label": "대형주 상승률 상위",
      "n": 1220,
      "avg_pct": -3.53,
      "excess_pp": -4.16
    },
    {
      "signal": "ma-stack-flow",
      "label": "정배열 진입 + 외국인·기관 순매수",
      "n": 108,
      "avg_pct": -6.18,
      "excess_pp": -4.33
    },
    {
      "signal": "losers",
      "label": "하락률 상위",
      "n": 1212,
      "avg_pct": -3.85,
      "excess_pp": -4.47
    },
    {
      "signal": "value-surge",
      "label": "거래대금 급증",
      "n": 1211,
      "avg_pct": -3.93,
      "excess_pp": -4.56
    },
    {
      "signal": "market-cap",
      "label": "시가총액 상위",
      "n": 1220,
      "avg_pct": -3.99,
      "excess_pp": -4.62
    },
    {
      "signal": "streak-up",
      "label": "연속 상승",
      "n": 1154,
      "avg_pct": -4.79,
      "excess_pp": -5.41
    },
    {
      "signal": "value-top",
      "label": "거래대금 상위",
      "n": 1220,
      "avg_pct": -5.01,
      "excess_pp": -5.63
    },
    {
      "signal": "momentum-weighted",
      "label": "가중 모멘텀 상위",
      "n": 1220,
      "avg_pct": -5.04,
      "excess_pp": -5.67
    },
    {
      "signal": "box-breakout",
      "label": "박스권 상단 돌파",
      "n": 1010,
      "avg_pct": -5.06,
      "excess_pp": -5.68
    },
    {
      "signal": "ma-stack",
      "label": "정배열 진입",
      "n": 266,
      "avg_pct": -5.83,
      "excess_pp": -5.84
    },
    {
      "signal": "gap-up",
      "label": "갭 상승",
      "n": 1199,
      "avg_pct": -6.26,
      "excess_pp": -6.89
    },
    {
      "signal": "gainers",
      "label": "상승률 상위",
      "n": 1217,
      "avg_pct": -6.37,
      "excess_pp": -6.99
    },
    {
      "signal": "trend-breakout",
      "label": "추세 돌파",
      "n": 15,
      "avg_pct": -15.01,
      "excess_pp": -9.77
    },
    {
      "signal": "high-52w",
      "label": "52주 신고가",
      "n": 417,
      "avg_pct": -10.2,
      "excess_pp": -10.41
    },
    {
      "signal": "turnover",
      "label": "회전율 상위",
      "n": 1218,
      "avg_pct": -10.25,
      "excess_pp": -10.87
    },
    {
      "signal": "disparity-hot",
      "label": "20일선 과열",
      "n": 1207,
      "avg_pct": -10.36,
      "excess_pp": -10.99
    },
    {
      "signal": "turnover-gapdown",
      "label": "과열 뒤 갭하락",
      "n": 160,
      "avg_pct": -12.49,
      "excess_pp": -13.39
    }
  ],
  "basis": "모든 목록이 같은 거래일 창을 본다 · 20거래일이 지나 성과가 확정된 시그널만",
  "coverage": {
    "lists_total": 36,
    "lists_scored": 36,
    "excluded": [],
    "not_settled": [],
    "note": "전체 36종 중 36종."
  },
  "market_state": {
    "date": "2026-10-28",
    "trend_share_pct": 23.33,
    "threshold_pct": 30.0,
    "trend_regime": "down",
    "kospi_above_ma200": false,
    "kospi_ret12_pct": 60.4,
    "definition": "추세 종목 비율 = 그 날짜 기준 20일 거래대금 상위 300 중 20일선>40일선이고 둘 다 5거래일 전보다 높은 종목의 비율(%). 문턱 30% 이상이면 up. KOSPI 는 200거래일 이동평균·252거래일 수익률"
  },
  "meta": {
    "as_of": "2026-10-29T00:03:14+09:00",
    "data_date": "2026-10-28",
    "lag_business_days": 1,
    "next_update": "10월 30일(금) 오전 11시 30분 전후",
    "source": "공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART · 한국거래소 통계정보",
    "license": "출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다",
    "disclaimer": "전일 마감 데이터이며 투자 참고용입니다. 특정 종목의 매수·매도를 권유하지 않습니다."
  }
}

label 은 축 사이 격차가 2%p 이상일 때만 붙는다(아니면 null — 혼재). 1위 축도 시장을 못 이겼으면 '우위' 라고 쓰지 않는다.

GET /api/v1/market

기준일의 지수·시장 폭·밸류에이션·매크로

파라미터	설명
`date`	기준일. 생략하면 최신 거래일

curl -s "https://maedong.kr/api/v1/market"

{
  "date": "2026-10-28",
  "indices": [
    {
      "market": "KOSPI",
      "close": 6012.44,
      "change_pct": 6.63,
      "value_krw": 19836769000000
    },
    {
      "market": "KOSDAQ",
      "close": 771.28,
      "change_pct": 3.69,
      "value_krw": 6672185000000
    }
  ],
  "breadth": {
    "up": 1731,
    "down": 810,
    "unchanged": 110,
    "limit_up": 6,
    "limit_down": 3
  },
  "valuation": [
    {
      "market": "KOSPI",
      "per": 20.6,
      "pbr": 1.61,
      "div_yield_pct": 1.21,
      "yield_gap_pp": -2.59,
      "coverage_pct": 96.3,
      "percentiles": {
        "per": {
          "percentile_pct": 59,
          "n": 1611,
          "since": "2020-04-01"
        },
        "pbr": {
          "percentile_pct": 91,
          "n": 1611,
          "since": "2020-04-01"
        },
        "div_yield": {
          "percentile_pct": 9,
          "n": 1611,
          "since": "2020-04-01"
        },
        "yield_gap": {
          "percentile_pct": 6,
          "n": 1611,
          "since": "2020-04-01"
        }
      }
    },
    {
      "market": "KOSDAQ",
      "per": 69.0,
      "pbr": 1.54,
      "div_yield_pct": 1.44,
      "yield_gap_pp": -2.36,
      "coverage_pct": 96.3,
      "percentiles": {
        "per": {
          "percentile_pct": 60,
          "n": 1611,
          "since": "2020-04-01"
        },
        "pbr": {
          "percentile_pct": 23,
          "n": 1611,
          "since": "2020-04-01"
        },
        "div_yield": {
          "percentile_pct": 47,
          "n": 1611,
          "since": "2020-04-01"
        },
        "yield_gap": {
          "percentile_pct": 13,
          "n": 1611,
          "since": "2020-04-01"
        }
      }
    }
  ],
  "macro": [
    {
      "series": "usdkrw",
      "label": "원/달러",
      "value": 1324.3,
      "unit": "원",
      "change": 0.13,
      "change_text": "+0.13%",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "jpykrw",
      "label": "원/100엔",
      "value": 838.3,
      "unit": "원",
      "change": -0.18,
      "change_text": "-0.18%",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "eurkrw",
      "label": "원/유로",
      "value": 1473.8,
      "unit": "원",
      "change": -0.27,
      "change_text": "-0.27%",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "ktb3y",
      "label": "국고채 3년",
      "value": 3.799,
      "unit": "%",
      "change": 0.041,
      "change_text": "+0.041%p",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "ktb10y",
      "label": "국고채 10년",
      "value": 4.108,
      "unit": "%",
      "change": 0.076,
      "change_text": "+0.076%p",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "base_rate",
      "label": "기준금리",
      "value": 3.0,
      "unit": "%",
      "change": 0.25,
      "change_text": "+0.25%p · 8/27부터 동결",
      "held": true,
      "date": "2026-10-26"
    },
    {
      "series": "gold",
      "label": "금 1g",
      "value": 170390.0,
      "unit": "원",
      "change": -0.01,
      "change_text": "-0.01%",
      "held": false,
      "date": "2026-10-27"
    },
    {
      "series": "btc",
      "label": "비트코인",
      "value": 10921.0,
      "unit": "만원",
      "change": 1.3,
      "change_text": "+1.30%",
      "held": false,
      "date": "2026-10-28"
    },
    {
      "series": "frgn_kospi",
      "label": "외국인 보유(코스피)",
      "value": 39.26,
      "unit": "%",
      "change": 0.22,
      "change_text": "+0.22%p",
      "held": false,
      "date": "2026-10-27"
    },
    {
      "series": "frgn_kosdaq",
      "label": "외국인 보유(코스닥)",
      "value": 11.4,
      "unit": "%",
      "change": 0.07,
      "change_text": "+0.07%p",
      "held": false,
      "date": "2026-10-22"
    },
    {
      "series": "credit_loan",
      "label": "신용융자 잔고",
      "value": 30.1,
      "unit": "조원",
      "change": -0.28,
      "change_text": "-0.28%",
      "held": false,
      "date": "2026-10-26"
    },
    {
      "series": "stock_loan",
      "label": "예탁증권담보융자",
      "value": 25.6,
      "unit": "조원",
      "change": -0.02,
      "change_text": "-0.02%",
      "held": false,
      "date": "2026-10-26"
    },
    {
      "series": "deposit",
      "label": "투자자 예탁금",
      "value": 88.7,
      "unit": "조원",
      "change": -1.31,
      "change_text": "-1.31%",
      "held": false,
      "date": "2026-10-26"
    },
    {
      "series": "forced_sale",
      "label": "미수금 반대매매 비중",
      "value": 1.2,
      "unit": "%",
      "change": 0.5,
      "change_text": "+0.5%p",
      "held": false,
      "date": "2026-10-26"
    }
  ],
  "value_vs_20d_avg": 0.98,
  "meta": {
    "as_of": "2026-10-29T00:03:14+09:00",
    "data_date": "2026-10-28",
    "lag_business_days": 1,
    "next_update": "10월 30일(금) 오전 11시 30분 전후",
    "source": "공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART · 한국거래소 통계정보",
    "license": "출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다",
    "disclaimer": "전일 마감 데이터이며 투자 참고용입니다. 특정 종목의 매수·매도를 권유하지 않습니다."
  }
}

percentiles 는 2020-04 이후 분포에서의 위치다. coverage_pct 는 재무가 있는 종목의 시총 비중.

봇·스크립트용 기록

발행 기록 · 원자료 · 갱신 신호

`GET /api/v1/published`	그날 실제로 내건 목록(발행 기록) — 발행 뒤 수정되지 않는다 (signal, from, to, cursor)
`GET /api/v1/published.csv`	발행 기록 CSV 일괄 받기 (signal)
`GET /api/v1/status`	기준일 · 속보/확정 · 목록별 마지막 발행 시각 · 다음 갱신 — 폴링 전에 이것부터
`POST /api/v1/keys`	무료 API 키 발급(선택) — {"email": ...}. 키를 X-API-Key 헤더로 보내면 분당 한도가 오른다
`GET /api/v1/stock/{code}/flow`	외국인·기관·개인 순매수(금액·수량) · 공매도 비중 — 없는 날 null (from, to)
`GET /api/v1/macro`	매크로 계열 목록 — 환율·금리·외국인 보유 비중·신용융자·예탁금·주택가격·가계부채 (최신값·주기·시작일)
`GET /api/v1/macro/{series}`	한 계열의 시계열 (from, to) — 월·분기 계열은 그 기간 마지막 날에 찍힌다

curl -s "https://maedong.kr/api/v1/status"
curl -s "https://maedong.kr/api/v1/published?signal=high-52w&from=2026-09-11"
curl -s "https://maedong.kr/api/v1/stock/005930/flow?from=2026-09-01"
curl -s "https://maedong.kr/api/v1/signals/high-52w/stats?entry=next_open&cost=statutory"
curl -s "https://maedong.kr/api/v1/macro/credit_loan?from=2026-01-01"

/status 의 수집 시각은 둘입니다. data_ingested_at 은 시세·수급 수집만의 마지막 시각이고, last_ingest_at 은 내부 정산·백필 작업까지 센 마지막 기록입니다(UTC).

발행 기록은 그날 실제로 내건 목록입니다. 과거 날짜로 /signals?date= 를 부르면 지금 규칙으로 다시 계산한 목록이 나옵니다 — 그날 내걸었던 목록은 /published 입니다. reachable_entry_krw 는 발행 시각 뒤 첫 09:00 시가입니다. r20_pct 는 판정과 같은 시그널일 종가 기준이라 두 값을 섞어 쓰지 마세요.

# 발행 기록으로 목록별 20거래일 성적 보기 (pandas)
import pandas as pd
df = pd.read_csv("https://maedong.kr/api/v1/published.csv")
done = df.dropna(subset=["r20_pct"])          # 검증 전(null)은 뺀다 — 0 이 아니다
print(done.groupby("signal")["r20_pct"].agg(["count", "mean", "median"]))

stats?entry= 의 next_open·published 는 참고 열입니다 — 판정(verdict)은 늘 종가 진입 기준입니다. cost=statutory 는 제도 비용(거래세·수수료)을 뺀 값을 더합니다 — 기간별 칸은 2026년 세율 왕복 0.23%, entry_variant 는 매도 결제일이 속한 해·시장의 세율을 행마다 뺍니다(cost_pct). flow 는 수급을 모으지 않은 날을 0 이 아니라 null 로 줍니다.

일봉 원시세(ohlcv·시세 CSV)는 제공하지 않습니다 — 시세 원천의 약관이 재배포를 금지합니다. 그 주소는 410 과 대안 주소를 돌려줍니다.

내린 목록: program-buy(2026-09-25, 종목별 프로그램매매 이력을 2026-06 이전으로 채울 길이 없어 목록에서 내렸다). 발행 기록에는 남아 있고 /signals·stats 는 404 입니다.

한도와 오류

요청 한도	IP 당 분당 60회. 넘으면 `429` 와 `Retry-After: 60` 을 줍니다.
수급	`/stock/{code}/flow` 는 하루 400회까지입니다(키와 무관, 한국 시각 자정에 다시 셈). 넘으면 `429` 입니다.
인증	필요 없습니다. 무료 키는 선택입니다 — `POST /api/v1/keys` 에 `{"email": "..."}` 를 보내 받은 키를 `X-API-Key` 헤더로 붙이면 분당 300회까지 됩니다. 틀린 키는 `401` 입니다.
갱신 확인	모든 GET 응답에 `ETag` 가 붙습니다. `If-None-Match` 로 보내면 바뀌지 않았을 때 `304` 입니다. 무엇이 바뀌었는지는 `/api/v1/status` 로 먼저 보세요.
CORS	`Access-Control-Allow-Origin: *` — 브라우저에서 바로 호출할 수 있습니다.
캐시	`Cache-Control: public, max-age=300`. 기준일이 하루 한 번 바뀌므로 그 이상 자주 부를 이유가 없습니다.
내 PC 백테스트 도구(베타)	내 PC 에서 내 한국투자증권·공공데이터포털 키로 이 API 와 같은 기준의 백테스트를 돌리는 도구를 무료 비공개 베타로 드립니다. 본인 키·계좌로만 쓸 수 있습니다. 받으려면 쓰실 용도를 적어 contact@maedong.kr 로 보내 주세요. 한도를 늘리는 문의도 같은 주소로 받습니다.
오류	`{"detail": "..."}` 형태의 JSON. 404(없는 목록·종목·날짜) · 400(형식) · 422(범위) · 429(한도).

계산 방법

성과는 매일 그 목록 상위 20종목을 그날 종가에 사서 N거래일 뒤 종가에 판 것으로 계산합니다. 거래비용·세금·슬리피지는 반영하지 않습니다. 비교 기준(market_avg_pct)은 같은 날들의 거래대금 10억 이상 전 종목 평균입니다 — 같은 날을 비교해야 장 전체가 오른 날의 상승이 시그널의 공으로 잡히지 않습니다.

/regime 은 모든 목록이 같은 거래일 창을 봅니다. 목록마다 '최근 60시그널일' 을 따로 잡으면 서로 다른 기간을 비교하게 되기 때문입니다. 20거래일이 지나 성과가 확정된 시그널만 세므로 창의 끝은 기준일보다 20거래일 앞입니다.

더 자세한 규칙은 규칙과 검증, 용어는 용어집에 있습니다. 과거 성과는 미래 수익을 보장하지 않습니다.

MCP 서버

AI 어시스턴트가 이 데이터를 직접 읽는 통로

Claude 같은 어시스턴트에 커스텀 커넥터로 붙이면, 화면을 긁지 않고 같은 계산 결과를 바로 받습니다. 주소는 아래 한 줄이고 인증은 없습니다.

https://maedong.kr/mcp

POST 전용입니다(JSON-RPC 2.0). 브라우저로 열면 405 가 뜨는 것이 정상입니다 — MCP 규격이 SSE 를 제공하지 않는 서버에 GET 405 를 요구합니다.

도구	하는 일
`maedong_signals`	Korean stock market (KOSPI/KOSDAQ) screener lists — which stocks are on a given trading day's signal lists (price, chart, value, and lists built on foreign/institutional net buying and short-selling activity), or the catalog of all lists.
`maedong_signal_stats`	Scored track record of a Korean stock screener list since 2020 — whether stocks on it beat, matched or lagged the market (the equal-weighted average of all stocks traded that day) 1/5/20 trading days later.
`maedong_stock_signals`	Signal history for one Korean stock (KOSPI/KOSDAQ) by its 6-digit code — which lists it appeared on and what happened after.
`maedong_chart_patterns`	Did classic chart patterns actually work in the Korean market? Golden cross, moving-average stack, RSI oversold and Bollinger bands scored over the entire population of KOSPI/KOSDAQ stocks since 2020, on daily/weekly/monthly bars.
`maedong_regime`	Which screener rules are currently working in the Korean market — recent excess-return ranking by list and by factor axis.
`maedong_market`	Korean market snapshot — KOSPI/KOSDAQ index levels, market breadth, valuation percentiles, and macro series (FX, bond yields, base rate).

도구가 주는 값은 공개 읽기 API와 같은 계산을 씁니다 — 두 곳에서 답이 갈리지 않습니다. AI 비서에 붙여 쓰는 지시문은 AI 비서에 매동 연결하기에 있습니다.

출처 표기

출처: 각 원천 · 원천 데이터의 이용 조건은 원천 약관을 따릅니다

원 데이터는 공공데이터포털 금융위원회 시세, 한국은행 ECOS, 금융감독원 DART 입니다. 시그널 정의·성과 집계·레짐 판정은 maedong.kr 이 계산한 값입니다. 표기 예:

출처: maedong.kr (원 데이터: 공공데이터포털 금융위원회 시세 · 한국은행 ECOS · 금융감독원 DART)

문의 contact@maedong.kr · 필드 추가가 필요하면 알려주세요.