tossinvest-strategy

토스증권 Open API로 전략 매수와 자동매매 루프를 만들기 위한 Python SDK입니다.

tossinvest-strategy는 단순한 API 호출 래퍼보다 한 단계 더 나아가, 사용자가 직접 만든 투자 전략을 StrategyManager와 Scheduler에 연결해 계속 실행할 수 있도록 돕습니다.

계좌 조회, 주문, 시장 데이터 같은 기본 API는 물론이고, 전략 상태 저장과 거래 이력 관리까지 SDK 안에서 함께 다룰 수 있습니다.

자세한 개발/운영 기준은 PROJECT_GUIDE.md를 참고하세요.

✨ 이런 패키지입니다

• 🧩 전략 중심 구조: BaseStrategy, BaseStrategyConfig를 상속해 나만의 매수/매도 전략을 만들 수 있습니다.
• 🔁 계속 실행되는 자동매매 루프: StrategyManager가 여러 전략을 관리하고, Scheduler가 시장 시간에 맞춰 반복 실행합니다.
• 💾 상태 저장/복구: 장시간 실행과 재시작을 고려해 StrategyState, TradeHistory로 전략 상태와 거래 이력을 보존합니다.
• 📈 토스증권 Open API 래퍼: 계좌, 주문, 시장, 캘린더, 종목, 랭킹, 지표, 조건주문 API를 Python 객체로 호출합니다.
• ⚡ 실시간 WebSocket: 체결, 호가, 내 주문 이벤트를 인증된 연결로 구독합니다.
• 🧪 샘플 전략 포함: 매일 특정 조건에서 주식을 모으는 StockAccumulationStrategy 예제를 제공합니다.

0.3.0 변경사항

• 조건주문 SINGLE·OCO·OTO의 생성, 조회, 정정, 취소를 위한 typed SDK 모델과 API를 추가했습니다.
• 조건주문은 dry_run 초안 생성도 지원해, 실제 주문 전 요청값을 검증할 수 있습니다.
• 수동 기록형 Value Rebalancing과 무한매수 전략을 위한 사이클 상태 저장, 초기 구성, 다음 사이클 예약 CLI를 추가했습니다.
• 새 주문형 전략에서 공통으로 사용할 수 있는 DryRunStrategyConfig를 제공하며, 기본값은 실주문을 보내지 않는 dry_run=True입니다.

0.2.1 변경사항

• PyPI 프로젝트 설명에 0.2.0의 REST OpenAPI, WebSocket, 실시간 설치 및 사용 예시를 반영

0.2.0 변경사항

• TossInvest REST OpenAPI 1.2.14 반영 및 거래소별 전체 종목 조회 client.stock.list() 추가
• AsyncAPI 1.2.2 기반 client.realtime 추가: 체결, 호가, 내 주문 구독, ACK/에러 수신, keepalive, 수동 재연결
• REST/AsyncAPI 명세 버전과 공식 소스 URL을 SDK에 포함하고 동기화 도구 제공

🚀 빠른 시작

pip install tossinvest-strategy

실시간 WebSocket을 사용하려면 선택 의존성을 설치합니다.

pip install "tossinvest-strategy[realtime]"

Python import 이름은 패키지명과 다릅니다. 코드에서는 tossinvestsdk를 사용합니다.

from tossinvestsdk import TossClient

client = TossClient()

prices = client.market.price(["AAPL", "MSFT"])
portfolio = client.account.portfolio()
open_orders = client.order.open_orders()

print(prices)
print(portfolio)
print(open_orders)

⚡ 실시간 WebSocket

client.realtime은 REST 인증 토큰을 재사용합니다. 구독 변경은 토스증권 프로토콜의 선언형 전체 교체 규칙에 맞춰 처리됩니다.

from tossinvestsdk import TossClient

with TossClient() as client:
    realtime = client.realtime.connect()
    realtime.subscribe_trades(["TQQQ", "SOXL"], market="US")
    realtime.subscribe_orderbooks("005930", market="KR")

    while True:
        message = realtime.receive()
        if message.type == "message":
            print(message.topic, message.data)

realtime.ping()으로 keepalive를 보내고, 연결이 끊긴 뒤에는 realtime.reconnect()로 인증과 마지막 구독 집합을 복원할 수 있습니다. 공개 체결 연결만 확인하려면 다음 예제를 사용합니다.

python examples/realtime_smoke.py --symbol TQQQ --market US

🧠 전략 매수 예시

아래 예시는 삼성전자(005930) 현재가가 250,000원 미만이면 하루 한 번 1주를 시장가로 매수하는 샘플 전략입니다.

from tossinvestsdk import TossClient, Scheduler, StrategyManager
from tossinvestsdk.strategy.samples import (
    StockAccumulationConfig,
    StockAccumulationStrategy,
)

client = TossClient()

manager = StrategyManager(client, market="KR")
manager.add(
    StockAccumulationStrategy(
        StockAccumulationConfig(
            symbol="005930",
            target_price=250000,
            quantity=1,
        )
    )
)

Scheduler(client, manager, market="KR").run_forever(interval=30)

이 구조를 그대로 활용하면 삼성전자뿐 아니라 여러 종목, 여러 전략을 하나의 실행 루프에서 함께 운용할 수 있습니다.

🏗️ 구조

핵심 패키지는 tossinvestsdk입니다.

🔐 인증 파일

SDK는 기본적으로 실행 중인 메인 스크립트와 같은 디렉터리의 credentials 파일을 읽고, 토큰 캐시는 token.json에 저장합니다.

이 저장소에는 실제 인증 정보가 아니라 샘플 파일만 포함합니다.

• credentials.example: 사용자가 복사해서 채워 넣을 인증 파일 템플릿
• token.example.json: 토큰 캐시 구조 예시

Windows PowerShell 예시:

Copy-Item credentials.example credentials

credentials 파일 형식:

client_id: your_client_id
client_secret: your_client_secret

명시적으로 경로를 넘길 수도 있습니다.

from tossinvestsdk import TossClient

client = TossClient(
    credential_file="config/credentials",
    token_file="state/token.json",
)

환경변수도 지원합니다.

TOSSINVEST_CREDENTIAL_FILE=config/credentials
TOSSINVEST_TOKEN_FILE=state/token.json

📦 포함되는 것과 포함되지 않는 것

이 저장소는 자동매매 프로그램 전체가 아니라 SDK 배포에 필요한 패키지, 문서, 예제, 테스트만 포함합니다.

포함되는 것:

• tossinvestsdk* 패키지
• 전략 작성용 base class와 manager/scheduler
• 샘플 전략 StockAccumulationStrategy
• 예제 코드와 문서
• 테스트와 배포 전 검증 스크립트

포함하지 않는 것:

• 실제 credentials, token.json
• strategy_state/, trade_history/, logs/
• 개인 전략, 백테스트 데이터, 로컬 운영 스크립트
• build/, dist/, *.egg-info, 캐시 파일

🧪 개발/검증

개발 중에는 프로젝트 루트에서 editable 설치를 사용합니다.

pip install -e ".[dev]"

테스트 실행:

python -m pytest

SDK 배포 전 검증:

python scripts/preflight.py
python scripts/preflight.py --with-wheel

preflight는 컴파일, pytest, OpenAPI 커버리지 점검, SDK 요청 smoke check, 패키지 포함 파일 검사를 실행합니다.

🛠️ 상태 보정

전략 회계 기준이 바뀌었거나 수수료/세금 반영 방식이 달라졌다면, 실거래 자동매매를 계속 실행하기 전에 상태 파일을 점검해야 합니다.

먼저 dry-run으로 차이를 확인합니다.

python scripts/reconcile_strategy_state.py TQQQ SOXL

주문 상세 API를 이용해 보정하고 실제 상태 파일에 반영하려면 다음처럼 실행합니다.

python scripts/reconcile_strategy_state.py TQQQ SOXL --use-api --write

--write를 사용하면 기존 상태 파일의 백업 .bak 파일을 먼저 생성합니다.

📚 문서

• PROJECT_GUIDE.md: 프로젝트 구조, SDK 사용 흐름, 전략/상태/운영 지침
• docs/REALTIME.md: 실시간 WebSocket 상세 사용법
• docs/API_COVERAGE.md: REST OpenAPI 지원 범위와 명세 버전
• docs/API_COVERAGE.md: OpenAPI 전체 지원 점검 요약
• docs/LOGGING_AND_ERRORS.md: 로깅, 재시도, 예외 정책
• docs/INTEGRATION_CHECKLIST.md: 실제 계정 기반 read-only/live-order 점검 절차
• docs/RELEASE_CHECKLIST.md: 배포 전 체크리스트
• docs/PYPI_RELEASE.md: PyPI/TestPyPI 배포 절차

⚠️ 주의

이 SDK는 자동매매와 주문 생성을 도울 수 있는 도구입니다. 실제 주문 전에는 반드시 소액 또는 read-only 흐름으로 충분히 검증하고, 사용하는 전략의 손실 가능성을 직접 이해한 뒤 실행하세요.