| name | tossinvest |
| description | 토스증권 Open API로 국내(KRX)·미국 주식의 시세/호가/체결/캔들, 종목 정보, 환율, 장 운영 시간을 조회하고, 본인 계좌의 보유 주식·매수가능금액·주문을 조회/생성/정정/취소한다. "토스증권", "토스 주식", "내 주식 잔고", "삼성전자 현재가", "매수/매도 주문", "보유 종목", "tossinvest" 등 토스증권 계좌·시세·주문 작업이 필요할 때 사용. |
Toss Invest (토스증권 Open API)
pytossinvest 패키지의 tossinvest CLI 로 토스증권 Open API 를 다룬다.
20개 REST 엔드포인트(시세·종목·환율·장운영·계좌·자산·주문)를 커버한다.
이 플러그인은 /tossinvest:price, /tossinvest:holdings, /tossinvest:account slash command 도 제공한다.
사전 준비
- CLI 설치 (한 번만) — uv 로 격리 설치한다:
uv tool install git+https://github.com/yangs1202/pytossinvest.git
uv 가 없으면 먼저 설치한다(brew install uv 또는 curl -LsSf https://astral.sh/uv/install.sh | sh).
tossinvest 명령이 잡히지 않으면 uv tool update-shell 후 셸을 다시 연다.
(uv 가 정말 불가하면 pip install git+https://github.com/yangs1202/pytossinvest.git 로 대체 가능.)
- 인증 — 토스증권 WTS > 설정 > Open API 에서 발급한 키를 설정 파일 또는 환경변수로 설정.
설정 파일
~/.tossinvest/token.json (권한 600) 에 두면 어디서나 바로 동작한다:
{ "client_id": "tsck_live_...", "client_secret": "tssk_live_...", "account": 1 }
또는 환경변수(설정 파일보다 우선):
export TOSSINVEST_CLIENT_ID=tsck_live_...
export TOSSINVEST_CLIENT_SECRET=tssk_live_...
export TOSSINVEST_ACCOUNT=1
우선순위는 플래그 > 환경변수 > 설정 파일. 키가 없으면 사용자에게 발급/설정을 요청한다.
키는 절대 로그·터미널 출력·커밋에 그대로 노출하지 않는다.
안전 수칙 (중요)
- 시세·조회 명령은 자유롭게 사용해도 된다.
- 주문 생성·정정·취소(
order-create / order-modify / order-cancel)는 실제 체결되는 실거래다.
- 이 명령들은
--yes 플래그가 없으면 실행되지 않는다(가드).
- 실행 전 반드시 사용자에게 종목·방향·수량·가격을 요약해 확인받는다.
- 테스트 목적이면 현재가에서 크게 벗어난 지정가(체결 안 될 가격)로 주문 후 즉시 취소한다.
- 미국장 휴장 여부는
calendar-us 로, 매수가능금액은 buying-power 로, 매도가능수량은 sellable 로 먼저 확인한다.
CLI 사용법
출력은 JSON. -c 는 한 줄 출력, -a/--account 로 accountSeq override.
시세·종목 정보 (토큰만 필요)
tossinvest orderbook 005930
tossinvest price 005930 AAPL
tossinvest trades 005930 --count 10
tossinvest price-limits 005930
tossinvest candles 005930 --interval 1d --count 20
tossinvest stock 005930 AAPL
tossinvest warnings 005930
환율·장 운영 시간
tossinvest exchange-rate --base USD --quote KRW
tossinvest calendar-kr
tossinvest calendar-us --date 2026-03-25
계좌·자산 (accountSeq 필요)
tossinvest accounts
tossinvest holdings
tossinvest buying-power KRW
tossinvest sellable 005930
tossinvest commissions
주문 조회
tossinvest orders --status OPEN
tossinvest orders --status CLOSED --limit 20
tossinvest order <ORDER_ID>
주문 (실거래 — --yes 필수, 사전 확인 필수)
tossinvest order-create --symbol 005930 --side BUY --type LIMIT \
--quantity 10 --price 70000 --client-order-id my-001 --yes
tossinvest order-create --symbol AAPL --side BUY --type MARKET --amount 100 --yes
tossinvest order-modify <ORDER_ID> --type LIMIT --quantity 15 --price 71000 --yes
tossinvest order-cancel <ORDER_ID> --yes
주문 참고:
--quantity(수량) 와 --amount(금액) 중 정확히 하나만 사용. --amount 는 US 전용.LIMIT 은 --price 필수, MARKET 은 --price 전달 불가.- 1억원 이상 주문은
--high-value 필요.
--client-order-id 는 멱등성 키(10분 유효).
Python 라이브러리로 직접 쓰기
스크립트/자동화가 필요하면 라이브러리를 직접 사용한다:
from pytossinvest import TossInvestClient, TossInvestAPIError
client = TossInvestClient(client_id="...", client_secret="...", account_seq=1)
print(client.get_prices(["005930", "AAPL"]))
print(client.get_holdings())
조회 메서드는 응답 envelope 의 result 를 그대로 반환한다(dict/list).
종료 코드 (스크립트에서 분기 시)
0 성공 · 1 API 에러(stderr 에 에러 JSON) · 2 인증 정보 누락 · 3 거래 명령에 --yes 누락
에러 처리
에러는 {"error": {"status","code","message","requestId","data"}} 형태로 stderr 에 출력된다.
대표 코드: invalid-token(토큰 무효, 재발급 필요), order-hours-closed(주문 시간 아님),
insufficient-buying-power(잔고 부족), stock-not-found, rate-limit-exceeded(429, 자동 재시도됨).
참고
