diff --git a/README.md b/README.md index dc7b34f..4190662 100644 --- a/README.md +++ b/README.md @@ -2,98 +2,78 @@ # 눈금 -**국내 주식·ETF 자동매매 프로그램** +**국내 주식·ETF 자동매매** -한국투자증권 KIS API를 지원하는 Python 프로그램입니다. 설정한 종목과 비중에 따라 자동으로 매매하고, 웹 화면에서 투자금과 수익률을 확인합니다. 기본 설정은 모의투자입니다. +정해 둔 종목과 비중에 맞춰 주식과 ETF를 사고파는 프로그램입니다. 계좌 화면에서 투자금, 수익률, 보유 종목을 볼 수 있습니다. -[설치 방법](#설치-및-실행) · [백테스트 결과](docs/RISK_REVIEW_20260922.md) · [문의](https://github.com/easygap/quant_trader/issues/new/choose) +내 PC에 설치해서 사용하며, 모의투자로 시작합니다. -![계좌에서 날짜별 수익률을 확인하고 차트 모양을 바꾸는 모습](docs/images/readme-walkthrough-20260922.gif) +[설치하기](docs/GETTING_STARTED.md) · [사용법](docs/USER_GUIDE.md) · [백테스트](#백테스트) · [문의](https://github.com/easygap/quant_trader/issues/new/choose) -2026년 9월 22일에 촬영한 모의투자 화면입니다. [이미지로 보기](docs/images/readme-account-20260922.png) +## 수익률 -## 주요 기능 +![날짜별 투자금과 수익률, 입체·평면 차트](docs/images/readme-walkthrough-20260922.gif) -- **계좌 조회**: 투자원금, 평가금액, 수익률을 날짜별로 확인하고 CSV로 저장합니다. -- **자동매매**: 정해 둔 종목과 비중에 맞춰 매수·매도합니다. 주문 전에 잔고와 거래 한도를 확인합니다. -- **모의투자**: 가상 자금으로 매매해 보고, 주문 내역과 수익률을 확인합니다. -- **백테스트**: 과거 주가로 매매 규칙을 시험하고 수익률, 손실, 거래 비용을 비교합니다. +모의투자 화면 · 2026.09.22 · [정지 화면](docs/images/readme-account-20260922.png) -계좌에 돈을 추가로 넣어도 수익률이 부풀려지지 않도록 계산합니다. 차트 아래에서 날짜를 고르면 그날의 투자금과 수익률이 함께 바뀝니다. +날짜를 고르면 그날의 금액과 수익률이 나옵니다. 추가로 넣은 돈은 원금으로 따로 계산합니다. 차트 아래 **기록 내려받기**를 누르면 날짜별 내역을 CSV 파일로 저장할 수 있습니다. -## 설치 및 실행 - -**Python 3.11 또는 3.12와 Git**이 필요합니다. 아래는 Windows PowerShell 기준입니다. - -```powershell -git clone https://github.com/easygap/quant_trader.git -cd quant_trader -python -m venv .venv -.\.venv\Scripts\python.exe -m pip install -r requirements.txt +## 보유 종목 -if (-not (Test-Path config/settings.yaml)) { - Copy-Item config/settings.yaml.example config/settings.yaml -} -if (-not (Test-Path .env)) { - Copy-Item .env.example .env -} +![대형주 계좌의 보유 수량, 평균 매수가, 종목별 비중](docs/images/readme-holdings-20260922.png) -.\.venv\Scripts\python.exe main.py --mode dashboard -``` +종목별 보유 수량과 평균 매수가, 투자 비중을 보여 줍니다. 지금 비중이 처음 정한 목표와 얼마나 다른지도 바로 비교할 수 있습니다. -브라우저에서 **[127.0.0.1:8080](http://127.0.0.1:8080)**을 열면 됩니다. 이 명령은 계좌 화면만 엽니다. 자동매매는 별도로 실행해야 합니다. +비중은 매수한 금액으로 계산합니다. 현재 가격을 반영한 평가금액과 손익은 표 아래에 있습니다. -처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. [설정과 모의투자 실행 방법](docs/GETTING_STARTED.md)을 따라 시작하세요. +## 자동매매 -## 보유 종목 +**ETF 적립**과 **대형주 분산 투자**, 두 가지 기본 설정이 들어 있습니다. 종목과 투자 비중은 직접 바꿀 수 있습니다. ETF 적립 설정은 현재 모의투자 전용입니다. -몇 주를 샀는지, 평균 매수가는 얼마인지, 목표 비중과 얼마나 차이가 나는지 확인할 수 있습니다. +주문 전에는 잔고와 거래 한도를 확인합니다. 마지막 실행 시각과 거래 중지 사유는 **자동매매 상태**에 표시합니다. -![대형주 계좌의 보유 수량, 평균 매수가, 종목별 비중](docs/images/readme-holdings-20260922.png) +![마지막 실행 시각, 거래 중지 여부, 증권사 연결 상태](docs/images/readme-operations-20260922.png) -종목별 비중은 **매수한 금액 기준**입니다. 현재 가격으로 계산한 보유 주식의 금액과 손익은 표 아래에 따로 나옵니다. +[기본 매매 설정과 사용법](docs/USER_GUIDE.md#매매-설정)
-자동매매 상태와 모바일 화면 보기 +모바일 화면 -### 자동매매 상태 +휴대폰 크기의 계좌 화면 -마지막 실행 시각과 거래 중지 여부, 증권사 연결 상태를 확인할 수 있습니다. 문제가 있으면 안내를 눌러 해당 화면으로 이동합니다. +작은 화면에서는 계좌 금액과 차트를 위아래로 배치합니다. 날짜는 터치로 바꿀 수 있습니다. 휴대폰 접속에는 [별도의 연결 설정](docs/USER_GUIDE.md#모바일-접속)이 필요합니다. -![자동매매의 마지막 실행 시각과 연결 상태](docs/images/readme-operations-20260922.png) - -### 모바일 화면 +
-휴대폰 화면에 맞춰 수익률, 계좌 금액, 차트 순서로 표시합니다. 차트의 날짜는 터치로 바꿀 수 있습니다. 휴대폰에서 접속하려면 PC의 기본 접속 설정을 바꿔야 합니다. +## 백테스트 -모바일 화면의 ETF 적립 계좌와 수익률 차트 +과거 주가로 매매 조건을 시험해 볼 수 있습니다. 거래 비용을 반영한 수익률과 크게 하락했던 구간을 함께 비교합니다. -[모바일 전체 화면 보기](docs/images/dashboard-mobile-20260922.png) +[백테스트 결과와 계산 조건](docs/RISK_REVIEW_20260922.md) - +모의투자와 백테스트에서 수익이 났더라도 실제 투자에서는 손실이 날 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다. -## 기본 매매 설정 +## 시작하기 -- **ETF 적립**: KODEX 200과 TIGER CD금리 ETF에 나눠 투자합니다. 시작 금액은 30만원, 월 적립 계획은 10만원입니다. -- **대형주 분산 투자**: 국내 대형주에 나눠 투자합니다. 주식 60%·현금 40%를 목표로 하며, 비중 차이가 커지면 조정합니다. +**Python 3.11 또는 3.12와 Git**이 필요합니다. 설치 안내는 Windows PowerShell 기준입니다. -종목과 비중은 [config/baskets.yaml](config/baskets.yaml)에서 바꿀 수 있습니다. ETF 적립은 현재 모의투자 전용입니다. 추가 투자금은 화면에 직접 기록하며, 자동이체 기능은 없습니다. +1. [설치 안내](docs/GETTING_STARTED.md)에 따라 프로그램을 설치합니다. +2. [모의투자](docs/GETTING_STARTED.md#모의투자)를 실행합니다. +3. 설치한 PC에서 [계좌 화면](http://127.0.0.1:8080)을 엽니다. 날짜 선택과 파일 저장은 [사용법](docs/USER_GUIDE.md)에 설명했습니다. -백테스트 결과에는 수익률뿐 아니라 **가장 많이 하락한 폭과 거래 비용**도 함께 정리했습니다. [비교 조건과 결과 보기](docs/RISK_REVIEW_20260922.md) +처음 실행하면 거래 기록이 없는 계좌가 열립니다. 자동매매는 계좌 화면과 별도로 실행하며, PC와 자동매매 프로그램을 켜 두어야 합니다. -모의투자와 백테스트 결과가 좋아도 실제 투자에서는 손실이 날 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다. 실제 계좌를 연결하기 전에는 [주문 설정과 확인 사항](docs/PAPER_TO_LIVE_RUNBOOK.md)을 읽어 주세요. +실제 계좌 연결은 한국투자증권 KIS API를 사용합니다. 연결 방법과 주문 설정은 [실제 계좌 사용 안내](docs/PAPER_TO_LIVE_RUNBOOK.md)에 있습니다. -## 사용 안내 +## 문의 -- [설치와 첫 모의투자](docs/GETTING_STARTED.md) -- [자동 실행과 설정 파일 설명](docs/PROJECT_GUIDE.md) -- [실제 계좌 연결](docs/PAPER_TO_LIVE_RUNBOOK.md) -- [거래가 중지됐을 때 확인할 것](docs/SAFETY_MODEL.md) +오류가 나거나 필요한 기능이 있으면 [오류 제보·기능 제안](https://github.com/easygap/quant_trader/issues/new/choose)에 남겨 주세요. 화면이나 오류 메시지를 올릴 때는 계좌번호와 API 키를 지워 주세요. -Python · aiohttp · SQLite를 사용합니다. 웹 화면은 HTML/CSS/JavaScript로 만들었으며, 프런트엔드는 따로 설치하거나 빌드할 필요가 없습니다. +도움이 됐다면 **Star**를 눌러 주세요. -## 문의와 의견 +
+개발 문서 -잘 안 되는 기능이나 필요한 기능이 있으면 [GitHub Issues](https://github.com/easygap/quant_trader/issues/new/choose)에 남겨 주세요. 오류 화면이나 메시지를 함께 올려 주시면 원인을 찾는 데 도움이 됩니다. 계좌번호와 API 키는 지우고 올려 주세요. +Python · aiohttp · SQLite · HTML/CSS/JavaScript를 사용합니다. 코드 구조와 자동 실행 설정은 [개발 문서](docs/PROJECT_GUIDE.md)에 정리했습니다. -유용하게 쓰셨다면 오른쪽 위 **Star**를 눌러 주세요. +
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 4e7d848..560713c 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -38,6 +38,8 @@ if (-not (Test-Path .env)) { 처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. README의 캡처는 기존 모의투자 계좌의 기록입니다. 설치 직후에는 캡처에 나온 금액과 수익률이 표시되지 않습니다. +계좌 선택, 날짜별 수익률, 적립금 입력은 [계좌 화면 사용법](USER_GUIDE.md)에 설명했습니다. + 기본 접속 주소는 이 PC에서만 열립니다. 포트를 바꾸려면 다음처럼 실행합니다. ```powershell @@ -46,6 +48,8 @@ if (-not (Test-Path .env)) { ## 모의투자 +계좌 화면을 켜 둔 채 진행하려면 PowerShell 창을 새로 열고, 설치한 `quant_trader` 폴더로 이동하세요. + 매매할 종목과 비중은 [config/baskets.yaml](../config/baskets.yaml)에서 정합니다. `kr_pocket`은 ETF 적립 계좌, `kr_diversified_hold`는 대형주 분산 계좌입니다. 먼저 어떤 주문을 낼지 확인합니다. 주가를 불러오므로 인터넷 연결이 필요합니다. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..2eae33b --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,76 @@ +# 계좌 화면 사용법 + +[설치 안내](GETTING_STARTED.md) · [README](../README.md) + +## 계좌 선택 + +화면 위쪽에서 **ETF 적립** 또는 **대형주 분산 투자**를 누릅니다. 선택한 계좌에 맞춰 금액, 수익률 차트, 보유 종목이 바뀝니다. + +처음 설치했다면 아직 거래 기록이 없습니다. [모의투자 실행 방법](GETTING_STARTED.md#모의투자)에 따라 한 번 실행한 뒤 화면을 새로고침하세요. 주문 조건에 맞지 않으면 거래가 없을 수도 있습니다. + +## 수익률 + +차트 아래의 날짜 막대를 움직이면 그날의 금액과 수익률이 나옵니다. **최근 날짜**를 누르면 마지막 기록으로 돌아갑니다. + +- **투자원금**: 처음 넣은 돈과 나중에 추가한 돈입니다. +- **평가금액**: 보유 주식·ETF의 금액과 현금을 합한 금액입니다. +- **수익률**: 돈을 넣고 뺀 영향을 제외한 투자 수익률입니다. + +입금은 수익으로 계산하지 않습니다. 수익률 계산 방식은 흔히 쓰는 이름으로 **시간가중수익률(TWR)**이라고 합니다. + +**입체**와 **평면**은 같은 수익률을 다른 모양으로 보여 줍니다. 입체 차트의 띠 너비가 별도의 투자 지표를 뜻하지는 않습니다. + +[계좌 화면 크게 보기](images/readme-account-20260922.png) + +## 내역 저장 + +차트 아래 **기록 내려받기**를 누르면 CSV 파일이 저장됩니다. 선택한 계좌와 기간에 해당하는 날짜, 평가금액, 투자원금, 수익률, 고점 대비 하락률이 들어 있습니다. 엑셀에서도 열 수 있습니다. + +## 보유 종목 + +종목마다 보유 수량, 평균 매수가, 매수한 금액, 비중이 나옵니다. 지금 비중과 목표 비중을 나란히 비교할 수 있습니다. + +이 표의 비중은 **매수한 금액 기준**입니다. 현재 가격으로 계산한 보유 주식의 금액과 손익은 표 아래에 따로 표시합니다. + +[보유 종목 화면 크게 보기](images/readme-holdings-20260922.png) + +## 적립금 기록 + +모의투자에 쓸 가상 자금을 추가하는 기능입니다. + +1. 화면 위쪽의 **적립금 기록**을 누릅니다. +2. 계좌를 고르고 금액을 입력합니다. 필요하면 메모도 남깁니다. +3. **내용 확인**을 누른 뒤 계좌, 금액, 모의투자 여부를 다시 확인하고 기록합니다. + +은행에서 돈을 가져오거나 자동이체를 등록하는 기능은 아닙니다. 추가한 금액은 모의투자 원금에 더해집니다. + +## 매매 설정 + +기본으로 사용하는 설정은 두 가지입니다. + +- **ETF 적립**: KODEX 200과 TIGER CD금리 ETF에 나눠 투자합니다. 시작 금액은 30만원, 월 적립 계획은 10만원입니다. 추가 투자금은 직접 기록합니다. +- **대형주 분산 투자**: 국내 대형주에 나눠 투자합니다. 주식 60%·현금 40%를 목표로 하며, 비중 차이가 커지면 조정합니다. + +종목과 비중은 [config/baskets.yaml](../config/baskets.yaml)에서 바꿉니다. 설정 파일의 `kr_pocket`은 ETF 적립, `kr_diversified_hold`는 대형주 분산 투자입니다. + +ETF 적립 설정은 현재 모의투자 전용입니다. 1주 가격과 최소 주문금액 때문에 실제 매수 비중이 목표와 다를 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다. + +## 자동매매 상태 + +**자동매매 상태**에는 마지막 실행 시각, 거래 중지 여부, 증권사 연결과 데이터 갱신 상태가 나옵니다. 오류가 표시되면 **다시 확인**을 눌러 상태를 새로 불러옵니다. + +자동매매는 계좌 화면과 별도로 실행합니다. 계속 매매하려면 PC와 자동매매 프로그램을 켜 두어야 합니다. 화면만 열어 놓아서는 매매가 시작되지 않습니다. + +- [자동 실행 설정](PROJECT_GUIDE.md) +- [거래가 중지됐을 때 확인할 것](SAFETY_MODEL.md) +- [실제 계좌 연결과 주문 설정](PAPER_TO_LIVE_RUNBOOK.md) + +## 모바일 접속 + +화면은 휴대폰 크기에 맞춰 바뀝니다. 차트의 날짜도 터치로 고를 수 있습니다. + +기본 주소 `127.0.0.1`은 프로그램을 실행한 PC에서만 열립니다. 휴대폰에서 접속하려면 접속 주소와 인증을 별도로 설정해야 합니다. [연결 설정](PROJECT_GUIDE.md)을 참고하세요. + +## 문의 + +[오류 제보·기능 제안](https://github.com/easygap/quant_trader/issues/new/choose)에 문제가 생긴 상황과 화면을 남겨 주세요. 계좌번호, API 키, 비밀번호는 지우고 올려 주세요.