실시간 수급·가격 분석 · 강의 실습 배포

코스피200 · 개별주 수급 분석 대시보드

키움 REST API 실데이터 · 외국인/기관/개인 수급, 지지/저항, 장중 수급 흐름, 나스닥 선물을 한 화면에서 — 매매 판단 보조 대시보드 실습 키트

전달 대상 · 김성범 님

SRC 소스코드 1식 (39파일) DATA 키움 REST 실데이터 연동 DOC 강의문서 3종 STACK Python · FastAPI · WebSocket

⚠️ 교육·실습용입니다. 투자 자문이 아닙니다. 실습 키트는 키 없이 목데이터로 즉시 동작하고, 키움 API 키를 .env에 넣으면 실데이터로 전환됩니다. 신호는 규칙 기반이라 실거래 전 백테스트 검증이 필요합니다.

⬇ 실습 키트 다운로드

소스코드 전체 + 강의문서 3종(docs/) + 키움 연결 검증 스크립트(scripts/) 포함. 비밀키·가상환경 제외로 안전. 압축 해제 후 docs/02_학생_설치_및_실행_가이드.md 부터 보세요.

실습 키트 받기 .zip · 53KB

01 / 정의

이 앱은 무엇인가

미래 가격을 "맞히는" 게 아니라, 현재 시장 상황을 근거와 함께 정리해 주는 매매 의사결정 보조 도구. 최종 매매는 사람이 한다.

기능	설명
실시간 시세	코스피200·개별주 현재가 (장중/장마감 상태 표시)
과거 흐름	약 1년치 일봉 캔들차트 + 지지/저항선
투자자 수급	외국인·기관·개인 순매수 (당일 잠정 + 5·20일 누적)
장중 수급 흐름	시간대별 누적 순매수 + 가격을 한 차트에 (직전 거래일/실시간)
지지 / 저항	피벗·스윙·매물대(POC)·이평선 자동 계산
나스닥 연동	나스닥100 선물을 장중 위험선호 지표로 표시
진출입 제안	위 요소 종합 → 매수/중립/매도 + 판단 근거
데이터 출처 배지	카드마다 실시간/직전거래일/지연/예시 표시

02 / 기술

기술 스택 · 데이터 소스

구분	기술 / 소스	비고
언어·서버	Python 3.11 · FastAPI · WebSocket	비동기 실시간 푸시
차트	TradingView Lightweight Charts	캔들 + 이중축 라인
국내 시세·수급	키움 REST API	ka10001·ka10081·ka10059·ka10064
코스피200 지수	키움 업종 TR	ka20001·ka20006 (값 ÷100)
나스닥100 선물	Yahoo NQ=F	키움 해외선물은 OCX(Win전용) → Yahoo, 약 15분 지연

💡 핵심 설계 — Provider 추상화 + 자동 폴백. 데이터 원천을 목 ↔ 실데이터로 갈아끼우고, 키움 호출이 실패하면 그 항목만 목데이터로 폴백해 대시보드가 죽지 않습니다. 카드별 출처를 추적해 실데이터/근사치/예시를 배지로 구분합니다.

03 / 상태

현재 구현 단계

✓
실데이터 완료 (개별종목) · 현재가·1년 일봉·투자자 수급·지지저항·진출입 신호 — 모두 키움 실데이터
✓
장중 수급 흐름 차트 · 시간대별 외국인/기관/개인 누적 + 가격 (장마감=직전 거래일, 장중=실시간 전환)
✓
장중/장마감 상태 · 데이터 출처 배지 · 실시간/직전거래일/지연/예시 구분
◐
부분 실데이터 · 코스피200 가격(실)·수급(대형주 바스켓 근사) / 나스닥 선물(Yahoo 지연)
○
다음 · 백테스트 · 실시간 체결 WebSocket · 지수 시간대별 흐름 · 수집 데이터 저장

04 / 실행

내 컴퓨터에서 실행하기

압축을 푼 폴더 안에서 터미널로 순서대로. 키 없이 목데이터로 바로 동작합니다.

가상환경 — python3 -m venv .venv
활성화 — source .venv/bin/activate
설치 — pip install -r requirements.txt
실행 — python run.py
브라우저 http://localhost:8000

키움 실데이터로 전환: cp .env.example .env → 앱키/시크릿 입력 → python scripts/test_connection.py 로 연결 검증 → 다시 python run.py. 헤더 배지가 실데이터로 바뀝니다. (.env 키는 절대 공유 금지 · 압축엔 미포함)

05 / 확장

Claude Code로 이어서 개발

폴더에서 claude 실행 → 이 프로젝트를 이해한 상태로 시작. 추천 순서:

1 백테스트→ 2 실시간 체결 WebSocket→ 3 지수 시간대별 흐름→ 4 데이터 저장

첫 지시문 예시 — 그대로 복사해 붙여넣기:

# 1단계: 백테스트 모듈
src/backtest/ 폴더를 만들고 백테스트 모듈을 구현해줘.
- 키움 일봉(과거 1년)에 signals.build_signal 규칙을 하루씩 적용
- BUY 진입, 손절/목표 도달 또는 반대신호에 청산
- 총 거래수·승률·평균 손익비·누적수익률·최대낙폭(MDD)을 표로 출력
- 대시보드에 '백테스트' 탭으로도 볼 수 있게 해줘
먼저 계획을 설명하고, 동의하면 구현해줘.

🎯 Claude Code 잘 쓰는 법. "좋게 해줘"❌ 보다 "signals.py의 나스닥 가중치를 0.2로 올려줘"⭕ 처럼 파일과 목표를 구체적으로. 나머지 단계별 지시문은 다운로드 안 docs/03_다음단계_ClaudeCode_지시문.md에 있습니다.

06 / 문서

키트에 포함된 강의 문서

파일	내용
01_앱소개_및_기술서.md	앱 정의·기술 스택·아키텍처·키움 TR·현재 단계·한계
02_학생_설치_및_실행_가이드.md	설치→목데이터 실행→키움 실데이터 전환→Claude Code
03_다음단계_ClaudeCode_지시문.md	이어서 개발할 때 복사-붙여넣는 지시문 모음