Skip to content

About

toss 증권 open Api 활용

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

stockterm

CI

터미널 위장형 증권 시세 데스크톱 앱 (Electron + TypeScript, electron-vite). 토스증권 OpenAPI 연동. 공개 시세 조회 + 본인 계좌 포트폴리오를 명령어와 단축키로만 확인한다. GUI 버튼 없음.

API 레퍼런스: https://developers.tossinvest.com/docs · 로컬 사본: docs/toss/

특징

  • 진짜 터미널처럼 — macOS 네이티브 신호등 · 중앙 정렬 제목 · 깜빡이는 블록 커서 · 오버레이 스크롤바. 따뜻한 macOS Terminal 톤으로 위장이 자연스럽다.
  • 명령어 + 단축키 only — GUI 버튼 0개. 멀티탭 · 중첩 분할(임의 그리드) · 드래그로 분할/탭 순서 변경.
  • 키보드 접근성 — WAI-ARIA 탭(roving tabindex · ←→/Home/End · Delete 닫기) · :focus-visible 링 · 시맨틱 <button>.
  • 디자인 토큰 — 색은 전부 CSS 변수 → dark/light 런타임 전환. 하드코딩 hex 금지.
  • 실 데이터 전용 — 토스 OpenAPI만, mock 없음. 실패는 정직하게 ✗로 표시.

실행

git clone https://github.com/leejpsd/stock-term.git && cd stock-term && npm install && npm start
npm start          # 실행 (빌드 + 프리뷰 — 사용자용, devtools 없음)
npm run dev        # 개발 (electron-vite HMR + devtools 도킹)

배포는 클론>실행 방식만 제공한다(개발자 타깃). unsigned .dmg 는 Gatekeeper 마찰이 커서 접음 — 개인용 패키징은 npm run dist 로 여전히 가능.

데이터는 실제 토스 OpenAPI 전용(mock 없음). 미연결·실패 시 정직하게 ✗ 실패로 표시한다.

자격증명 (BYO-key)

본인 토스 계좌 + OpenAPI 키가 필요하다. 시크릿은 메인 프로세스/로컬에만 저장되고 외부로 안 나간다.

  • 개발: 루트에 .env 작성(.env.example 복사) → TOSS_CLIENT_ID / TOSS_CLIENT_SECRET / TOSS_ACCOUNT. 시작 시 자동 로그인.
  • 배포 사용자: 터미널에 login 입력 → API_KEY= / SECRET_KEY= 인터랙티브 입력(secret 가림) → 로컬 저장 후 자동 토큰 발급. 이후 login은 저장된 키로 자동. 키는 settings에서 마스킹 표시.
  • ⚠️ 토스 포털에서 허용 IP 등록 필요(WTS 설정 → Open API → 허용 IP). 미등록 시 403.

명령어

명령 설명
stock <종목> [-w] 단일 시세 (예: stock 삼성전자). -w로 실시간 폴링
watch <종목...> / unwatch 실시간 와칭 / 해제 (Ctrl+C 중단)
top / top 등락률 시총 상위 / 등락률 상위 (실시간)
login / logout 토스 연동 / 해제
accounts 내 계좌 목록(accountSeq 확인)
portfolio [-w] / pnl 내 보유종목(-w 실시간) / 평가손익
alias 이름 = 명령 나만의 명령어 (예: alias 내주식 = portfolio -w)
tab [이름] 새 탭
split / vsplit / zoom / swap / exit 분할 / 최대화 / 위치교환 / 닫기
settings / theme <dark|light> / pin / clear 설정 / 테마 / 항상위 / 화면 지움
help 명령어 목록

종목은 코드(005930)·티커(AAPL)·종목명(대형주) 모두 인식. 입력 중 회색 고스트 텍스트를 Tab/→로 채택.

단축키

  • ⌘/Ctrl+⇧P — 명령어 팔레트 · ⌘/Ctrl+K — clear (터미널 관례)
  • ⌘/Ctrl+T — 새 탭 · ⌘/Ctrl+1~9 — 탭 전환 · ? — 도움말(help 인라인 출력)
  • 탭(키보드): Tab/Shift+Tab로 탭바 포커스 → ←/→ 이동 · Delete 닫기 · Enter 진입 (드래그로 순서 변경도 가능)
  • ⌘/Ctrl+D 좌우 / ⌘/Ctrl+⇧D 상하 분할 · ⌘/Ctrl+⇧Enter 패널 최대화
  • ⌘/Ctrl+⌥방향키·⌘[·⌘] 패널 포커스 이동 · ⌘⇧[·⌘⇧] 위치 교환
  • ↑/↓ 히스토리 · Ctrl+L clear · Ctrl+C 와칭 중단(입력값도 지움) · Esc 오버레이 닫기
  • ⌘/Ctrl+B — boss-key (위장 화면, 한 손 토글)

테마

dark / light 2종 — macOS Terminal 풍의 따뜻한 중성 팔레트. 색은 전부 CSS 변수(디자인 토큰)로 관리, theme(무인자=토글) 또는 설정에서 런타임 전환. 크롬(타이틀바·탭·상태바)은 sans-serif, 본문만 mono로 진짜 터미널 대비를 살렸다. 시세 색은 한국 관례(상승=빨강, 하락=파랑).

구조

src/
├── shared/
│   └── types.ts      # 메인↔렌더러 공유 도메인 모델 + IPC 계약(StocktermBridge)
├── main/
│   ├── index.ts      # 프레임리스 윈도우, IPC
│   └── toss.ts       # 토스 OpenAPI 클라이언트 (시크릿은 여기만)
├── preload/
│   └── index.ts      # contextBridge 안전 브릿지 (nodeIntegration off)
└── renderer/
    ├── index.html    # 터미널 UI 마크업 (GUI 버튼 없음, 상태바 힌트만)
    └── src/          # 변경 경계로 분리된 기능 모듈
        ├── app.ts        # 엔트리: boot + 사이드이펙트 모듈 와이어링 (thin)
        ├── panes.ts      # 멀티탭·분할 트리·드래그(분할/탭 reorder)·키보드 탭 내비(WAI-ARIA)
        ├── input.ts      # 패널 입력: 자동완성 고스트·구문강조·블록 커서
        ├── commands.ts   # CMDS + 명령어 구현 + exec 디스패치
        ├── overlays.ts · keys.ts · statusbar.ts · theme.ts · persist.ts · boss.ts
        ├── data.ts · poller.ts · output.ts · format.ts · state.ts · bridge.ts
        ├── styles.scss   # 디자인 토큰(CSS 변수)·스타일 (Vite 가 번들·주입)
        └── core/
            ├── parser.ts    # 순수 로직(resolve/fmtQuote/tokenize/rankTop/sparkline/matchSymbols)
            └── universe.ts  # 탑N 후보 풀(대형주 코드 시드)
docs/toss/            # 토스 OpenAPI 로컬 사본(openapi.json 정본)
tests/                # Vitest (parser·정규화 + 렌더러 부팅 스모크)

타입 안전: 메인↔렌더러는 src/shared/types.ts 의 StocktermBridge 계약에만 의존한다(렌더러는 구현체를 모름 · DIP). 조회 IPC 결과는 ApiResult<T> = {ok,data} | {ok:false,error} 로 통일.

개발

npm run dev           # electron-vite dev (HMR)
npm run build         # out/ 번들 (main/preload/renderer)
npm run dist          # build + electron-builder 패키징 → dist/*.dmg (unsigned, arm64)
npm run typecheck     # tsc --noEmit (strict)
npm test              # Vitest
npm run lint          # ESLint (typescript-eslint) · npm run format (Prettier)

기여·컨벤션(주석 규칙 포함): CONTRIBUTING.md

데이터 연동 메모: 토스 OpenAPI엔 순위/시총상위·KOSPI 지수 엔드포인트가 없어 top은 후보 풀(universe.ts) 위에서 직접 계산한다. 모든 watch/top/stock 구독은 중앙 폴러가 심볼을 합쳐 dedup → 주기당 batch 1회만 호출한다.

주의

  • 토스 약관: 시세는 본인 매매 목적만. 제3자 제공·재배포·상업적 활용 금지 → BYO-key 구조 유지.
  • 시크릿 키는 메인 프로세스/로컬에만. 외부 서버 전송 금지. .env는 gitignore.
  • 주문 기능 미포함(조회 전용) — 오발주 리스크 회피.
  • 개인 도구 목적. 투자 책임은 사용자 본인.

About

toss 증권 open Api 활용

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages