krx-cli AI 에이전트 활용 가이드

krx-cli를 AI 에이전트와 연동하면, 자연어 대화만으로 한국 주식시장 데이터를 조회하고 분석할 수 있습니다. CLI(Bash tool)든 MCP든 동일한 데이터와 기능을 사용할 수 있으며, 아래 시나리오는 연동 방식에 관계없이 모두 동작합니다.

설치 및 연동 방법은 README를 참고하세요.

참고: KRX Open API 데이터는 T-1(전 거래일) 기준 확정 데이터이며, 실시간 시세가 아닙니다. 이 문서에서 "오늘"은 "가장 최근 거래일"을 의미합니다.

일상 투자 정보 조회
포트폴리오 모니터링
시장 분석 리포트 생성
종목 스크리닝
기간별 추세 분석
멀티 자산 비교 분석
리스크 모니터링
교육 및 학습 도우미
데이터 파이프라인 구축
투자 리서치 어시스턴트
전략 백테스트
도구 레퍼런스

1. 일상 투자 정보 조회

가장 기본적인 활용입니다. 증권 앱을 열지 않고 대화만으로 시장 정보를 확인합니다.

시나리오

사용자 요청	에이전트가 호출하는 Tool
"오늘 코스피 어때?"	`krx_index` (endpoint: kospi_dd_trd)
"삼성전자 주가 알려줘"	`krx_search` → `krx_stock` (isuCd 포함)
"오늘 금 시세 얼마야?"	`krx_commodity` (endpoint: gold_dd_trd)
"국채 수익률 보여줘"	`krx_bond` (endpoint: kts_bydd_trd)

대화 예시

사용자: 삼성전자 주가 알려줘

에이전트: (내부적으로 krx_search → krx_stock 호출)

삼성전자(005930) 최근 거래일 정보입니다:
- 종가: 72,400원
- 전일대비: +1,200원 (+1.68%)
- 거래량: 12,345,678주
- 거래대금: 893,456백만원
- 시가: 71,500원 / 고가: 72,800원 / 저가: 71,200원

사용자: 시장 전체적으로 어때?

에이전트: (krx_market_summary 호출)

최근 거래일 시장 요약입니다:

[KOSPI] 2,645.32 (+0.87%)
- 상승: 523종목 / 하락: 312종목
- 거래대금: 8.2조원

[KOSDAQ] 892.15 (+1.23%)
- 상승: 876종목 / 하락: 456종목
- 거래대금: 6.1조원

거래대금 상위: 삼성전자, SK하이닉스, LG에너지솔루션...
상승률 상위: OO전자(+29.8%), XX바이오(+18.5%)...

2. 포트폴리오 모니터링

워치리스트에 보유 종목을 등록해두면, 한 번의 질문으로 전체 포트폴리오 현황을 파악할 수 있습니다.

초기 설정 대화

사용자: 내 포트폴리오 종목 등록해줘. 삼성전자, SK하이닉스, NAVER, 카카오, LG에너지솔루션

에이전트:
  1. krx_search/krx stock search로 각 종목 검색
  2. 복수 결과가 나오면 보통주 선택 (예: "삼성전자" → 삼성전자보통주, 삼성전자1우선주)
  3. krx_watchlist add로 등록

워치리스트에 5개 종목을 등록했습니다:
1. 삼성전자보통주 (KR7005930003)
2. 에스케이하이닉스보통주 (KR7000660001)
3. NAVER보통주 (KR7035420009)
4. 카카오보통주 (KR7035720002)
5. LG에너지솔루션보통주 (KR7373220003)

참고: 종목명 검색 시 보통주/우선주가 모두 매칭되면 에이전트가 보통주를 선택합니다. KRX 공식 종목명에는 "보통주" 접미사가 포함되어 있습니다 (예: "삼성전자보통주"). 에이전트가 이 과정을 자동으로 처리합니다.

일일 모니터링

사용자: 내 포트폴리오 어때?

에이전트: (krx_watchlist action: show 호출)

최근 거래일 포트폴리오 현황입니다:

| 종목 | 종가 | 등락률 | 거래량 |
|------|------|--------|--------|
| 삼성전자 | 72,400 | +1.68% | 12.3M |
| SK하이닉스 | 185,000 | +2.22% | 5.6M |
| NAVER | 215,500 | -0.46% | 1.2M |
| 카카오 | 48,900 | +0.82% | 3.4M |
| LG에너지솔루션 | 378,000 | -1.05% | 0.8M |

전체적으로 5종목 중 3종목 상승, 2종목 하락입니다.
반도체 섹터(삼성전자, SK하이닉스)가 강세를 보이고 있습니다.

Resource 활용

에이전트는 krx://watchlist Resource를 읽어 별도 Tool 호출 없이도 현재 워치리스트 상태를 파악할 수 있습니다. Rate limit 현황(krx://rate-limit)도 Resource로 확인 가능합니다.

3. 시장 분석 리포트 생성

여러 Tool을 조합하여 에이전트가 종합적인 시장 분석 리포트를 작성합니다.

대화 예시

사용자: 오늘 시장 마감 후 리포트 좀 써줘. 코스피/코스닥 동향, 섹터별 흐름,
        특이 종목 정리해서.

에이전트: (순차적으로 여러 Tool 호출)
  1. krx_market_summary → 시장 요약
  2. krx_index (kospi) → KOSPI 전 지수
  3. krx_index (kosdaq) → KOSDAQ 전 지수
  4. krx_stock (kospi, sort: FLUC_RT, limit: 10) → 상승률 Top 10
  5. krx_stock (kospi, sort: FLUC_RT, sort_direction: asc, limit: 10) → 하락률 Top 10
  6. krx_stock (kospi, sort: ACC_TRDVAL, limit: 10) → 거래대금 Top 10
  7. krx_etp (etf, sort: FLUC_RT, limit: 5) → ETF 등락률 상위

==== 2026년 3월 20일 시장 마감 리포트 ====

1. 시장 개요
   KOSPI 2,645.32 (+0.87%), KOSDAQ 892.15 (+1.23%)
   양 시장 모두 상승 마감. 상승 종목 수가 하락 종목의 1.7배...

2. 섹터별 동향 (KOSPI 시리즈 지수 기준)
   - KRX 반도체: +2.1%
   - KRX 2차전지: -0.8%
   - KRX 바이오: +1.5%...

3. 특이 종목 (상승률/하락률/거래대금 상위)
   [급등] OO전자 +29.8% (거래대금 234B)
   [급락] XX건설 -15.2% (거래대금 89B)
   [거래 폭증] YY바이오 거래대금 567B (Top 5)...

4. ETF 동향
   KODEX 반도체 +2.3%, TIGER 2차전지 -1.1%...

활용 포인트

에이전트가 여러 Tool을 자율적으로 조합하여 데이터를 수집
수집된 정량 데이터에 에이전트의 분석/해석 능력을 결합
매일 같은 요청을 하면 일관된 형식의 리포트를 받을 수 있음
결과를 파일로 저장하거나 노트앱에 정리하도록 추가 요청 가능

4. 종목 스크리닝

특정 조건에 맞는 종목을 필터링하여 투자 후보군을 탐색합니다.

대화 예시

사용자: 코스피에서 오늘 5% 이상 오른 종목 찾아줘

에이전트: (krx_stock 호출, filter: "FLUC_RT > 5", sort: FLUC_RT)

오늘 KOSPI 시장에서 5% 이상 상승한 종목입니다:

| 종목명 | 종가 | 등락률 | 거래대금 |
|--------|------|--------|----------|
| OO전자 | 15,200 | +29.8% | 234,567M |
| XX소재 | 8,900 | +12.5% | 45,678M |
| YY화학 | 32,100 | +7.8% | 123,456M |
| ... | ... | ... | ... |

총 18종목이 해당됩니다.

사용자: 거래대금 상위 20개 종목 중에서 하락한 종목만 보여줘

에이전트:
  1. krx_stock (kospi, sort: ACC_TRDVAL, limit: 20) → 거래대금 Top 20
  2. 결과에서 FLUC_RT < 0 인 종목 필터링

거래대금 Top 20 중 하락 종목입니다:

| 종목명 | 종가 | 등락률 | 거래대금 |
|--------|------|--------|----------|
| AA건설 | 45,600 | -3.2% | 567,890M |
| BB엔터 | 12,300 | -1.5% | 345,678M |

2종목이 해당됩니다.
거래대금이 높은데 하락한 종목은 매도 압력이 강한 것으로 볼 수 있습니다.

사용자: ETF 중에서 레버리지/인버스 빼고 거래량 많은 순으로 10개만

에이전트: (krx_etp 호출, sort: ACC_TRDVOL, limit: 10,
          filter로 레버리지/인버스 제외)

일반 ETF 거래량 Top 10입니다:

1. KODEX 200 - 거래량 5,234,567주
2. TIGER 반도체 - 거래량 3,456,789주
...

5. 기간별 추세 분석

date_from/date_to (CLI에서는 --from/--to) 파라미터로 여러 날짜의 데이터를 한 번에 조회하여 추세를 분석합니다. 날짜별로 병렬 호출하므로 한 번의 요청으로 수십 거래일의 데이터를 받을 수 있습니다.

대화 예시

사용자: 삼성전자 최근 2주간 주가 추이 알려줘

에이전트: (krx_stock 호출, date_from: 20260306, date_to: 20260320,
          isuCd: KR7005930003)

삼성전자(005930) 최근 2주 주가 추이입니다:

| 날짜 | 종가 | 등락률 | 거래량 |
|------|------|--------|--------|
| 03/06 | 69,800 | -0.57% | 11.2M |
| 03/09 | 70,200 | +0.57% | 10.8M |
| 03/10 | 71,000 | +1.14% | 13.5M |
| ... | ... | ... | ... |
| 03/20 | 72,400 | +1.68% | 12.3M |

2주간 +3.7% 상승했습니다.
3/10 이후 꾸준히 상승세를 유지하고 있으며,
거래량도 점진적으로 증가하는 패턴입니다.

사용자: 이번 달 코스피 지수 흐름을 차트로 설명해줘

에이전트: (krx_index 호출, market: kospi, date_from: 20260301, date_to: 20260320)

3월 KOSPI 지수 흐름입니다:

2,620 |                                    *
2,610 |                              * *  *
2,600 |          *  *           *  *
2,590 |    *  *     *  *     *
2,580 | *              *  *
      +----+----+----+----+----+----+----
       3/3  3/5  3/7 3/10 3/12 3/14 3/17 3/19

- 월초 2,580대에서 출발하여 현재 2,645까지 상승 (+2.5%)
- 3/7~3/12 조정 구간 이후 반등
- 최근 5거래일 연속 상승 중

6. 멀티 자산 비교 분석

주식, ETF, 채권, 원자재 등 서로 다른 자산군의 데이터를 조합하여 비교합니다.

대화 예시

사용자: 오늘 주식, 채권, 금, 유가 전체적으로 어떻게 됐는지 한눈에 정리해줘

에이전트: (병렬로 여러 Tool 호출)
  1. krx_index (kospi) → 주식
  2. krx_bond (kts) → 국채
  3. krx_commodity (gold) → 금
  4. krx_commodity (oil) → 유가

오늘의 멀티 자산 현황입니다:

| 자산군 | 지표 | 현재 | 등락 |
|--------|------|------|------|
| 주식 | KOSPI | 2,645.32 | +0.87% |
| 주식 | KOSDAQ | 892.15 | +1.23% |
| 채권 | 국고채 3년 | 3.125% | -0.02%p |
| 채권 | 국고채 10년 | 3.456% | -0.03%p |
| 원자재 | KRX 금 (g) | 92,450원 | +0.5% |
| 원자재 | KRX 원유 | 78,200원 | -1.2% |

분석:
- 주식/채권 동반 상승 (금리 하락 → 채권 가격 상승)
- 금 소폭 상승, 유가 하락 → 인플레이션 압력 완화 시그널
- Risk-on 분위기로 해석됩니다

사용자: KODEX 200 ETF와 KOSPI 지수의 괴리율 확인해줘

에이전트:
  1. krx_index (kospi, fields: [CLSPRC_IDX]) → KOSPI 종가
  2. krx_etp (etf, isuCd: KODEX200코드, fields: [TDD_CLSPRC, NAV]) → ETF 종가/NAV

KODEX 200 vs KOSPI 200 괴리율:
- KODEX 200 시장가: 35,425원
- NAV(순자산가치): 35,410원
- 괴리율: +0.04% (거의 없음)
- 정상 범위 내에서 추적이 잘 되고 있습니다.

7. 리스크 모니터링

급변하는 시장 상황이나 특정 이벤트 발생 시 빠르게 상황을 파악합니다.

대화 예시

사용자: 오늘 하한가 종목 있어?

에이전트: (krx_stock, filter: "FLUC_RT < -25", sort: FLUC_RT, sort_direction: asc)

오늘 코스피+코스닥에서 -25% 이상 하락한 종목입니다:

| 종목 | 시장 | 종가 | 등락률 | 사유 |
|------|------|------|--------|------|
| XX제약 | KOSDAQ | 3,200 | -29.9% | 하한가 |
| YY홀딩스 | KOSPI | 8,100 | -26.3% | - |

2종목이 급락했습니다. 공시 확인을 권장드립니다.

사용자: 내 워치리스트 종목 중에 오늘 3% 이상 빠진 거 있어?

에이전트:
  1. krx://watchlist Resource로 워치리스트 확인
  2. krx_watchlist (action: show) 호출
  3. 등락률 < -3% 필터링

워치리스트 종목 중 오늘 3% 이상 하락한 종목:

- LG에너지솔루션: -3.8% (378,000원)
  → 최근 5일 -7.2% 하락 추세

나머지 4종목은 -3% 이내입니다.
주의가 필요합니다.

사용자: 파생상품 시장 변동성은 어때?

에이전트:
  1. krx_derivative (opt_bydd_trd) → 옵션 전체 데이터 (12,000건+)
  2. RGHT_TP_NM(CALL/PUT) 기준으로 ACC_TRDVOL 합산하여 P/C Ratio 계산
  3. krx_derivative (fut_bydd_trd) → 선물 데이터

KOSPI200 옵션 시장 현황:
- CALL 총거래량: 852,457계약
- PUT 총거래량: 735,870계약
- Put/Call Ratio: 0.86

선물 시장:
- KOSPI200 선물: 351.25 (-0.92%)
- 미결제약정(ACC_OPNINT_QTY): 245,678계약

참고: P/C Ratio는 옵션 데이터의 RGHT_TP_NM 필드(CALL/PUT)별
ACC_TRDVOL을 합산하여 에이전트가 계산합니다.

8. 교육 및 학습 도우미

금융 초보자나 학생이 실제 시장 데이터를 기반으로 학습합니다.

대화 예시

사용자: ETF가 뭔지 설명해주고, 실제 KRX에서 거래되는 ETF 몇 개 보여줘

에이전트: (krx_etp 호출, type: etf, sort: ACC_TRDVAL, limit: 5)

ETF(Exchange Traded Fund)는 특정 지수를 추적하는 펀드를
주식처럼 거래소에서 매매할 수 있는 상품입니다.

현재 KRX에서 거래되는 ETF 거래대금 상위 5개:

| ETF명 | 추적지수 | 종가 | 등락률 | 거래대금 |
|-------|---------|------|--------|---------|
| KODEX 200 | KOSPI 200 | 35,425 | +0.9% | 567B |
| TIGER 반도체 | KRX 반도체 | 12,340 | +2.1% | 345B |
| ... | ... | ... | ... | ... |

예를 들어 KODEX 200은 KOSPI 200 지수를 추적하므로,
이 ETF 1주를 사면 KOSPI 200에 포함된 200개 기업에
분산 투자하는 효과가 있습니다.

사용자: 채권 수익률이 뭔지 실제 데이터로 설명해줘

에이전트: (krx_bond, endpoint: kts_bydd_trd)

채권 수익률은 채권의 연간 투자 수익을 나타냅니다.

오늘 국채전문유통시장(KTS) 기준:

| 채권 | 수익률 | 가격 |
|------|--------|------|
| 국고채 1년 | 2.85% | 99,234 |
| 국고채 3년 | 3.12% | 97,456 |
| 국고채 10년 | 3.45% | 92,123 |

핵심 포인트:
- 만기가 길수록 수익률이 높음 → "기간 프리미엄"
- 수익률 상승 = 채권 가격 하락 (역의 관계)
- 국고채 3년물은 한국은행 기준금리의 시장 기대를 반영

9. 데이터 파이프라인 구축

MCP를 코드 작성 에이전트(Claude Code 등)와 결합하면, 데이터 수집부터 분석까지 한 번의 대화로 처리할 수 있습니다.

시나리오 A: 스프레드시트 생성

사용자: 코스피 거래대금 상위 50개 종목 데이터를 CSV로 만들어줘.
        종목명, 종가, 등락률, 거래량, 거래대금 포함해서.

에이전트:
  1. krx_stock (kospi, sort: ACC_TRDVAL, limit: 50,
     fields: [ISU_NM, TDD_CLSPRC, FLUC_RT, ACC_TRDVOL, ACC_TRDVAL])
  2. 결과를 CSV 형식으로 변환
  3. 파일로 저장

kospi_top50_20260320.csv 파일을 생성했습니다.
50개 종목의 데이터가 포함되어 있습니다.

시나리오 B: 분석 스크립트 생성

사용자: KOSPI 거래대금 상위 10 종목의 등락률 분포를
        시각화하는 Python 스크립트 만들어줘.
        데이터는 krx CLI에서 가져오도록.

에이전트: (krx_schema 호출로 필드 구조 확인 후 코드 작성)

# krx CLI의 JSON 출력을 subprocess로 호출하는 Python 스크립트 생성
# 예: subprocess.run(["krx", "stock", "list", "--market", "kospi",
#      "--sort", "ACC_TRDVAL", "--limit", "10", "-o", "json"])

정기 실행: 매일 자동으로 돌리려면 에이전트가 생성한 스크립트를 cron이나 GitHub Actions로 스케줄링하면 됩니다. MCP 자체는 데이터 접근 프로토콜이므로 스케줄링은 별도 구성이 필요합니다.

시나리오 C: 로컬 투자 노트 업데이트

사용자: 내 투자 노트(investment-log.md)에 시장 데이터 추가해줘

에이전트:
  1. krx_market_summary → 시장 요약 수집
  2. krx_watchlist (show) → 보유 종목 현황 수집
  3. investment-log.md 파일에 오늘 날짜 섹션 추가

10. 투자 리서치 어시스턴트

에이전트의 추론 능력과 KRX 시장 데이터를 결합하여 심층 리서치를 수행합니다.

대화 예시

사용자: 반도체 관련주 분석해줘. 최근 1주일 동향이랑 같이.

에이전트:
  1. krx_index (kospi) → KOSPI 시리즈 중 "KRX 반도체" 지수 확인
  2. 에이전트 지식으로 주요 반도체 종목 목록 파악
     (krx_search는 종목명 기반이므로 "삼성전자"는 검색 불가)
  3. krx_stock (date_from~date_to, isuCd로 개별 종목 조회) → 1주일 추이
  4. krx_etp (etf, filter로 "반도체" 포함 ETF) → 섹터 ETF 동향

=== 반도체 섹터 리서치 ===

1. 섹터 지수: KRX 반도체 지수 1주일 +4.2%
   (KOSPI 시리즈 지수 데이터에서 IDX_NM으로 필터링)

2. 주요 종목 1주일 성과:
   - 삼성전자: +3.7% (72,400원)
   - SK하이닉스: +5.8% (185,000원)
   - 한미반도체: +8.2% (12,300원)
   - DB하이텍: +1.2% (45,600원)

3. 섹터 ETF:
   - TIGER 반도체: +4.5% (거래대금 345B)
   - KODEX 반도체: +4.3%

4. 관찰 포인트:
   - 지수 대비 개별 종목 성과 차이가 큼
   - 장비주(한미반도체)가 가장 높은 상승률
   - 섹터 ETF 거래대금 증가 추세

사용자: 거래가 활발한 대형주 중에서 시가총액 대비 거래대금 비율이
        높은 종목 알려줘

에이전트:
  1. krx_stock (kospi, sort: ACC_TRDVAL, limit: 50,
     fields: [ISU_NM, TDD_CLSPRC, ACC_TRDVAL, MKTCAP, FLUC_RT])
  2. ACC_TRDVAL / MKTCAP 비율 계산 (회전율 대용치)

거래대금 상위 50 종목의 시가총액 대비 거래대금 비율입니다:

| 종목 | 종가 | 거래대금 | 시가총액 | 회전율 |
|------|------|----------|----------|--------|
| OO바이오 | 45,600 | 567B | 2.3T | 24.7% |
| XX소재 | 8,900 | 234B | 1.1T | 21.3% |
| YY전자 | 32,100 | 345B | 5.6T | 6.2% |
| ... | ... | ... | ... | ... |

회전율이 높은 종목은 단기 거래 관심이 집중된 상태입니다.

참고: KRX Open API는 배당, 외국인/기관 매매, 재무제표 데이터를
제공하지 않으므로, 이런 정보가 필요하면 DART나 증권사 API를
병행하시는 것을 권장합니다.

11. 전략 백테스트

KRX Open API는 2010년부터의 일별 OHLCV(시가/고가/저가/종가/거래량) 데이터를 제공합니다. date_from/date_to로 과거 데이터를 가져와 에이전트가 직접 전략을 검증하거나, 백테스트 코드를 생성할 수 있습니다.

사용 가능한 데이터

자산	필드	비고
주식	TDD_OPNPRC, TDD_HGPRC, TDD_LWPRC, TDD_CLSPRC, ACC_TRDVOL, FLUC_RT, MKTCAP	종목별 isuCd 필터
지수	OPNPRC_IDX, HGPRC_IDX, LWPRC_IDX, CLSPRC_IDX, ACC_TRDVOL, FLUC_RT	IDX_NM으로 지수 선택
ETF	TDD_CLSPRC, NAV, ACC_TRDVOL, IDX_IND_NM, FLUC_RT	NAV로 괴리율 추적
선물	TDD_CLSPRC, SETL_PRC, ACC_OPNINT_QTY	정산가, 미결제약정 포함

시나리오 A: 대화 내에서 간단한 백테스트

사용자: KOSPI가 1주일간 3% 이상 하락한 뒤 매수해서 5거래일 보유하면
        수익이 나는지 최근 1년 데이터로 확인해줘

에이전트:
  1. krx_index (kospi_dd_trd, date_from: 20250320, date_to: 20260320)
     → 약 250거래일의 KOSPI 지수 데이터 수신
  2. 에이전트가 데이터 내에서 직접 계산:
     - 5일 수익률이 -3% 이하인 시점 탐색
     - 각 시점에서 매수 후 5거래일 뒤 수익률 계산

=== 백테스트 결과 ===

조건: KOSPI 5일 수익률 < -3% 시점에 매수 → 5거래일 보유
기간: 2025.03 ~ 2026.03 (약 250거래일)

발생 횟수: 7회

| 매수일 | 매수 지수 | 매도 지수 | 수익률 |
|--------|----------|----------|--------|
| 2025-04-15 | 2,482 | 2,531 | +1.97% |
| 2025-06-22 | 2,545 | 2,512 | -1.30% |
| 2025-08-05 | 2,398 | 2,456 | +2.42% |
| ... | ... | ... | ... |

평균 수익률: +1.23%
승률: 5/7 (71.4%)
최대 손실: -1.30%

주의: 7회는 통계적으로 유의미하지 않습니다.
더 긴 기간으로 검증하시겠습니까?

시나리오 B: 이동평균 크로스 전략

사용자: 삼성전자에 골든크로스(5일선이 20일선 상향돌파) 전략을 적용하면
        어떤 결과가 나오는지 6개월치로 보여줘

에이전트:
  1. krx_stock (stk_bydd_trd, date_from: 20250920, date_to: 20260320,
     isuCd: KR7005930003)
     → 약 125거래일의 삼성전자 일별 데이터
  2. TDD_CLSPRC(종가) 기준 5일/20일 이동평균 계산
  3. 크로스 시점 탐색 및 수익률 계산

=== 골든크로스 백테스트: 삼성전자 ===

기간: 2025.09 ~ 2026.03
전략: 5일 MA > 20일 MA 진입, 5일 MA < 20일 MA 청산

시그널 발생: 4회

| 진입일 | 진입가 | 청산일 | 청산가 | 수익률 | 보유일수 |
|--------|-------|--------|-------|--------|---------|
| 10/08 | 68,200 | 10/28 | 71,500 | +4.84% | 14일 |
| 11/18 | 69,100 | 12/05 | 67,800 | -1.88% | 12일 |
| 01/12 | 70,500 | 02/20 | 73,200 | +3.83% | 28일 |
| 03/05 | 71,000 | - | 72,400 | +1.97% | 보유중 |

누적 수익률: +8.93%
같은 기간 Buy & Hold: +6.16%
초과 수익: +2.77%

시나리오 C: ETF 로테이션 전략

사용자: KODEX 200이랑 KODEX 국채선물10년 두 개로 모멘텀 로테이션하면
        어떻게 되는지 테스트해줘. 매월 초 전월 수익률 높은 쪽에 투자.

에이전트:
  1. krx_etp (etf, date_from: 20250320, date_to: 20260320,
     isuCd: KODEX200코드) → 주식 ETF 1년
  2. krx_etp (etf, date_from: 20250320, date_to: 20260320,
     isuCd: KODEX국채코드) → 채권 ETF 1년
  3. 월별 수익률 비교 후 로테이션 시뮬레이션

=== 듀얼 모멘텀 로테이션 백테스트 ===

기간: 2025.04 ~ 2026.03 (12개월)
규칙: 매월 초, 전월 수익률이 높은 ETF에 100% 투자

| 월 | 선택 ETF | 수익률 |
|----|---------|--------|
| 04 | KODEX 200 | +2.1% |
| 05 | KODEX 200 | -1.3% |
| 06 | 국채선물10년 | +0.8% |
| ... | ... | ... |

누적 수익률: +9.2%
KODEX 200 Buy & Hold: +7.1%
국채선물 Buy & Hold: +3.8%
최대 낙폭(MDD): -4.5% (vs KODEX 200 단독 -8.2%)

시나리오 D: 백테스트 코드 생성

사용자: 위 모멘텀 전략을 Python 코드로 만들어줘.
        파라미터 바꿔서 다시 돌릴 수 있게.

에이전트:
  1. krx_schema → 필드 구조 확인
  2. Python 스크립트 생성 (subprocess로 krx CLI 호출)

# 에이전트가 생성하는 코드 예시:
# - krx CLI로 데이터 수집 (subprocess)
# - pandas로 월별 수익률 계산
# - 로테이션 로직 + 성과 지표(누적수익률, MDD, 샤프비율)
# - matplotlib 시각화

Rate Limit 참고

조회 기간	예상 API 호출 수	비고
1개월	~22회/종목	거래일 기준
6개월	~125회/종목	캐시 사용 시 재조회 무료
1년	~250회/종목	일 10,000건 한도 내 충분
3년	~750회/종목	여러 종목 병행 시 주의

한계: 배당 데이터가 없으므로 총수익률(배당 재투자 포함) 계산은 불가합니다. 가격 수익률 기준의 백테스트만 가능합니다. 분봉/틱 데이터가 없으므로 일봉 기반 전략만 테스트할 수 있습니다.

도구 레퍼런스

에이전트가 내부적으로 호출하는 도구 목록입니다. CLI에서는 서브커맨드(krx index list), MCP에서는 Tool(krx_index)로 동일한 기능을 사용합니다.

기능	CLI 명령어	MCP Tool	주요 파라미터
지수 조회	`krx index list`	`krx_index`	--market, --date, --from/--to
주식 조회	`krx stock list`	`krx_stock`	--market, --date, --code, --sort, --limit
종목 검색	`krx stock search`	`krx_search`	검색어
ETF/ETN/ELW	`krx etp list`	`krx_etp`	--type, --date
채권 조회	`krx bond list`	`krx_bond`	--market, --date
파생상품	`krx derivative list`	`krx_derivative`	--type, --date
일반상품	`krx commodity list`	`krx_commodity`	--type, --date
ESG	`krx esg list`	`krx_esg`	--type, --date
시장 요약	`krx market summary`	`krx_market_summary`	--date
워치리스트	`krx watchlist`	`krx_watchlist`	add/remove/list/show
스키마 조회	`krx schema`	`krx_schema`	엔드포인트명
Rate Limit	`krx cache status`	`krx_rate_limit`	-

공통 파라미터 패턴

# 특정 종목만 조회
--code KR7005930003  (또는 005930)

# 기간 조회 (여러 날짜 한 번에)
--from 20260301 --to 20260320

# 필터링
--filter "FLUC_RT > 5"        # 등락률 5% 이상

# 정렬 + 제한
--sort FLUC_RT --limit 10     # 등락률 Top 10

# 필드 선택 (응답 크기 절약)
--fields ISU_NM,TDD_CLSPRC,FLUC_RT

주의사항

데이터 시차: KRX 데이터는 T-1(전 거래일) 기준 확정 데이터이며, 실시간 시세가 아닙니다
Rate Limit: 일 10,000건 제한이 있으므로, 기간 조회 시 날짜 범위를 적절히 설정하세요
서비스 승인: 각 카테고리(주식, 채권, 파생상품 등)별로 KRX Open API 포털에서 별도 승인이 필요합니다
제공하지 않는 데이터: KRX Open API는 다음 데이터를 포함하지 않습니다. 필요 시 DART, 증권사 API 등을 병행하세요:
- 배당 정보 (배당금, 배당수익률)
- 투자자별 매매 동향 (외국인/기관/개인 순매수)
- 재무제표 (매출, 영업이익, PER/PBR 등)
- 공시/뉴스
- 실시간 호가/체결
에이전트 해석: 에이전트가 데이터에 덧붙이는 분석(섹터 전망, 시장 해석 등)은 에이전트 자체 지식에 기반한 것이며, KRX API에서 제공하는 정보가 아닙니다
투자 판단: 에이전트의 분석은 참고용이며, 최종 투자 판단은 본인 책임입니다

FilesExpand file tree

AGENT-USE-CASES.md

Latest commit

History

AGENT-USE-CASES.md

File metadata and controls

krx-cli AI 에이전트 활용 가이드

목차

1. 일상 투자 정보 조회

시나리오

대화 예시

2. 포트폴리오 모니터링

초기 설정 대화

일일 모니터링

Resource 활용

3. 시장 분석 리포트 생성

대화 예시

활용 포인트

4. 종목 스크리닝

대화 예시

5. 기간별 추세 분석

대화 예시

6. 멀티 자산 비교 분석

대화 예시

7. 리스크 모니터링

대화 예시

8. 교육 및 학습 도우미

대화 예시

9. 데이터 파이프라인 구축

시나리오 A: 스프레드시트 생성

시나리오 B: 분석 스크립트 생성

시나리오 C: 로컬 투자 노트 업데이트

10. 투자 리서치 어시스턴트

대화 예시

11. 전략 백테스트

사용 가능한 데이터

시나리오 A: 대화 내에서 간단한 백테스트

시나리오 B: 이동평균 크로스 전략

시나리오 C: ETF 로테이션 전략

시나리오 D: 백테스트 코드 생성

Rate Limit 참고

도구 레퍼런스

공통 파라미터 패턴

주의사항