tossinvest-web 📊

로컬에서 실행하는 TossInvest 전략 대시보드입니다. 계좌 보유 종목, 전략 상태, 사이클 진행 상황, 거래 이력을 하나의 브라우저 화면에서 확인합니다.

tossinvest-web은 단독 제품이 아닙니다. Toss Open API 연동과 전략 실행 기반은 tossinvest-strategy 가 담당하며, 이 패키지는 그 결과를 읽고 관리하기 위한 웹 인터페이스를 제공합니다.

🧩 패키지 관계

Toss Open API
    |
tossinvest-strategy (필수)
    |- 인증, 토큰 갱신, 계좌/시세 API
    |- 전략 실행, strategy_state/ 및 trade_history/ 관리
    |
tossinvest-web
    |- 계좌/보유 종목 대시보드
    |- 전략 및 Cycle 현황 시각화
    |- 거래 이력 조회, VR 수동 기록 입력

tossinvest-web을 설치하면 tossinvest-strategy>=0.2.1도 자동으로 설치됩니다. 웹 대시보드는 전략을 대신 실행하지 않습니다. 전략 실행으로 생성된 로컬 상태와 거래 이력을 보여 주며, 계좌 조회는 tossinvest-strategy의 Toss Open API 클라이언트를 통해 이뤄집니다.

🖼️ 스크린샷

포트폴리오

전략 현황

위 화면의 금액, 수익, 종목, 수량은 공개용으로 블라인드 처리한 예시입니다. 실제 실행 시에는 사용자의 로컬 계좌 및 전략 데이터가 표시됩니다.

📦 설치

pip install tossinvest-web

위 명령은 필수 기반 패키지인 tossinvest-strategy를 함께 설치합니다. 전략 SDK를 먼저 명시적으로 설치하려면 다음과 같이 실행할 수 있습니다.

pip install "tossinvest-strategy>=0.2.1" tossinvest-web

이 저장소에서 개발 설치할 때는 SDK와 웹 패키지를 모두 editable 모드로 설치합니다.

pip install -e .
pip install -e packages/tossinvest-web

🚀 빠른 시작

1. 🔐 Toss Open API 인증 파일 준비

로컬 데이터 디렉터리를 만들고 Toss Open API 자격 증명을 credentials 파일에 저장합니다. tossinvest-strategy는 첫 인증 요청 후 token.json을 생성하고 갱신합니다.

my-tossinvest/
  credentials
  token.json                 # 로컬 생성 파일, 커밋 금지
  strategy_state/            # 전략 실행 시 생성되는 상태 파일
  trade_history/             # 전략 체결 이력 또는 수동 기록

credentials 형식은 다음과 같습니다.

client_id: your_client_id
client_secret: your_client_secret
account_number: your_account_number

2. ⚙️ 전략 실행 또는 기존 상태 준비

tossinvest-strategy로 전략을 실행하면 strategy_state/와 trade_history/에 대시보드가 읽을 수 있는 로컬 데이터가 만들어집니다. 전략을 아직 실행하지 않아도 계좌와 보유 종목은 조회할 수 있으며, 전략 섹션에는 상태 파일이 없다는 안내가 표시됩니다.

전략 구성과 실행 방법은 tossinvest-strategy 프로젝트를 참고하세요.

3. 🌐 웹 대시보드 실행

로컬 데이터 디렉터리에서 다음 명령을 실행합니다.

tossinvest-web --host 127.0.0.1 --port 8000

브라우저에서 http://127.0.0.1:8000을 엽니다.

개발 중 Python 또는 정적 파일 변경 시 자동 재시작하려면 --reload를 사용합니다.

tossinvest-web --host 127.0.0.1 --port 8000 --reload

🧭 주요 화면

• Portfolio: Toss Open API를 통해 계좌 요약과 보유 종목을 조회합니다. 환율 환산은 기본적으로 꺼져 있으며 대시보드에서 선택할 수 있습니다.
• Strategy Overview: 로컬 전략 상태를 전략 단위와 실행 항목 단위로 나눠 실현 손익, 보유 원가, 수량, 회수액과 운영 상태를 표시합니다.
• Cycle Map: Cycle 기반 전략의 매수 진행, 매도 대기, 완료 상태를 한눈에 확인합니다.
• Value Rebalancing: 다른 증권사에서 수동으로 운영하는 VR 전략의 체결, 목돈 추가, 다음 Cycle 예약과 주문 가이드를 기록합니다.
• Daily Trade Log: 로컬 거래 이력을 날짜 범위로 필터링해 확인합니다.

자동 새로고침 주기, 선택한 탭, 정렬 기준, 필터는 브라우저에 저장되어 다음 실행 시에도 복원됩니다.

📱 다른 기기에서 보기

같은 Wi-Fi 또는 사설 네트워크의 다른 기기에서 보려면 모든 로컬 네트워크 인터페이스에 바인딩합니다.

tossinvest-web --host 0.0.0.0 --port 8000

다른 기기에서 http://<내-컴퓨터-IP>:8000을 엽니다. 방화벽은 신뢰하는 사설 네트워크에만 허용하고, 이 서버를 공용 인터넷에 직접 노출하지 마세요.

📁 데이터 디렉터리와 환경 변수

기본값은 명령을 실행한 현재 디렉터리입니다. SDK 파일을 다른 위치에 둘 경우 다음 환경 변수를 사용할 수 있습니다.

TOSSINVEST_DATA_DIR=C:\\path\\to\\my-tossinvest
TOSSINVEST_CREDENTIAL_FILE=C:\\path\\to\\credentials
TOSSINVEST_TOKEN_FILE=C:\\path\\to\\token.json

TOSSINVEST_DATA_DIR 하나만 설정해도 그 아래의 credentials, token.json, strategy_state/, trade_history/를 함께 찾습니다.

🔒 보안 유의사항

• credentials, token.json, strategy_state/, trade_history/는 공개 저장소와 공유 폴더에 넣지 마세요.
• 웹 패키지는 로컬 대시보드이며 인증 정보나 이력을 외부 서비스로 전송하지 않습니다.
• 실제 주문과 전략 실행은 tossinvest-strategy 및 사용자의 전략 실행 환경에서 관리됩니다. 실계좌 사용 전에는 충분한 검증이 필요합니다.