surge-bot 🌍

해외주식 급등 신호를 기본 공개 설정의 shadow + paper=true 환경에서 검증하고, 주문 의도부터 체결·포지션 반영까지의 상태를 durable ledger로 관리하는 Python 연구 프로젝트입니다.

교육·연구용 소프트웨어이며 투자 자문이 아닙니다. 공개본에는 실계좌 설정, 운영 거래 기록, 고객·계정 데이터가 없습니다.

자동매매에서 가장 위험한 문제는 신호 정확도만이 아닙니다. 브로커가 주문을 접수한 직후 응답이 유실되면, 무작정 재시도한 주문이 중복 체결될 수 있습니다. surge-bot은 이 실패 구간을 명시적인 상태와 복구 규칙으로 다룹니다.

• Durable order state machine — 주문 전 의도를 저장하고 SUBMITTING timeout을 AMBIGUOUS로 격리합니다.
• Recovery-only startup gate — 미종결 명령을 브로커 증거와 대조하기 전에는 신규 진입을 허용하지 않습니다.
• Transactional outbox — ledger 변경과 외부 전달 이벤트를 같은 트랜잭션에 기록합니다.
• Idempotent reconciliation — execution delta와 event ID를 이용해 재시작·중복 전달에 견딥니다.
• Namespace isolation — 계좌·전략·심볼 단위 상태가 섞이지 않도록 분리합니다.
• Operational controls — heartbeat, loop budget, graceful shutdown, runtime metric을 테스트합니다.

flowchart LR
    A[Market data] --> B[Signal & risk gates]
    B --> C[Durable command: PREPARED]
    C --> D[Broker adapter]
    D -->|ack| E[ACKED / PARTIAL / FILLED]
    D -->|timeout| F[AMBIGUOUS]
    E --> G[Idempotent ledger apply]
    F --> H[Recovery reconciliation]
    G --> I[Transactional outbox]
    H --> G
    I --> J[Report / notification adapter]

상세 설계 판단은 ADR에서 확인할 수 있습니다.

surgebot/          신호·리스크·브로커·ledger·outbox·운영 제어
scripts/           공개용 단발 실행 진입점
tests/             운영 데이터 없이 실행되는 회귀 테스트
docs/decisions/    상태기계·outbox·저장소 경계 ADR
config.yaml        shadow/paper 예시 설정

Python 3.12 이상을 권장합니다.

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/python -m pytest -q

paper 주문 단발 실행 예시:

SURGE_CONFIG=config.yaml ./.venv/bin/python scripts/run_once.py

• config.yaml은 shadow/paper 예시입니다.
• API 키와 계좌 자격증명은 환경변수 또는 로컬 .env로만 주입합니다.
• SURGE_TESTING=1 및 pytest에서는 암묵적 저장소가 임시 DB로 라우팅됩니다.
• 실주문은 공개 설정만으로 활성화되지 않습니다.

• 공개 snapshot 기준 182개 pytest 회귀 테스트
• 주문 상태·outbox·복구 gate·namespace·shutdown·rate limit·credential redaction 검증

• 수익률·실거래 성과를 주장하지 않습니다.
• 브로커·시장 데이터 API의 이용약관과 계정 안전은 실행자가 별도로 검증해야 합니다.
• PostgreSQL 전환 방향은 ADR에 기록돼 있지만, 공개본의 기본 원장은 SQLite입니다.

• 취약점 제보와 민감정보 정책: SECURITY.md
• 소스는 공개되어 있으나 별도 사용 허가는 부여되지 않습니다: LICENSE