root/trading_bot_v4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Clarify orderbook shadow logging scope for next agent

Browse Source 
Key clarifications in ORDERBOOK_SHADOW_LOGGING.md:

1. Trade execution only (NOT periodic):
   - Orderbook captured in /api/trading/execute (lines 1037-1053)
   - NOT captured in /api/trading/market-data (1-minute feed)
   - Frequency: 3-5 orderbook snapshots per day (when trades execute)
   - vs. 1,440 market data updates per day (price/ATR/ADX/RSI)

2. Phase 1.5 declined (Dec 19, 2025):
   - User asked about 1-minute periodic orderbook capture
   - Agent explained tradeoffs: 1,440 API calls/day, more storage
   - User confirmed trade-time capture sufficient for now
   - Periodic monitoring not needed for Phase 1 validation

3. Scope clarity for resumption:
   - Phase 1 complete and deployed
   - Goal: Collect 50-100 trades with orderbook data
   - Phase 2: Real orderbook API integration (Hyperliquid/Jupiter)
   - Next agent: Monitor trade data collection, analyze patterns

Status: ✅ All Phase 1 tasks complete, awaiting first trade validation
This commit is contained in:
mindesbunister
2025-12-19 09:07:46 +01:00
parent 6990f20d6f
commit 67dde80679
1 changed files with 26 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/ORDERBOOK_SHADOW_LOGGING.md
View File

@@ -1,11 +1,13 @@
# Orderbook Shadow Logging System
**Status**: ✅ DEPLOYED (Dec 18, 2025)
**Status**: ✅ DEPLOYED (Dec 19, 2025)
**Purpose**: Track orderbook metrics for all trades to prepare for real orderbook integration (Phase 2)
## Overview
Phase 1 implementation: Oracle-based estimates with 2bps spread assumption. Captures orderbook snapshots at trade execution for future analysis.
Phase 1 implementation: Oracle-based estimates with 2bps spread assumption. Captures orderbook snapshots **at trade execution only** (not periodic).
**Critical Scope Note**: Orderbook data is captured ONLY when trades execute via `/api/trading/execute`, NOT during 1-minute market data feed updates (`/api/trading/market-data`). The 1-minute feed captures price/ATR/ADX/RSI metrics but does NOT capture orderbook data. This is intentional to minimize API overhead - we only need orderbook state at the moment of trade execution.
## Database Schema
@@ -54,6 +56,14 @@ docker compose restart trading-bot
- Estimates sufficient for pattern analysis
- Phase 2 will integrate Hyperliquid/Jupiter for real data
**CRITICAL: Trade Execution Only**:
- Orderbook capture happens in `/api/trading/execute` endpoint (lines 1037-1053)
- Triggered ONLY when trade signal executes (not periodic)
- `/api/trading/market-data` endpoint (1-minute feed) does NOT capture orderbook data
- 1-minute feed captures: ATR, ADX, RSI, volume, price position (stored in MarketData table)
- Orderbook data stored in: Trade table (7 columns added via ALTER TABLE)
- Frequency: 3-5 orderbook snapshots per day (when trades execute) vs. 1,440 market data updates per day
## Verification Queries
### Check Latest Trade with Orderbook Data
@@ -146,18 +156,22 @@ After next trade executes, verify:
# Then query database for orderbook data
```
## Phase 2 Roadmap
## Phase 2 Roadmap (Future Enhancement)
**Real Orderbook Integration** (Future - after Phase 1 validation):
1. Integrate Hyperliquid API for real-time orderbook snapshots
2. Integrate Jupiter API for Solana DEX orderbook aggregation
3. Replace oracle estimates with actual L2 data
4. Add orderbook depth charts to analytics UI
5. Implement smart entry based on orderbook liquidity
6. Detect and avoid low-liquidity traps
7. Optimize entry timing based on bid/ask pressure
**Real Orderbook Integration**:
- Hyperliquid API for SOL/ETH orderbook data
- Jupiter aggregator for DEX liquidity depth
- Replace oracle estimates with actual L2 orderbook snapshots
- Add real-time spread/imbalance monitoring
**Data Collection Goal**: 50-100 trades with shadow logging before Phase 2 implementation
**Potential Phase 1.5 (User Declined Dec 19, 2025)**:
- Periodic orderbook capture via 1-minute market data feed
- Would store orderbook snapshots every 1 minute in separate table (not Trade table)
- Use case: Track spread/imbalance trends over time independent of trades
- Tradeoffs: More API calls (1,440/day vs. 3-5/day), more storage, minimal benefit for Phase 1 validation
- Decision: User confirmed trade-time capture sufficient for now, periodic monitoring not needed yet
## Analysis Queries
## Troubleshooting