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

opportunity-scanner

NPX Install

Tags

SKILL.md Content