tossinvest-cli

AI 에이전트를 토스증권에 연결하는 비공식 CLI.

Claude Code · Codex · Cursor · OpenClaw · bash · HTTP — 어떤 도구든 동일한 명령 표면(tossctl)으로 토스증권 계좌·시세·거래를 다룰 수 있습니다. 사람이 직접 터미널에서 쓸 수도 있습니다.

Quick Start · 지원 범위 · 명령 표면 · FAQ · 문서

> [!WARNING] > 이 프로젝트는 토스증권 공식 제품이 아닙니다. 웹 내부 API를 비공식적으로 사용하며, 토스증권 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계좌 제한, 손실, 기타 불이익에 대해 개발자는 어떠한 책임도 지지 않습니다. 본인의 판단과 책임 하에 사용하세요. > [!IMPORTANT] > 거래 기능은 설치 직후 모두 꺼져 있습니다. `config.json`에서 기능별로 직접 허용해야만 실행됩니다.

tossctl overview

Works with

_OpenClaw

_{Claude Code}

_Codex

_Cursor

_Bash

_HTTP

## Quick Start ### For Agent ```text Install tossinvest-cli: curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh (macOS/Linux) or GitHub Releases (Windows). Run `tossctl doctor` to verify setup, then complete browser login with `tossctl auth login`. Use read-only commands first (account, portfolio, quote). Trading actions stay disabled until config.json explicitly allows them. Always run `tossctl order preview` before any trading mutation. ``` ### For Human ```bash # macOS / Linux curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh # 설치 확인 tossctl version tossctl doctor tossctl auth login tossctl account summary --output json ``` > `auth login`에는 Google Chrome과 Python이 필요하며, 설치 스크립트가 자동으로 설정합니다. > Windows, Homebrew, 소스 빌드 등 다른 설치 방법은 [설치](#설치) 섹션을 참고하세요. > > QR 스캔 후 폰에 뜨는 **"이 기기 로그인 유지"** 확인 프롬프트까지 꼭 눌러주세요. > 이 2차 확인을 건너뛰면 세션이 약 1시간 idle 후 만료되어 재로그인이 필요해집니다. > 정상 캡처 여부는 `tossctl auth status` 의 `Persistence: persistent cookie (expires ...)` 로 확인할 수 있습니다. > **GUI 없는 환경 (SSH 서버·CI):** `tossctl auth login --headless [--qr-output /tmp/toss-qr.png]`. > QR URL 과 확인 문자(answerLetter)가 stderr 로 출력되며, URL 을 폰으로 전달해 탭하면 카메라 없이 Toss 앱에서 인증할 수 있습니다. `--qr-output` 파일은 `0600` 권한으로 저장됩니다. ## 지원 범위 ### 조회 (읽기 전용) | 기능 | 커맨드 | US | KR | |------|--------|:--:|:--:| | 계좌 목록 / 요약 | `account list`, `account summary` | O | O | | 포트폴리오 | `portfolio positions`, `portfolio allocation` (US: USD 병기) | O | O | | 시세 | `quote get `, `quote batch [sym...]` | O | O | | 미체결 주문 | `orders list` | O | O | | 체결 내역 | `orders completed --market us\|kr\|all` | O | O | | 단건 주문 조회 | `order show ` | O | O | | 관심 종목 | `watchlist list` | O | O | | 거래내역 ledger | `transactions list --market us\|kr` (매매·입출금·배당·입출고) | O | O | | 현금 overview | `transactions overview --market us\|kr` (주문가능·출금가능·예정입금) | O | O | | CSV 내보내기 | `export positions --market`, `export orders --market`, `transactions list --output csv` | O | O | | 실시간 푸시 | `push listen` (SSE, JSONL 스트림 — 주문/가격 변경 알림) | O | O | ### 거래 | 기능 | 커맨드 | 필요 config | |------|--------|-------------| | 지정가 매수 (US/KR) | `order place --side buy --price ` | `place` | | 지정가 매도 (US/KR) | `order place --side sell --price ` | `place` + `sell` | | 국내주식 거래 | `order place --market kr` | `place` + `kr` | | 소수점 매수 (US) | `order place --fractional --amount ` | `place` + `fractional` | | 주문 취소 | `order cancel --order-id ` | `cancel` | | 주문 정정 | `order amend --order-id ` | `amend` | | 거래 권한 관리 | `order permissions grant\|status\|revoke` | `place`/`cancel`/`amend` 중 하나 | 모든 거래는 `allow_live_order_actions=true`도 필요합니다. 소수점 주문은 시장가(market order)로 자동 전환되며, 금액(KRW) 기반입니다. US 지정가는 `--currency-mode`로 가격 해석을 선택합니다: `KRW` (기본, 서버 환율로 USD 변환) 또는 `USD` (입력을 USD 가격 그대로 전송). 예: `order place --symbol MRVL --side buy --qty 1 --price 158.01 --currency-mode USD`. ### Safety Model ``` config.json 허용 → permissions grant (TTL) → preview → --execute → --dangerously-skip-permissions → --confirm ``` 6단계 게이트. 거래 기능은 기본 전부 꺼져 있고, 하나씩 열어야 실행 가능. ## Config ```bash tossctl config init tossctl config show ``` ```json { "$schema": "https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/schemas/config.schema.json", "schema_version": 2, "trading": { "place": false, "sell": false, "kr": false, "fractional": false, "cancel": false, "amend": false, "allow_live_order_actions": false, "dangerous_automation": { "accept_fx_consent": false } } } ``` | 필드 | 설명 | |------|------| | `place` | `order place` 경로 허용 (broker API 분기: place) | | `cancel` | `order cancel` 경로 허용 (broker API 분기: cancel) | | `amend` | `order amend` 경로 허용 (broker API 분기: amend) | | `sell` | 매도 주문 허용 (`place`도 필요) — **scope 선언**: 유저가 스스로 "매수만/매도 포함" 범위 제한 | | `kr` | 국내주식 거래 허용 (`place`도 필요) — **scope 선언**: "US only" 자가 제한 | | `fractional` | 소수점 주문 허용 (`place`도 필요, US 시장가만) — **scope 선언** | | `allow_live_order_actions` | 마스터 킬스위치 — 위 `place/cancel/amend` 중 하나라도 실제 broker에 도달하려면 이 값도 `true`여야 함 | | `accept_fx_consent` | post-prepare FX confirmation 자동 진행 | > **두 가지 유형의 토글:** > - **경로 게이트** (`place`, `cancel`, `amend`) — broker API 분기가 실제로 다른 세 동작을 각각 독립적으로 켬/끔 > - **스코프 선언** (`sell`, `kr`, `fractional`) — 유저가 스스로 "난 이 범주의 주문은 안 낸다"고 선언하여 실수/버그/agent 오작동 방지 > > `v0.4.3`에서 `trading.grant`, `dangerous_automation.complete_trade_auth`, `dangerous_automation.accept_product_ack`는 제거되었습니다. 남아있는 구 설정은 자동 무시되며 `doctor`에서 경고로 표시됩니다. ## 주문 예시 ### 지정가 매수 (US) ```bash tossctl config init # config.json: place, allow_live_order_actions → true tossctl order preview \ --symbol TSLL --side buy --qty 1 --price 18000 --output json tossctl order permissions grant --ttl 300 tossctl order place \ --symbol TSLL --side buy --qty 1 --price 18000 \ --execute --dangerously-skip-permissions --confirm \ --output json ``` ### 소수점 매수 (US, 금액 기반) ```bash # config.json: place, fractional, allow_live_order_actions → true tossctl order preview \ --symbol TSLL --side buy --fractional --amount 1000 --qty 0 --output json tossctl order place \ --symbol TSLL --side buy --fractional --amount 1000 --qty 0 \ --execute --dangerously-skip-permissions --confirm \ --output json ``` ### 국내주식 매수 ```bash # config.json: place, kr, allow_live_order_actions → true tossctl order place \ --symbol 005930 --market kr --side buy --qty 1 --price 200000 \ --execute --dangerously-skip-permissions --confirm ``` ### 매도 ```bash # config.json: sell → true (추가) tossctl order place \ --symbol TSLL --side sell --qty 1 --price 18000 \ --execute --dangerously-skip-permissions --confirm ``` ### 다종목 시세 ```bash tossctl quote batch TSLL 005930 GOOG VOO --output table ``` ## 이 프로젝트가 하지 않는 것 | 하지 않는 것 | 설명 | |---|---| | 공식 API SDK 제공 | 토스증권 공식 API나 공식 지원 SDK를 제공하는 프로젝트가 아닙니다. | | 범용 트레이딩 클라이언트 | 모든 주문 유형과 시장을 완전히 지원하지 않습니다. | | 무제한 자동 매매 | 안전장치 없이 바로 실행되는 자동 매매 도구를 목표로 하지 않습니다. | ## 설치

Homebrew, Windows, 소스 빌드 등 다른 설치 방법

#### Homebrew (macOS) ```bash brew tap JungHoonGhae/tossinvest-cli brew install tossctl ``` #### Windows (PowerShell) ```powershell Invoke-WebRequest -Uri https://github.com/JungHoonGhae/tossinvest-cli/releases/latest/download/tossctl-windows-amd64.zip -OutFile tossctl.zip Expand-Archive tossctl.zip -DestinationPath . ``` #### From source ```bash git clone https://github.com/JungHoonGhae/tossinvest-cli.git cd tossinvest-cli make build cd auth-helper python3 -m pip install -e . ```

## 명령 표면 ### 조회 ```bash tossctl account list tossctl account summary tossctl portfolio positions tossctl portfolio allocation tossctl orders list tossctl orders completed --market us|kr|all tossctl order show tossctl quote get tossctl quote batch [symbol...] tossctl watchlist list tossctl export positions --market us|kr|all tossctl export orders --market us|kr|all ``` ### 거래 ```bash tossctl order preview --symbol --side --qty --price tossctl order preview --symbol --side buy --fractional --amount --qty 0 tossctl order place ...flags... --execute --dangerously-skip-permissions --confirm tossctl order cancel --order-id --symbol ... tossctl order amend --order-id ... tossctl order permissions grant --ttl 300 tossctl order permissions status tossctl order permissions revoke ``` ### 실시간 푸시 ```bash tossctl push listen # SSE 구독, JSONL stdout (Ctrl+C 종료) tossctl push listen --retry=false # 재연결 비활성 ``` 토스 웹의 SSE 채널을 그대로 구독해 `pending-order-refresh` · `purchase-price-refresh` · `share-holdings` · `web-push` 이벤트를 JSONL로 흘립니다. 이벤트 분류와 후속 재조회 매핑은 [`docs/reverse-engineering/push-events.md`](docs/reverse-engineering/push-events.md). ### 시스템 ```bash tossctl version tossctl doctor tossctl doctor --report # JSON 진단 번들 (이슈 첨부용, 경로 자동 redact) tossctl config init tossctl config show tossctl auth login tossctl auth status tossctl auth doctor tossctl auth logout ``` ## 주문 ref rollover `amend`나 `cancel` 이후 브로커 쪽 주문 ref가 바뀔 수 있습니다. - `tossctl order show `가 local lineage cache를 통해 새 ref를 추적합니다. - lineage cache: `/trading-lineage.json` - 같은 조건의 canceled row가 여러 개면 수동 확인이 필요합니다. ## 개발 ```bash make build make test make fmt make tidy ``` ## FAQ **바로 주문까지 가능한가요?** US/KR 지정가 매수/매도, US 소수점 매수, 당일 미체결 취소가 live 검증되어 있습니다. `amend`는 추가 검증이 필요합니다. 모든 거래는 `config.json`에서 해당 액션을 허용한 뒤에만 실행됩니다. **공식 API인가요?** 아닙니다. 웹 내부 API를 재사용하는 비공식 프로젝트입니다. **왜 Playwright가 필요한가요?** 로그인 세션을 브라우저 흐름으로 확보하기 위해 필요합니다. 조회/거래 로직은 Go CLI에 구현되어 있습니다. **뭔가 깨진 것 같아요. 어디서부터 확인하나요?** `tossctl doctor --report` 를 실행하고 JSON 출력을 GitHub 이슈에 그대로 붙여주세요. 버전, OS, Chrome 버전, 세션 상태, `wts-api`/`wts-cert-api`/`wts-info-api` 3개 엔드포인트 실시간 응답(200/401/403), 파일 권한, 남은 임시 파일까지 한 번에 확인할 수 있어 대부분의 회귀를 빠르게 원인 파악할 수 있습니다. 홈 디렉토리 경로는 자동으로 `~`로 redact되어 사용자명이 노출되지 않습니다. ## 문서 - [`docs/architecture.md`](docs/architecture.md) - [`docs/configuration.md`](docs/configuration.md) - [`docs/reverse-engineering/`](docs/reverse-engineering/) - [`docs/trading/`](docs/trading/) - [`auth-helper/README.md`](auth-helper/README.md) ## 로컬 저장 경로 | 경로 | 설명 | |------|------| | `/config.json` | 거래 설정 | | `/session.json` | 브라우저 세션 | | `/trading-permission.json` | 임시 거래 권한 | | `/trading-lineage.json` | 주문 ref 추적 | `--config-dir`, `--session-file` 플래그로 경로를 덮어쓸 수 있습니다. ## Contributing 버그 제보와 PR은 환영합니다. ## Support 도움이 되었다면 유지보수에 힘을 보태 주세요.

## License MIT