키움 주식 자동매매 대시보드 개발 일지 — 기획부터 구현까지
요즘 저처럼 주식 자동매매에 관심 갖고 계신 분들 많으시죠? 🤖
저는 주식에 관심이 많아서 이것저것 알아보던 중, 키움증권 OpenAPI+를 활용해 나만의 주식 자동매매 대시보드를 직접 만들어보기로 했습니다. 시중에 나온 자동매매 프로그램도 많지만, 내 손으로 직접 만들어보면 매매 전략도 마음대로 바꿀 수 있고 리스크 관리도 내 기준으로 설계할 수 있으니까요.
오늘은 그 개발 일지를 기획 단계부터 구현 단계까지 정리해서 공유합니다.
📌 한줄 요약: 키움 OpenAPI+ + Python(FastAPI) + React로 만든 주식 자동매매 대시보드. 자동매매 엔진, 리스크 가드, 볼린저 밴드 스크리닝, 텔레그램 알림까지 — 3주 만에 기획부터 배포까지 완성한 개발 일지.
📋 전체 일정 한눈에 보기
| 단계 | 내용 | 상태 |
|---|---|---|
| 1 | 기획 — 왜 만들었나, 요구사항 정리 | ✅ |
| 2 | 기술 스택 선정 (FastAPI + React + 키움 OpenAPI+) | ✅ |
| 3 | 초기 이관 & 기본 구조 잡기 | ✅ |
| 4 | 메인화면 — 국내·해외 지수 | ✅ |
| 5 | 관심목록 & 차트 진단 연결 | ✅ |
| 6 | 텔레그램 아침 리포트 봇 | ✅ |
| 7 | 대시보드 AI 채팅 (자연어 조회) | ✅ |
| 8 | 자동매매 엔진 & 전략 프리셋 5종 | ✅ |
| 9 | 볼린저 밴드 스크리닝 + 승인형 자동매수 | ✅ |
| 10 | 수익률 / 보호설정 / 공매도 분석 | ✅ |
| 11 | 리스크 관리 시스템 (리스크 가드) | ✅ |
1️⃣ 시작 단계 — 왜 만들었나
주식을 하다 보면 이런 생각이 들 때가 있죠.
- “새벽에 눈 뜨자마자 미국장 확인하는 게 지겹다” 😪
- “급등하는 종목을 놓쳐서 아쉽다”
- “매도 타이밍을 기계적으로 정해두고 싶다”
저는 특히 감정적인 매매를 막고 싶었습니다. 사람은 손실이 커질수록 손절을 미룬다거나, 조금 오르면 바로 팔아버리는 실수를 하기 마련이니까요. 그래서 정한 목표는 이랬습니다.
- ✅ 매매 전략을 규칙으로 정의하고, 규칙이 발동하면 자동으로 주문
- ✅ 잘못된 매매로 큰 손실이 나지 않도록 강력한 리스크 관리
- ✅ 매일 아침 관심종목 리포트를 텔레그램으로 수신
- ✅ 대시보드에서 내 계좌/전략/수익률을 한눈에 확인
2️⃣ 기술 스택 선정
| 영역 | 기술 | 선택 이유 |
|---|---|---|
| 백엔드 | Python + FastAPI | 키움 OpenAPI+가 Python 연동을 잘 지원하고, 개발 속도가 빠름 |
| 프런트 | React + Vite + TypeScript | 실시간 데이터를 표로/차트로 깔끔하게 보여주기 좋음 |
| 데이터 저장 | SQLite (SQLModel) | 개인용이면 충분하고 설치/백업이 간단 |
| 매매 연동 | 키움증권 OpenAPI+ (REST + 실시간 웹소켓) | 국내 증권사 API 중 가장 자료가 많고 안정적 |
| 알림 | 텔레그램 봇 | 무료이고 API가 간단, 모바일 알림까지 한 번에 |
| AI 어시스턴트 | Hermes 에이전트 연동 | 대시보드에서 자연어로 잔고/공시/지수 조회 가능 |
3️⃣ 초기 이관 & 기본 구조
기존에 만들어두던 프로젝트를 git으로 이관하면서 시작했습니다. 구조는 크게 두 갈래입니다.
kiwoom-dashboard/
├── backend/ # FastAPI 서버 (:8002)
│ └── app/
│ ├── api/ # 라우트 (계좌/주문/자동매매/차트/공시...)
│ ├── services/ # 비즈니스 로직
│ └── kiwoom_client/ # 키움 OpenAPI+ 연동 (TR 매핑, 웹소켓)
└── frontend/ # React + Vite (:5173)
└── src/pages/ # 메인/관심목록/수동매매/자동매매/차트/계좌...
⚠️ 여기서 가장 중요한 함정 하나! 키움 OpenAPI+는 TR(Transaction) 요청에 초당 제한이 있습니다. 이 프로젝트에서는 4 req/s로 rate limit을 걸어 과도한 요청이 쌓이지 않게 했어요.
4️⃣ 메인화면 — 국내·해외 지수
메인 화면에 오늘의 시장 상황을 한눈에 보여주고 싶었습니다.
- 국내 지수 (KOSPI, KOSDAQ) → 키움 TR로 실시간 조회
- 해외 지수 (다우, 나스닥, 닛케이, 상해) → 키움 REST에는 해외 지수 TR이 없어서 Yahoo Finance API로 대체
메인 대시보드 — KOSPI/KOSDAQ(키움 TR) + 다우/나스닥/닛케이/상해(Yahoo Finance 폴백)
# 해외지수는 키움에 TR이 없어 Yahoo Finance로 폴백 (요약)
def get_global_indices():
symbols = {"^DJI": "다우", "^IXIC": "나스닥", "^N225": "닛케이", "000001.SS": "상해"}
for symbol, name in symbols.items():
price = yfinance.download(symbol, period="1d") # 최신가 조회
...
이렇게 하니 국내/해외 시장 상황이 한 화면에 정리됐습니다. 👍
5️⃣ 관심목록 & 차트 진단
관심 종목을 저장하고, 종목을 클릭하면 차트 분석 페이지로 바로 이동하도록 만들었습니다.
관심목록 → 종목 클릭 → 차트 페이지 (종목코드 + 이름 전달)
관심목록 — 저장한 종목들이 시세와 함께 표시
수동매매 화면 — 직접 종목을 골라 주문을 낼 수 있는 페이지
차트 페이지에서는 일봉/분봉 캔들 + 보조지표(이동평균, RSI, MACD 등)를 함께 볼 수 있습니다.
종목 상세 — 005930 삼성전자 시세/거래량 (2026-08-12, +4.13%)
보조지표 — RSI 45.5, MACD, 거래량 4,640,323 (-5.4%)
6️⃣ 텔레그램 아침 리포트 봇
매일 아침 08:00에 텔레그램으로 이런 리포트가 옵니다. 🌅
- 관심종목 시세 요약
- 관련 뉴스 (구글 뉴스 RSS)
- 오늘의 투자 아이디어
# 크론잡으로 매일 아침 실행되는 리포트 (요약)
def morning_report():
watchlist = load_watchlist() # 관심종목
prices = fetch_prices(watchlist) # pykrx → 네이버금융 폴백
news = fetch_news(watchlist) # 구글 뉴스 RSS
send_telegram(f"{시세}\n{뉴스}\n{아이디어}")
이제 아침마다 시장 확인하러 앱 여는 수고가 줄었습니다. 😊
7️⃣ 대시보드 AI 채팅 — 자연어로 조회
대시보드 오른쪽 아래에 AI 어시스턴트 채팅창을 달았습니다. 예를 들면:
- 💬 “삼성전자 공시 알려줘” → DART 공시 자동 조회
- 💬 “내 잔고 알려줘” → 계좌 잔고 조회
- 💬 “지수 상황 알려줘” → 국내/해외 지수 요약
채팅창에서 보낸 메시지가 백엔드를 거쳐 Hermes 에이전트가 자연어를 이해하고 실제 API를 호출하는 구조입니다. 대화 컨텍스트(세션)도 유지돼서 “아까 그 종목 손절선은?” 같은 후속 질문도 가능해요.
AI 채팅으로 “지수 상황 알려줘” → KOSPI +0.73%, MSCI ETF +2.53% 등 요약 응답
AI 어시스턴트 (DeepSeek 모델 연동 화면)
자연어로 “NHN 60,600원 매수” → 주문번호 0111547, return_code 0 (체결 성공)
8️⃣ 자동매매 엔진 — 전략 프리셋 5종 🎯
자동매매의 핵심! 가격 임계값 트리거 기반으로 전략 프리셋 5종을 만들었습니다.
| 프리셋 | 동작 | 방향 |
|---|---|---|
| ⚡️ 초단타 급등 추격 매수 | 현재가 ≥ 기준가 | 매수 |
| 🛡 초단타 급락 손절 | 현재가 ≤ 기준가 | 매도 |
| 🎯 데이트레이딩 익절 | 현재가 ≥ 기준가 | 매도 |
| 📉 단타 지지선 저점 매수 | 현재가 ≤ 기준가 | 매수 |
| 🌊 스윙 추세 돌파 매수 | 현재가 ≥ 기준가 | 매수 |
자동매매 설정 화면 — 전략 프리셋과 조건을 등록하는 페이지
종목과 기준가만 입력하면 1초 만에 규칙이 등록됩니다. 규칙이 발동하면 시장가 주문이 나가고, 실시간 웹소켓 틱을 감시하다가 조건이 맞는 순간 주문을 실행합니다.
# 가격 임계값 트리거 (요약)
if rule.trigger_type == "price_threshold":
price = latest_price(rule.stock_code)
if rule.price_operator == ">=" and price >= rule.price_value:
fire_buy_order(rule) # 조건 충족 → 자동 매수
elif rule.price_operator == "<=" and price <= rule.price_value:
fire_sell_order(rule) # 조건 충족 → 자동 매도
9️⃣ 볼린저 밴드 스크리닝 + 승인형 자동매수 📡
여기서부터는 좀 더 고급 기능입니다.
- 평일 15:00 → 거래량 상위 200종목 스캔
- 볼린저 밴드(20, 2) 하단을 이탈 + 거래량 배율 1.2배 이상 → 후보 선정
- 상위 5종목을 대시보드에 표시 → 내가 직접 매수 승인
- 승인된 종목은 익일 개장 첫 틱에 시장가 자동 매수
- 체결 후 익절 +2% / 손절 -3% 매도 규칙이 자동 생성
삼성전자 일봉 — MA5/20/60 + 볼린저 밴드(20, 2) 오버레이 (BB 상단 290,466 / 하단 206,262)
핵심 철학은 “종목 선택은 사람이, 실행은 기계가” 입니다. AI가 고른 종목을 무조건 사는 게 아니라, 최종 결정권은 저한테 있는 구조로 설계했어요. 🧠
🔟 수익률 / 보호설정 / 공매도 분석
- 💹 수익률 카테고리: 일별/주별/월별/특정기간/누적 수익률을 차트와 표로. 키움의 일별잔고수익률 TR로 과거 잔고 스냅샷까지 조회해 시계열을 구성했습니다.
- 🔒 보호설정: 보유 종목에 “보호”를 걸면 자동매매가 그 종목을 절대 매도하지 못함. 봇의 실수 매도를 원천 차단하면서 수동 매도는 그대로 허용하는 안전장치입니다.
- 📉 공매도현황: 종목별 공매도 추이(수량·금액·매매비중)를 기간으로 조회. 일별 테이블과 요약 카드로 한눈에 파악됩니다.
🛡 리스크 관리 — 이 프로젝트의 자랑 🚨
자동매매에서 가장 중요한 건 “돈을 잃지 않는 장치”라고 생각합니다. 그래서 리스크 가드를 백엔드에 내장했습니다.
| 장치 | 내용 |
|---|---|
| 주문 한도 | 1회 주문 30만원 / 100주 이하 |
| 일일 손실 한도 | 당일 누적 실현손실 20만원 도달 시 전 주문 차단 |
| 쿨다운 | 같은 종목 5초 내 연속 주문 불가 (무한루프 방지) |
| 킬스위치 | 비상 시 원클릭 전체 매매 중지 |
| 안전 기본값 | 서버 시작 시 자동매매 강제 OFF (수동으로 켜야 동작) |
| 속도 제한 | API 요청 초당 4건 제한 |
# 일일 손실 한도 초과 시 차단 (요약)
if state.daily_realized_loss_krw >= settings.daily_loss_limit_krw:
raise RiskViolation(
f"당일 누적 실현손실이 한도에 도달해 신규 주문이 차단되었습니다."
)
이 리스크 가드는 자동매매는 물론, 텔레그램 봇 명령에도 동일하게 적용됩니다. 어떤 경로로 주문이 들어와도 안전장치를 우회할 수 없는 구조예요.
🏗 최종 아키텍처
┌─────────────────────────────────────────────┐
│ 브라우저 대시보드 (React :5173) │
│ 메인/관심목록/자동매매/차트/수익률/공매도 │
└──────────────┬──────────────────────────────┘
│
┌──────────────▼──────────────────────────────┐
│ FastAPI 백엔드 (:8002) │
│ 자동매매 엔진 · 리스크 가드 · 볼린저 │
│ 스크리닝 · 공시/수익률/공매도 서비스 │
└──────┬───────────────────────┬─────────────┘
│ │
┌──────▼─────────┐ ┌─────────▼─────────────┐
│ 키움 OpenAPI+ │ │ 텔레그램 봇 │
│ REST + 웹소켓 │ │ (아침 리포트 · 자연어 │
│ (실시간 시세) │ │ 매매 명령) │
└────────────────┘ └───────────────────────┘
🎉 마무리 — 지금은 어디까지?
이렇게 시작 단계부터 하나씩 쌓아 올려서 지금은:
- ✅ 실시간 시세 기반 자동매매 규칙 실행
- ✅ 볼린저 스크리닝 → 승인 → 자동 익절/손절 원스톱 플로우
- ✅ 텔레그램으로 아침 리포트 + 자연어 매매 명령
- ✅ 대시보드에서 AI 채팅으로 종목/공시/수익률 조회
까지 동작하고 있습니다. 아직 실제 운용은 소액으로 조심스럽게 시작하는 단계고, 앞으로는 백테스팅 기능과 전략별 성과 통계를 추가해볼 생각입니다.
📌 마지막 한 줄: 자동매매의 본질은 “전략”이 아니라 “리스크 관리”라는 걸 이번 개발로 뼈저리게 느꼈습니다. 관심 있으신 분들은 소액으로 꼭 직접 만들어보세요. 공부가 정말 많이 됩니다! 💪