name: opportunity-scanner
description: >-
4-stage funnel that screens all 500+ Aftermath perpetuals down to the top
trading opportunities. Scores setups 0-400 across smart money, market
structure, technicals, and funding. BTC macro filter, hourly trend gate
(counter-trend = hard skip), cross-scan momentum tracking. Near-zero LLM
tokens — all computation in Python.
Use when scanning for new trading opportunities on Aftermath Finance, evaluating
setups, or checking market conditions.
license: Apache-2.0
compatibility: >-
Requires python3, mcporter (configured with Senpi auth), and cron.
Aftermath perpetuals only. Uses ThreadPoolExecutor for parallel candle fetches.
metadata:
author: jason-goldberg
version: "5.0"
platform: senpi
exchange: aftermath

Opportunity Scanner v5

521 perps on Aftermath Finance. 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).

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:

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

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.sh

Migration from v4

Drop-in replacement. All v5 features have sensible defaults:
- Hourly trend gate active by default (set hourlyTrendGate: false to disable)
- Counter-trend hourly penalty is -30 points (configurable)
- hourlyTrend and trendAligned added to output
- disqualifiedAssets shows what was filtered
- SM trader count 400+ tier added automatically