From f8355248b438b9a6549811b24c4cea03321081d5 Mon Sep 17 00:00:00 2001 From: choijaewook Date: Fri, 20 Mar 2026 17:12:39 +0900 Subject: [PATCH] Add crypto signal dashboard design spec Comprehensive spec covering: 4 analysis agents (technical, news, social, AI), signal scoring engine, virtual $200 spot portfolio simulator with P&L tracking, Streamlit dashboard with sidebar+detail layout, and failure handling strategy. Co-Authored-By: Claude Opus 4.6 (1M context) --- ...26-03-20-crypto-signal-dashboard-design.md | 320 ++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-20-crypto-signal-dashboard-design.md diff --git a/docs/superpowers/specs/2026-03-20-crypto-signal-dashboard-design.md b/docs/superpowers/specs/2026-03-20-crypto-signal-dashboard-design.md new file mode 100644 index 0000000..95dfba7 --- /dev/null +++ b/docs/superpowers/specs/2026-03-20-crypto-signal-dashboard-design.md @@ -0,0 +1,320 @@ +# Crypto News Signal Dashboard — Design Spec + +## Overview + +Binance 현물(Spot) 코인을 대상으로 뉴스, 소셜미디어, 기술적 분석, AI 분석을 종합하여 매수/매도 시그널을 생성하고, 가상 $200 포트폴리오로 시뮬레이션하는 대시보드. + +## Tech Stack + +- **App**: Streamlit (단일 프로세스, Sidebar + Detail 레이아웃) +- **Scheduler**: APScheduler (in-process background thread) +- **Storage**: SQLite WAL mode (시그널 이력, 포트폴리오, 거래 기록) + JSON cache (API 응답) +- **Language**: Python 3.11+ + +## Application Topology + +Streamlit이 메인 프로세스로 동작하며, FastAPI 없이 Python 모듈을 직접 import하여 사용한다. + +``` +[Streamlit Process (main)] + ├── imports agents/* (직접 호출) + ├── imports engine/* (직접 호출) + ├── imports data/* (직접 호출) + ├── APScheduler (in-process, background thread) + │ └── 15분마다 agents 실행 → engine 업데이트 + └── Binance WebSocket (background thread) + └── 실시간 가격 업데이트 → st.session_state +``` + +- **단일 프로세스**: Streamlit이 모든 모듈을 직접 import. 별도 FastAPI 서버 불필요 +- **Scheduler**: APScheduler가 Streamlit 프로세스 내 background thread로 동작 +- **WebSocket**: python-binance의 ThreadedWebsocketManager로 background에서 가격 수신 +- **Storage**: SQLite WAL 모드 (concurrent read 허용, single-writer) + +## Architecture + +### Data Sources + +| Source | API | Purpose | Update Cycle | +|--------|-----|---------|-------------| +| Binance | REST + WebSocket | 가격, 거래량, OHLCV, 시가총액 순위 | 실시간 (WebSocket) | +| CryptoPanic / NewsAPI | REST | 크립토 뉴스 헤드라인 | 15분 | +| Twitter/X API | REST | 코인별 언급량, 감성 | 15분 | +| Reddit API | REST | r/cryptocurrency 등 감성 분석 | 15분 | +| Claude API | REST | 시장 상황 종합 분석, 뉴스 영향도 판단 | 15분 | + +### Analysis Agents + +4개의 독립적인 분석 에이전트가 각 코인에 대해 0~100 점수를 산출한다. + +#### 1. Technical Agent (기본 가중치: 60%) +- **Indicators**: RSI(14), MACD(12,26,9), Bollinger Bands(20,2), 이동평균(SMA 20/50/200) +- **Volume Analysis**: 거래량 급증 감지, OBV(On-Balance Volume) +- **Candlestick Patterns**: Engulfing, Doji, Hammer 등 주요 패턴 +- **Input**: Binance OHLCV 데이터 (1h, 4h, 1d 캔들) +- **Output**: 0~100 기술적 점수 + +#### 2. News Agent (기본 가중치: 20%) +- **Sources**: CryptoPanic API, NewsAPI +- **Analysis**: 헤드라인 감성 분석 (positive/negative/neutral) +- **Scoring**: 최근 24시간 뉴스의 감성 비율 + 뉴스 영향도(중요도) 가중 +- **Output**: 0~100 뉴스 감성 점수 + +#### 3. Social Agent (기본 가중치: 10%) +- **Sources**: Twitter/X API, Reddit API (r/cryptocurrency, r/binance) +- **Metrics**: 코인별 언급량 추세, 감성 분석, 인플루언서 언급 가중치 +- **Analysis**: 24시간 언급량 변화율 + 감성 비율 +- **Output**: 0~100 소셜 감성 점수 + +#### 4. AI Agent (기본 가중치: 10%) +- **Provider**: Claude API (Anthropic) +- **Input**: 최근 뉴스 요약, 기술적 지표 요약, 소셜 감성 요약, 시장 전반 상황 +- **Task**: 종합적 시장 컨텍스트 판단, 각 코인의 단기 전망 평가 +- **Output**: 0~100 AI 종합 점수 + 텍스트 분석 요약 + +### Signal Engine + +#### Score Aggregator +``` +composite_score = (technical * w1) + (news * w2) + (social * w3) + (ai * w4) +where w1 + w2 + w3 + w4 = 1.0 +defaults: w1=0.6, w2=0.2, w3=0.1, w4=0.1 +``` + +#### Signal Classification +- **BUY**: composite_score >= 70 +- **HOLD**: 40 <= composite_score < 70 +- **SELL**: composite_score < 40 + +#### Surge Detector +- 바이낸스 전체 코인 중 거래량이 24h 평균 대비 300% 이상 급증한 코인을 자동 감지 +- 감지된 코인을 모니터링 목록에 자동 추가 +- Top 50에 없더라도 급등/급락 코인 포착 가능 + +### Coin Scope +- **Base**: 시가총액 Top 50 (USDT 페어 기준) +- **Auto-add**: 거래량 급증 코인 (Surge Detector) +- **User pin**: 사용자가 수동으로 추가한 코인 +- **Pair**: 모든 코인은 USDT 현물 페어 기준 + +## Portfolio Simulator + +### Rules +- **초기 자본**: $200 (가상) +- **거래 방식**: Binance 현물(Spot)만 사용. 레버리지/마진/선물/공매도 없음 +- **최대 동시 포지션**: 5개 + +### Entry (매수) +- Signal score >= 70인 코인 중 점수가 높은 순서대로 매수 +- Position size: 가용 현금의 15~30% (점수가 높을수록 큰 비중) + - Score 70~79: 15% of cash + - Score 80~89: 20% of cash + - Score 90~100: 30% of cash +- 가용 현금이 없으면 매수하지 않음 +- **최소 포지션**: $15 미만이면 매수하지 않음 (바이낸스 최소 주문 규모 고려) + +### Exit (매도) +- **Signal exit**: 보유 코인의 score가 39 이하로 하락 시 전량 매도 +- **Stop-loss**: 진입가 대비 -8% 하락 시 자동 손절 +- **Take-profit 1차**: 진입가 대비 +15% 상승 시 50% 부분 익절 +- **Take-profit 2차**: 진입가 대비 +25% 상승 시 나머지 전량 익절 + +### Reinvestment (재투자) +- 매도 후 현금은 가용 풀로 복귀 +- 다음 15분 분석 주기에 새로운 BUY 시그널 탐색 +- 가장 높은 점수의 코인부터 우선 배분 + +### P&L Tracking +- **Per-trade P&L**: 각 거래의 실현 손익 (진입가 vs 퇴장가) +- **Per-position P&L**: 보유 중인 포지션의 미실현 손익 (진입가 vs 현재가) +- **Total portfolio P&L**: 초기 자본 대비 총 수익률 +- **Win rate**: 수익 거래 / 전체 거래 +- **Average gain/loss**: 평균 수익 / 평균 손실 + +## Dashboard (Streamlit) + +### Layout: Sidebar + Detail + +#### Sidebar (Left) +- 코인 목록 + 종합 점수 +- 색상 코딩: BUY(green), HOLD(yellow), SELL(red) +- 코인 클릭 시 우측 Detail 영역 변경 +- 정렬: 점수 높은 순 (BUY 순위) +- 하단: 가중치 슬라이더 (사용자 커스텀) + +#### Detail Area (Right) +선택한 코인의 상세 정보를 4개 패널로 표시: + +1. **Chart Panel**: 캔들스틱 차트 + RSI/MACD/BB 오버레이. plotly 사용 +2. **News Panel**: 최근 뉴스 헤드라인 목록 + 감성 태그 +3. **Social Panel**: Twitter/Reddit 언급량 추세 차트 + 주요 글 +4. **AI Panel**: Claude 분석 요약 텍스트 + 시그널 근거 + +#### Portfolio Tab +- Summary bar: 초기자본, 현재가치, 총 P&L, 승률, 가용 현금 +- Current Holdings: 보유 포지션 테이블 (코인, 배분금액, 수량, 평균진입가, 현재가, P&L) +- Trade History: 청산 거래 이력 (날짜, 코인, 진입/퇴장가, 사이즈, P&L, 사유) +- Allocation Chart: 원형 차트 (코인별 비중 + 현금) + +## Update Cycle + +| Component | Cycle | Method | +|-----------|-------|--------| +| Price data | Realtime | Binance WebSocket | +| Technical indicators | On price update | Calculated from OHLCV | +| News analysis | Every 15 min | APScheduler → CryptoPanic/NewsAPI | +| Social analysis | Every 15 min | APScheduler → Twitter/Reddit API | +| AI analysis | Every 15 min | APScheduler → Claude API | +| Signal scoring | Every 15 min | After all agents complete | +| Portfolio rebalance | Every 15 min | After signal scoring | + +## Project Structure + +``` +crypto_news_trading/ +├── run.py # Streamlit entry point (streamlit run run.py) +├── config.py # API keys, settings, defaults +├── requirements.txt +├── .env # API keys (gitignored) +│ +├── agents/ +│ ├── __init__.py +│ ├── technical.py # Technical analysis agent +│ ├── news.py # News sentiment agent +│ ├── social.py # Social media agent +│ └── ai_analyst.py # Claude AI agent +│ +├── engine/ +│ ├── __init__.py +│ ├── signal.py # Score aggregator + signal classifier +│ ├── surge.py # Volume surge detector +│ └── portfolio.py # Portfolio simulator + P&L tracker +│ +├── data/ +│ ├── __init__.py +│ ├── binance_ws.py # Binance WebSocket client +│ ├── binance_rest.py # Binance REST client +│ ├── news_client.py # CryptoPanic / NewsAPI client +│ ├── social_client.py # Twitter / Reddit client +│ └── db.py # SQLite DB manager +│ +├── dashboard/ +│ ├── app.py # Streamlit main app +│ ├── sidebar.py # Coin list sidebar +│ ├── detail.py # Detail panels (chart, news, social, ai) +│ └── portfolio_view.py # Portfolio dashboard +│ +├── scheduler/ +│ └── jobs.py # APScheduler job definitions +│ +├── logs/ # Log files (gitignored) +│ +└── db/ + └── schema.sql # SQLite schema +``` + +## Database Schema (SQLite) + +### signals +| Column | Type | Description | +|--------|------|-------------| +| id | INTEGER PK | Auto increment | +| coin | TEXT | Symbol (e.g., BTCUSDT) | +| timestamp | DATETIME | Signal time | +| technical_score | REAL | 0~100 | +| news_score | REAL | 0~100 | +| social_score | REAL | 0~100 | +| ai_score | REAL | 0~100 | +| composite_score | REAL | Weighted sum | +| signal | TEXT | BUY / HOLD / SELL | + +### trades +| Column | Type | Description | +|--------|------|-------------| +| id | INTEGER PK | Auto increment | +| coin | TEXT | Symbol | +| side | TEXT | BUY / SELL | +| price | REAL | Execution price | +| quantity | REAL | Coin quantity | +| amount_usd | REAL | USD value | +| timestamp | DATETIME | Trade time | +| reason | TEXT | Signal/stop-loss/take-profit | + +### positions +| Column | Type | Description | +|--------|------|-------------| +| id | INTEGER PK | Auto increment | +| coin | TEXT | Symbol | +| entry_price | REAL | Average entry price | +| quantity | REAL | Current quantity | +| invested_usd | REAL | Total USD invested | +| status | TEXT | OPEN / CLOSED | +| opened_at | DATETIME | Position open time | +| closed_at | DATETIME | Position close time (nullable) | + +### portfolio +| Column | Type | Description | +|--------|------|-------------| +| id | INTEGER PK | Auto increment | +| timestamp | DATETIME | Snapshot time | +| total_value | REAL | Portfolio total value | +| cash | REAL | Available cash | +| pnl | REAL | Total P&L | +| pnl_pct | REAL | P&L percentage | + +## Failure Handling + +| Failure | Recovery | +|---------|----------| +| Binance WebSocket 끊김 | 자동 reconnect (python-binance 내장), 3회 실패 시 REST fallback | +| CryptoPanic/NewsAPI 실패 | 캐시된 마지막 결과 사용, 뉴스 점수를 50 (neutral)로 설정 | +| Twitter API 미사용/실패 | Reddit만으로 소셜 점수 산출 | +| Reddit API 실패 | 소셜 점수를 50 (neutral)로 설정 | +| Claude API 타임아웃 | AI 점수를 50으로 설정, 이전 분석 텍스트 유지 | +| Agent가 점수 미산출 | 해당 에이전트 점수 50, 나머지 에이전트로 가중 재배분 | + +## Rate Limit & Cost + +### API Call Budget (per 15-min cycle) +- **Binance REST**: ~5 calls (Top 50 목록 + surge scan). WebSocket은 별도 +- **CryptoPanic**: ~1 call (전체 뉴스 조회 후 코인별 필터링) +- **Reddit**: ~3 calls (subreddit별 조회) +- **Twitter**: ~5 calls (있을 경우) +- **Claude API**: ~2-3 calls (코인을 배치로 묶어 분석. Top 10은 매 주기, 나머지는 1시간 간격) + +### Claude API 예상 비용 +- 배치 분석: ~2,000 input tokens + ~500 output tokens per call +- 하루 ~150 calls → 월 ~$5-15 (Sonnet 기준) + +## Logging + +- Python `logging` 모듈, `RotatingFileHandler` (10MB, 5 backups) +- 로그 레벨: 시그널 결정(INFO), 거래 실행(INFO), API 에러(WARNING), 시스템 에러(ERROR) +- 로그 파일: `logs/app.log` + +## Data Retention + +- signals 테이블: 90일 보관, 이후 일별 요약으로 집계 후 삭제 +- trades/positions: 영구 보관 +- portfolio 스냅샷: 90일 보관 + +## Database Schema Additions + +### settings +| Column | Type | Description | +|--------|------|-------------| +| key | TEXT PK | Setting name | +| value | TEXT | JSON-encoded value | + +사용자 가중치, surge 임계값, 포트폴리오 설정 등을 저장. + +## API Keys Required + +| Service | Env Variable | Required | +|---------|-------------|----------| +| Binance | BINANCE_API_KEY, BINANCE_SECRET | Yes | +| CryptoPanic | CRYPTOPANIC_API_KEY | Yes | +| NewsAPI | NEWS_API_KEY | Optional (fallback) | +| Twitter/X | TWITTER_BEARER_TOKEN | Optional (유료 API, 없으면 Reddit만 사용) | +| Reddit | REDDIT_CLIENT_ID, REDDIT_SECRET | Yes | +| Anthropic (Claude) | ANTHROPIC_API_KEY | Yes |