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 # 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) **Purpose**: Track orderbook metrics for all trades to prepare for real orderbook integration (Phase 2)
## Overview ## 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 ## Database Schema
@@ -54,6 +56,14 @@ docker compose restart trading-bot
- Estimates sufficient for pattern analysis - Estimates sufficient for pattern analysis
- Phase 2 will integrate Hyperliquid/Jupiter for real data - 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 ## Verification Queries
### Check Latest Trade with Orderbook Data ### Check Latest Trade with Orderbook Data
@@ -146,18 +156,22 @@ After next trade executes, verify:
# Then query database for orderbook data # Then query database for orderbook data
``` ```
## Phase 2 Roadmap ## Phase 2 Roadmap (Future Enhancement)
**Real Orderbook Integration** (Future - after Phase 1 validation): **Real Orderbook Integration**:
1. Integrate Hyperliquid API for real-time orderbook snapshots - Hyperliquid API for SOL/ETH orderbook data
2. Integrate Jupiter API for Solana DEX orderbook aggregation - Jupiter aggregator for DEX liquidity depth
3. Replace oracle estimates with actual L2 data - Replace oracle estimates with actual L2 orderbook snapshots
4. Add orderbook depth charts to analytics UI - Add real-time spread/imbalance monitoring
5. Implement smart entry based on orderbook liquidity
6. Detect and avoid low-liquidity traps
7. Optimize entry timing based on bid/ask pressure
**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 ## Troubleshooting