Metadata-Version: 2.4
Name: tossinvest-strategy
Version: 0.2.0
Summary: Strategy-first Python SDK for Toss Invest Open API automated trading
Author: HG
Keywords: toss,tossinvest,openapi,trading,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests<3,>=2.34
Requires-Dist: urllib3<3,>=2.0
Provides-Extra: backtest
Requires-Dist: matplotlib<4,>=3.10; extra == "backtest"
Requires-Dist: numpy<3,>=2.2; extra == "backtest"
Requires-Dist: pandas<3,>=2.3; extra == "backtest"
Requires-Dist: yfinance<2,>=1.5; extra == "backtest"
Provides-Extra: realtime
Requires-Dist: websocket-client<2,>=1.8; extra == "realtime"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"

# 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` 예제를 제공합니다.

## 🚀 빠른 시작

```bash
pip install tossinvest-strategy
```

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

```python
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주를 시장가로 매수하는 샘플 전략입니다.

```python
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 예시:

```powershell
Copy-Item credentials.example credentials
```

`credentials` 파일 형식:

```text
client_id: your_client_id
client_secret: your_client_secret
```

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

```python
from tossinvestsdk import TossClient

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

환경변수도 지원합니다.

```bash
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 설치를 사용합니다.

```bash
pip install -e ".[dev]"
```

테스트 실행:

```bash
python -m pytest
```

SDK 배포 전 검증:

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

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

## 🛠️ 상태 보정

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

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

```bash
python scripts/reconcile_strategy_state.py TQQQ SOXL
```

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

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