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 객체로 호출합니다.
• 🧪 샘플 전략 포함: 매일 특정 조건에서 주식을 모으는 StockAccumulationStrategy 예제를 제공합니다.

🚀 빠른 시작

pip install tossinvest-strategy

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)

🧠 전략 매수 예시

아래 예시는 삼성전자(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입니다.

영역	설명
TossClient	인증, 토큰, HTTP 요청, API 객체를 묶는 진입점
client.account	계좌, 잔고, 포트폴리오 조회
client.order	매수/매도 주문, 주문 조회/취소
client.market	가격, 캔들, 호가, 시장 시간 조회
client.stock	종목 정보 조회
client.ranking	랭킹 API
client.indicator	지표 API
client.conditional	조건주문 API
StrategyManager	여러 전략 관리
Scheduler	시장 시간 기반 반복 실행
StrategyState / TradeHistory	전략 상태와 거래 이력 저장

🔐 인증 파일

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/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 흐름으로 충분히 검증하고, 사용하는 전략의 손실 가능성을 직접 이해한 뒤 실행하세요.