Opportunity Scanner v5
521 perps on Hyperliquid. Fetching candles + computing technicals for all = 500k+ tokens. This scanner screens everything but only burns tokens on real opportunities.
All computation in Python. Near-zero LLM tokens.
The 4-Stage Funnel
Stage 0: BTC Macro Context
Source: BTC 4h + 1h candles (2 API calls). Output: btc_trend (strong_down/down/neutral/up/strong_up) and a macro_modifier applied to all final scores. Configurable via scanner-config.json.
Stage 1: Bulk Screen (~0 LLM tokens)
Source: Single API call — metaAndAssetCtxs. Filter: 24h volume > $500K (configurable). Output: ~70 assets that pass minimum liquidity.
Stage 2: Smart Money + Freshness Overlay (~0 LLM tokens)
Sources: leaderboard_get_markets + leaderboard_get_top (limit=100). Two entries per asset (long + short) — keeps dominant side. Freshness: avgAtPeak (>85% = live, <50% = stale), nearPeakPct. Filter: Top 15-16 by quick score. Force-include top 8 SM assets.
Stage 3: Deep Dive — Multi-Timeframe (~0 LLM tokens)
Parallel candle fetches via ThreadPoolExecutor (~20s vs ~60s sequential).
| Timeframe | Period | Candles | Purpose |
|---|---|---|---|
| 4h | 7 days | ~42 | Macro trend (EMA 5/13 crossover) |
| 1h | 24h | ~24 | Hourly trend structure + RSI, volume, S/R, patterns |
| 15m | 6h | ~24 | Entry: RSI, patterns, momentum, volume divergence |
v5: Hourly Trend Classification — analyzes swing highs/lows in 1h data to classify as UP/DOWN/NEUTRAL. See references/hourly-trend.md for the algorithm.
This is the #1 gate for all trade decisions. NEVER open a LONG on hourlyTrend: "DOWN" or a SHORT on hourlyTrend: "UP".
Per-TF error recovery: if 15m fetch fails, analysis continues with 4h+1h data.
Stage 4: Cross-Scan Momentum
Saves results to scan-history.json. Computes scoreDelta (change from last scan) and scanStreak (consecutive appearances).
4-Pillar Scoring (25% each, 0-400 total)
See references/scoring.md for the complete point breakdowns.
Pillar 1: Smart Money (25%)
PnL contribution tiers, trader count (v5: 400+ = +30 pts), acceleration, freshness. Trader count separates real signals from noise — conviction 4 with 130 traders caused whipsaws, conviction 4 with 400+ was consistently real.
Pillar 2: Market Structure (25%)
Volume, volume surge, open interest, OI/volume ratio.
Pillar 3: Technicals (25%)
4h trend alignment, 1h trend structure (v5), RSI multi-TF convergence, volume confirmation, candlestick patterns, momentum. Counter-trend on hourly: -30 points (v5).
Pillar 4: Funding (25%)
Neutral funding is best (+40). Favorable extreme is strong (+35). Unfavorable extreme hurts (-20).
BTC Macro Modifier
Applied to final scores. Penalizes alt LONGs during BTC downtrend, boosts SHORTs (and vice versa). All modifiers configurable.
Hard Disqualifiers (v5)
These cause an opportunity to be skipped entirely, not just penalized:
| Condition | Rationale |
|---|---|
| Counter-trend on hourly | SM conviction on a 1-min bounce doesn't override a 2-week downtrend. $346 lesson. |
| Extreme RSI (< 20 for SHORTs, > 80 for LONGs) | Reversal imminent |
| Counter-trend on 4h with strength > 50 | Strong macro against you |
| Volume dying (ratio < 0.5 on both TFs) | No liquidity |
| Funding heavily against you (> 50% ann) | Fee drag kills profits |
| BTC macro headwind > 30 pts | Market-wide risk |
Architecture
┌──────────────────────────────────────────┐
│ Stage 0: BTC macro (2 API calls) │
├──────────────────────────────────────────┤
│ Stage 1: metaAndAssetCtxs → ~70 assets │
├──────────────────────────────────────────┤
│ Stage 2: SM + freshness → top 15-16 │
├──────────────────────────────────────────┤
│ Stage 3: parallel candle fetch + v5 │
│ hourly trend classification │
├──────────────────────────────────────────┤
│ Stage 4: cross-scan momentum │
├──────────────────────────────────────────┤
│ v5: Hard disqualifier check │
├──────────────────────────────────────────┤
│ Final: scored JSON → LLM formats report │
│ Total: ~5k LLM tokens │
└──────────────────────────────────────────┘Files
| File | Purpose |
|---|---|
scripts/opportunity-scan-v5.py | Python pipeline — fetches, scores, applies hourly gate |
scripts/opportunity-report.sh | Wrapper — runs pipeline + outputs LLM prompt |
scanner-config.json | User prefs: risk, leverage, macro modifiers |
scan-history.json | Auto-maintained: last 12 scans for cross-scan tracking |
active-positions.json | Current positions (conflict flags) |
Config Schema
See references/config-schema.md for the complete config with all options.
Output Format
See references/output-schema.md for the full output JSON schema.
Key fields per opportunity: asset, direction, leverage, finalScore, hourlyTrend, trendAligned, pillarScores, smartMoney, technicals, funding, risks, scoreDelta, scanStreak.
Disqualified assets reported separately with reason and wouldHaveScored for transparency.
Source Code
See references/source-code-v5.md for the v5 additions to the Python scanner (hourly trend classification, scoring changes, hard disqualifier logic).
Cron Setup
Run every 10-30 minutes (time-aware scheduling optional):
python3 scripts/opportunity-scan-v5.py | python3 scripts/opportunity-report.shMigration from v4
Drop-in replacement. All v5 features have sensible defaults:
- Hourly trend gate active by default (set
hourlyTrendGate: falseto disable) - Counter-trend hourly penalty is -30 points (configurable)
hourlyTrendandtrendAlignedadded to outputdisqualifiedAssetsshows what was filtered- SM trader count 400+ tier added automatically