한국어 · English

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

[!WARNING] 이 프로젝트는 토스증권 공식 제품이 아닙니다. 웹 내부 API를 비공식적으로 사용하며, 토스증권 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계좌 제한, 손실, 기타 불이익에 대해 개발자는 어떠한 책임도 지지 않습니다. 본인의 판단과 책임 하에 사용하세요.

[!IMPORTANT] 거래 기능은 설치 직후 모두 꺼져 있습니다. config.json에서 기능별로 직접 허용해야만 실행됩니다.

Works with

OpenClaw

Claude Code

Codex

Cursor

Bash

HTTP

Quick Start

For Agent

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

# 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 권한으로 저장됩니다.

세션 연장

토스 서버는 SESSION 쿠키(1년 Max-Age)와 별개로 약 7일짜리 활성 만료 시계를 운영합니다. 만료 24시간 전부터 모든 명령에 다음과 같은 stderr 경고가 표시됩니다.

⚠ session expires in ~18h; run `tossctl auth extend` to renew

tossctl auth extend 는 폰의 토스 앱에 푸시를 보내고 승인을 기다립니다.

$ tossctl auth extend
Waiting for approval in the Toss app on your phone...
✓ Extension complete. New expiry: 2026-05-13 07:03 KST (took 4s)

기본 timeout 은 120초이며 --timeout 60s 처럼 단축할 수 있습니다.

지원 범위

tossctl 은 토스 공식 Open API 의 조회·거래 표면을 100% 커버하고, 그 너머까지 다룹니다. 공식 Open API 문서의 모든 엔드포인트(계좌·잔고·시세·호가·체결·캔들·상하한가·매도가능수량·수수료·주문 등)에 대응하며, 추가로 수급·시장지수·AI 시그널·조건검색·관심종목 관리·거래내역 ledger·실시간 푸시·소수점 주문·dry-run preview 등 12개 이상이 공식에 없는 tossctl 고유 범위입니다.

토스증권 공식 Open API 는 현재 사전 신청자 대상으로 단계적 롤아웃 중이며, REST only 의 좁은 표면입니다 (공식 문서: https://developers.tossinvest.com/docs). 아래 표의 공식 API (예정) 칼럼은 그 문서 기준 공식이 커버하는 범위이고, tossctl 칼럼은 우리가 제공하는 범위입니다. 공식의 ✅ 행은 tossctl 도 전부 ✅ — 즉 공식 표면을 100% 커버합니다.

• ✅ 지원 · ❌ 미지원 · 🔸 부분 지원
• 공식 API (예정) 칼럼 = 공개 문서 기준 예상 커버리지 (사전 신청자 단계적 롤아웃 — 변동 가능).
• 공식 API (예정) 가 ❌ 인 행 = tossctl 고유 범위.

조회 (읽기 전용) · US·KR 공통

거래

공식 API 도 주문 생성·정정·취소를 제공하지만, 소수점 주문·통화 모드·dry-run preview·config 기반 안전 게이트 등 tossctl 의 거래 UX/안전장치는 우리 고유입니다.

모든 거래는 allow_live_order_actions=true도 필요합니다. 소수점 주문은 시장가(market order)로 자동 전환되며, 금액 기반입니다 (--currency-mode KRW 기본 또는 USD).

US 지정가는 --currency-mode로 가격 해석을 선택합니다: KRW (기본, 서버 환율로 USD 변환) 또는 USD (입력을 USD 가격 그대로 전송). 예: order place --symbol MRVL --side buy --qty 1 --price 158.01 --currency-mode USD.

Safety Model

거래 기능은 기본 전부 꺼져 있습니다. 한 건의 live 주문이 broker 에 닿으려면 영속(config) 게이트와 런타임(flag) 게이트를 모두 통과해야 합니다.

flowchart TD
    A["order place / cancel / amend"] --> P{"action 토글<br/>place·cancel·amend"}
    P -->|off| X1["❌ DisabledActionError"]
    P -->|on| S{"scope 선언<br/>sell·fractional<br/>(해당 시)"}
    S -->|위반| X2["❌ DisabledActionError"]
    S -->|ok| E{"--execute"}
    E -->|없음| PV["📋 preview만 출력<br/>(confirm token 발급)"]
    E -->|있음| M{"allow_live_order_actions"}
    M -->|false| X3["❌ ErrLiveActionsDisabled"]
    M -->|true| C{"--confirm token<br/>== preview token?"}
    C -->|불일치| X4["❌ ErrConfirmMismatch"]
    C -->|일치| GO["✅ broker 로 live mutation"]

    subgraph CFG["영속 게이트 · config.json"]
        P
        S
        M
    end
    subgraph RT["런타임 게이트 · CLI flag"]
        E
        C
    end

• 영속 게이트 (config.json): place/cancel/amend 경로 토글 + sell/fractional 스코프 선언 + allow_live_order_actions 마스터 킬스위치. (시장 US/KR 은 게이트 아님 — KR 주문이 US 보다 위험하지 않으므로 동일 취급)
• 런타임 게이트 (매 실행): --execute (preview 아닌 실제 실행) + --confirm <token> (preview 에서 받은 주문별 토큰).
• 진짜 안전장치는 주문별 --confirm <token> — preview 를 봐야만 얻을 수 있어, 의도하지 않은 주문은 토큰이 어긋나 차단됩니다.

v0.5.x 간소화 히스토리: 중복이던 TTL grant 레이어(internal/permissions)를 제거하고(allow_live_order_actions 가 같은 보호 제공), 거짓 이름이던 --dangerously-skip-permissions(이제 가리킬 permissions 가 없음 + 의미도 역방향)를 은퇴시켰습니다. 기존 플래그는 한 릴리즈 동안 deprecated no-op alias 로 받아들여 스크립트/agent 호환을 유지합니다.

Config

tossctl config init
tossctl config show

{
  "$schema": "https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/schemas/config.schema.json",
  "schema_version": 3,
  "trading": {
    "place": false,
    "sell": false,
    "fractional": false,
    "cancel": false,
    "amend": false,
    "allow_live_order_actions": false,
    "dangerous_automation": {
      "accept_fx_consent": false
    }
  },
  "update_check": {
    "enabled": true
  }
}

두 가지 유형의 토글:

• 경로 게이트 (place, cancel, amend) — broker API 분기가 실제로 다른 세 동작을 각각 독립적으로 켬/끔
• 스코프 선언 (sell, fractional) — 유저가 스스로 "난 이 범주의 주문은 안 낸다"고 선언하여 실수/버그/agent 오작동 방지

v0.4.3에서 trading.grant, dangerous_automation.complete_trade_auth, dangerous_automation.accept_product_ack가, v0.5.2에서 trading.kr(비대칭 시장 게이트 — KR 주문은 US 보다 위험하지 않아 제거, 시장 대칭 취급)이 제거되었습니다. 남아있는 구 설정은 자동 무시되며, 일반 명령 실행 시 stderr 경고 1줄(24h backoff)로 안내되고 config status/doctor에서도 표시됩니다.

주문 예시

지정가 매수 (US)

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 place \
  --symbol TSLL --side buy --qty 1 --price 18000 \
  --execute --confirm <token> \
  --output json

소수점 매수 (US, 금액 기반)

# 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 --confirm <token> \
  --output json

국내주식 매수

# config.json: place, kr, allow_live_order_actions → true

tossctl order place \
  --symbol 005930 --market kr --side buy --qty 1 --price 200000 \
  --execute --confirm <token>

매도

# config.json: sell → true (추가)

tossctl order place \
  --symbol TSLL --side sell --qty 1 --price 18000 \
  --execute --confirm <token>

다종목 시세

tossctl quote batch TSLL 005930 GOOG VOO --output table

이 프로젝트가 하지 않는 것

설치

brew tap JungHoonGhae/tossinvest-cli
brew install tossctl

Invoke-WebRequest -Uri https://github.com/JungHoonGhae/tossinvest-cli/releases/latest/download/tossctl-windows-amd64.zip -OutFile tossctl.zip
Expand-Archive tossctl.zip -DestinationPath .

git clone https://github.com/JungHoonGhae/tossinvest-cli.git
cd tossinvest-cli
make build

cd auth-helper
python3 -m pip install -e .

명령 표면

조회

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 <id>
tossctl quote get <symbol>
tossctl quote batch <symbol> [symbol...]
tossctl quote orderbook|sellable|commission <symbol>
tossctl watchlist list
tossctl export positions --market us|kr|all
tossctl export orders --market us|kr|all

거래

tossctl order preview --symbol <sym> --side <buy|sell> --qty <n> --price <krw>
tossctl order preview --symbol <sym> --side buy --fractional --amount <krw> --qty 0
tossctl order place ...flags... --execute --confirm <token>
tossctl order cancel --order-id <id> --symbol <sym> ...
tossctl order amend --order-id <id> ...

실시간 푸시

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.

시스템

tossctl version
tossctl doctor
tossctl doctor --report     # JSON 진단 번들 (이슈 첨부용, 경로 자동 redact)
tossctl config init
tossctl config show
tossctl auth login
tossctl auth status         # 세션 + Server Expiry (KST) 표시
tossctl auth extend         # 폰 푸시 승인으로 서버 측 ~7일 만료 연장
tossctl auth doctor
tossctl auth logout

API 회귀 감시

tossctl monitor api           # 16개 endpoint schema probe (병렬); exit 0 통과, 1 실패
tossctl monitor api --quiet   # cron 용

본인 머신에서 본인 세션으로 16개 read-only endpoint 응답 schema 를 병렬 점검합니다. #29 같은 토스 서버측 body 계약 변경을 조기 감지할 목적. exit code 만 반환하므로 알림 채널 (Discord / Slack / ntfy / macOS / 이메일) 은 cron 라인의 || <command> 우항에서 사용자가 합성합니다. 합성 recipe: AGENTS.md. 설정 가이드: docs/operations.md.

주문 ref rollover

amend나 cancel 이후 브로커 쪽 주문 ref가 바뀔 수 있습니다.

• tossctl order show <old-id>가 local lineage cache를 통해 새 ref를 추적합니다.
• lineage cache: <config dir>/trading-lineage.json
• 같은 조건의 canceled row가 여러 개면 수동 확인이 필요합니다.

개발

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/configuration.md
• docs/reverse-engineering/
• docs/trading/
• auth-helper/README.md

로컬 저장 경로

--config-dir, --session-file 플래그로 경로를 덮어쓸 수 있습니다.

Contributing

버그 제보와 PR은 환영합니다.

Support

도움이 되었다면 유지보수에 힘을 보태 주세요.

License

MIT