📈 Toss Stock CLI

🕵️ 흑백(스텔스) 테마 를 켜면 색을 빼고 흐릿한 회색조로 그려져, 평범한 로그 출력처럼 보입니다.

설치 방식은 셋 중 편한 걸 고르세요. 처음이라면 A(원클릭) 를 추천합니다.

파이썬만 있으면 더블클릭 한 번으로 끝. (가상환경·패키지 설치를 알아서 처리)

1. 이 저장소를 ZIP 다운로드 후 압축 풀기 (또는 git clone)
2. 폴더 안의 실행 파일을 더블클릭
   • Windows → start.bat
   • macOS / Linux → 터미널에서 chmod +x start.sh && ./start.sh
3. 끝. 실행되면 API Key / Secret Key 입력창이 뜹니다.

파이썬이 없다면? python.org 에서 3.11+ 설치 (Windows는 설치 시 "Add Python to PATH" 체크 필수). 아니면 아래 B(.exe) 를 쓰세요.

파이썬조차 깔기 싫은 Windows 사용자용. Releases 에서 toss-stock.exe 를 받아 더블클릭하면 바로 실행됩니다. (종목 데이터 내장, 별도 설치 없음)

⚠️ 서명되지 않은 파일이라 처음 실행 시 파란 "Windows가 PC를 보호했습니다" 창이 뜰 수 있습니다. → 추가 정보 → 실행 을 누르면 됩니다. (백신이 오탐하면 예외 등록)

pip install -r requirements.txt   # 또는:  pip install httpx textual
python cli.py                      # 실행 즉시 API Key / Secret Key 입력창
python cli.py --mock              # (선택) API 키 없이 가상 데이터로 체험

실행하면 이렇게 진행됩니다:

🪪 API Key(client_id) 입력: tsck_live_...
🔑 Secret Key 입력: ********        ← 화면에 표시되지 않습니다
━━ 화면 설정 ━━
  테마 선택 [1]: 3   (회사용 흑백)
  모드 선택 [2]: 1   (쉬움)
● LIVE 모드 인증 성공

이 도구는 본인 소유의 토스증권 오픈 API 키로 동작합니다. 아래 두 가지를 먼저 준비하세요.

1. API 키 발급 — 토스증권 앱 → 오픈 API 사전 신청 → 승인 후 PC 웹(tossinvest.com)에서 client_id(API Key)와 Secret Key 발급
2. 허용 IP 등록 — API를 호출할 공인 IP를 등록해야 합니다. 보통 접속한 IP가 자동으로 채워지니 그대로 등록하면 됩니다.
   • ⚠️ 등록해야 하는 건 192.168.x.x 같은 로컬 IP가 아니라 공인 IP입니다. (자동값 사용 권장)
   • 인터넷을 바꾸거나(집↔핫스팟) 통신사 IP가 바뀌면 IP도 바뀌므로 재등록이 필요합니다. 현재 내 공인 IP는 whatismyip.com 에서 확인할 수 있어요.

🚨 가장 흔한 실수 — IP 등록 위치 헷갈림! 허용 IP는 반드시 오픈 API 앱(키) 관리 페이지의 "허용 IP" 항목에 등록해야 합니다. 토스 설정의 로그인 유지 설정 화면에 뜨는 기기/IP 목록은 브라우저 로그인 세션일 뿐, API와 전혀 무관합니다. 거기 IP가 맞아도 API는 계속 막힙니다. (developers.tossinvest.com 또는 API 키 발급 페이지 → 앱 상세 → 허용 IP)

💵 실제 돈이 오가는 LIVE 트레이딩 도구입니다. 보안을 최우선으로 설계했습니다.

• API Key · Secret Key 모두 코드에 하드코딩하지 않습니다. 실행 시 입력받으며, 특히 Secret Key 는 getpass 로 화면 비표시 · 메모리에만 보관합니다. (명령 히스토리에도 남지 않음)
• 매번 입력이 번거로우면 환경변수로 주입할 수 있습니다 (이 경우 프롬프트 생략):

  # Windows (PowerShell)
  $env:TOSS_CLIENT_ID="..."; $env:TOSS_CLIENT_SECRET="..."; python cli.py
  # macOS / Linux
  TOSS_CLIENT_ID=... TOSS_CLIENT_SECRET=... python cli.py

• 모든 매수 · 매도 · 정정 · 취소는 전송 전 내용을 보여주고 y/N 확인을 받습니다.
• 주문 시 코드/티커가 실제 어떤 종목인지 API 로 재확인해 보여주어 오주문을 막습니다.
• 국장 종목을 장 시간 외에 주문하면 사전 경고합니다.

1) 계좌/자산   2) 시세   3) 주문   4) 시장정보   9) 설정   0) 종료

• 6자리 숫자 → 국장 코드 / 영문 → 미국 티커 / 한글·영문명 → 자동 변환
• 여러 종목이 검색되면 번호로 선택, 미국 주식 한글 별칭 내장(애플·엔비디아·테슬라 등)
• 목록 갱신: python update_stocks.py (국장 주식·ETF, 미장 자동 다운로드)

• 테마: 1 컬러(기본) · 2 연한색 · 3 흑백(스텔스) — 언제든 9) 설정 에서 변경
• 모드: 1 쉬움(핵심 기능만) · 2 어려움(전체 기능)
• 차트: 시세 → 8) 📈 차트, 봉 단위(일/분) · 개수(최대 120) 선택

1~4 탭 전환 · r 새로고침 · q 종료 — 시세/포트폴리오/주문/주문내역을 시각화

toss-stock/
├── start.bat          # ⭐ Windows 원클릭 실행 (더블클릭)
├── start.sh           # ⭐ macOS/Linux 원클릭 실행
├── build_exe.bat      # 배포자용 — dist/toss-stock.exe 빌드
├── toss-stock.spec    # PyInstaller 빌드 설정
├── requirements.txt   # 의존성 목록 (httpx, textual)
├── cli.py             # cmd 인터랙티브 CLI (메인)
├── app.py             # Textual TUI 대시보드
├── toss_api.py        # 토스증권 API 클라이언트 (실제 20개 엔드포인트 + Mock)
├── stocks.py          # 종목명 → 코드/티커 검색 (국장 + 미장)
├── market_rank.py     # 주식 순위 (네이버 금융)
├── update_stocks.py   # 종목 목록 갱신 스크립트 (3종 자동 다운로드)
├── krx_stocks.json    # 국장 주식 데이터
├── kr_etf.json        # 국장 ETF 데이터
└── us_stocks.json     # 미장 주식/ETF 데이터

배포자용 — .exe 만들기: Windows에서 build_exe.bat 더블클릭 → dist\toss-stock.exe 생성. 이 파일 하나만 Releases에 올리면 사용자는 B 방식으로 바로 실행할 수 있습니다.

• 시세 · 주문: 토스증권 Open API (OpenAPI 3.1.0 / v1.1.5)
• 국장 종목: 한국거래소 KIND 상장법인목록
• 국장 ETF · 순위: 네이버 금융 (ETF 목록 / 종목 순위)
• 미장 종목: NASDAQ Trader Symbol Directory

ℹ️ 시세·주문·계좌는 토스증권 공식 API를 사용합니다. 순위·종목목록 등 토스 API 가 제공하지 않는 보조 데이터만 네이버/거래소 공개 데이터로 보완합니다. (조회 전용, 주문과 무관)

본 프로젝트는 토스증권 비공식 클라이언트입니다. 실제 자산 거래가 발생하며, 사용에 따른 모든 투자 손익과 책임은 사용자 본인에게 있습니다. 코드는 "있는 그대로(AS IS)" 제공되며 어떠한 보증도 하지 않습니다. 투자에 유의하세요.

국내 주식 매매 수수료: 2026년 6월까지 무료 (이후 KRX 0.015%)

MIT © 2026 TaeWoongYoun