opportunity-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Opportunity Scanner v5

机会扫描器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.

Hyperliquid上共有521种永续合约。如果为所有合约抓取K线+计算技术指标会消耗50万以上的token。本扫描器会筛选所有标的，仅在出现真实交易机会时才消耗token。

所有计算均通过Python实现，LLM token消耗几乎为零。

The 4-Stage Funnel

四阶段漏斗

Stage 0: BTC Macro Context

阶段0：BTC宏观背景

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

数据源：BTC 4小时+1小时K线（2次API调用）。输出：

btc_trend

（strong_down/down/neutral/up/strong_up）以及应用于所有最终评分的

macro_modifier

（宏观调整系数）。可通过

scanner-config.json

进行配置。

Stage 1: Bulk Screen (~0 LLM tokens)

阶段1：批量筛选（~0 LLM token消耗）

Source: Single API call —

metaAndAssetCtxs

. Filter: 24h volume > $500K (configurable). Output: ~70 assets that pass minimum liquidity.

数据源：单次API调用 ——

metaAndAssetCtxs

。过滤条件：24小时交易量 > 50万美元（可配置）。输出：约70个满足最低流动性要求的资产。

Stage 2: Smart Money + Freshness Overlay (~0 LLM tokens)

阶段2：聪明资金+新鲜度叠加筛选（~0 LLM token消耗）

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.

数据源：

leaderboard_get_markets

leaderboard_get_top

（limit=100）。每个资产对应两个条目（多头+空头）—— 保留占主导的一侧。新鲜度指标：

avgAtPeak

（>85% = 有效，<50% = 失效）、

nearPeakPct

。过滤条件：按快速评分选出前15-16个资产，强制包含排名前8的聪明资金标的。

Stage 3: Deep Dive — Multi-Timeframe (~0 LLM tokens)

阶段3：深度分析 —— 多时间维度（~0 LLM token消耗）

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.

通过ThreadPoolExecutor并行抓取K线（~~20秒完成，串行抓取需~~60秒）。

时间周期	统计区间	K线数量	用途
4小时	7天	~42	宏观趋势（EMA 5/13交叉）
1小时	24小时	~24	小时级趋势结构 + RSI、交易量、支撑位/阻力位、形态
15分钟	6小时	~24	入场判断：RSI、形态、动量、量价背离

v5版本新增：小时级趋势分类 —— 分析1小时数据中的高低点摆动，将趋势分类为上涨/下跌/震荡。算法详情请查看references/hourly-trend.md。

这是所有交易决策的第一闸门。绝对不要在

hourlyTrend: "DOWN"

时开多，也不要在

hourlyTrend: "UP"

时开空。

各时间周期错误恢复机制：如果15分钟K线抓取失败，会继续使用4小时+1小时数据进行分析。

Stage 4: Cross-Scan Momentum

阶段4：跨扫描动量分析

Saves results to

scan-history.json

. Computes

scoreDelta

(change from last scan) and

scanStreak

(consecutive appearances).

将结果保存到

scan-history.json

，计算

scoreDelta

（较上一次扫描的评分变化）和

scanStreak

（连续出现在结果中的次数）。

4-Pillar Scoring (25% each, 0-400 total)

四大维度评分（各占25%，总分0-400）

See references/scoring.md for the complete point breakdowns.

完整评分细则请查看references/scoring.md。

Pillar 1: Smart Money (25%)

维度1：聪明资金（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.

包含盈利贡献等级、交易者数量（v5新增：400人以上+30分）、增速、新鲜度。交易者数量可区分真实信号和噪音：130个交易者给出的4级信心常会导致反复洗盘，而400个以上交易者给出的4级信心通常是真实信号。

Pillar 2: Market Structure (25%)

维度2：市场结构（25%）

Volume, volume surge, open interest, OI/volume ratio.

包含交易量、交易量激增、持仓量、持仓量/交易量比率。

Pillar 3: Technicals (25%)

维度3：技术面（25%）

4h trend alignment, 1h trend structure (v5), RSI multi-TF convergence, volume confirmation, candlestick patterns, momentum. Counter-trend on hourly: -30 points (v5).

包含4小时趋势对齐度、1小时趋势结构（v5新增）、多周期RSI共振、成交量确认、K线形态、动量。小时级反向趋势：-30分（v5新增）。

Pillar 4: Funding (25%)

维度4：资金费率（25%）

Neutral funding is best (+40). Favorable extreme is strong (+35). Unfavorable extreme hurts (-20).

中性资金费率最优（+40分），有利的极端费率次之（+35分），不利的极端费率会扣分（-20分）。

BTC Macro Modifier

BTC宏观调整系数

Applied to final scores. Penalizes alt LONGs during BTC downtrend, boosts SHORTs (and vice versa). All modifiers configurable.

应用于最终评分，BTC下跌趋势中会惩罚山寨币多头、提升空头评分（反之亦然），所有调整系数均可配置。

Hard Disqualifiers (v5)

硬性淘汰条件（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

满足以下条件的机会会被完全跳过，而非仅扣分：

条件	逻辑依据
小时级反向趋势	1分钟反弹带来的聪明资金信心不足以抵消2周的下跌趋势，为此我们付出过346美元的学费。
极端RSI（空头标的<20，多头标的>80）	即将出现反转
4小时反向趋势且强度>50	宏观趋势与交易方向严重相悖
交易量萎缩（两个时间周期的交易量比率均<0.5）	流动性不足
资金费率严重不利（年化>50%）	手续费损耗会吞噬利润
BTC宏观逆风扣分>30	全市场风险

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                  │
└──────────────────────────────────────────┘

┌──────────────────────────────────────────┐
│  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)

文件名	用途
`scripts/opportunity-scan-v5.py`	Python流水线 —— 抓取数据、评分、应用小时级闸门
`scripts/opportunity-report.sh`	封装脚本 —— 运行流水线并输出LLM提示词
`scanner-config.json`	用户偏好设置：风险、杠杆、宏观调整系数
`scan-history.json`	自动维护：最近12次扫描结果，用于跨扫描跟踪
`active-positions.json`	当前持仓（冲突标记）

Config Schema

配置结构

See references/config-schema.md for the complete config with all options.

完整配置及所有选项说明请查看references/config-schema.md。

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.

完整输出JSON结构请查看references/output-schema.md。

每个机会的关键字段：

asset

、

direction

、

leverage

、

finalScore

、

hourlyTrend

、

trendAligned

、

pillarScores

、

smartMoney

、

technicals

、

funding

、

risks

、

scoreDelta

、

scanStreak

。

被淘汰的资产会单独列出，附带

reason

（淘汰原因）和

wouldHaveScored

（本应获得的评分），保证透明性。

Source Code

源代码

See references/source-code-v5.md for the v5 additions to the Python scanner (hourly trend classification, scoring changes, hard disqualifier logic).

Python扫描器的v5新增功能（小时级趋势分类、评分调整、硬性淘汰逻辑）请查看references/source-code-v5.md。

Cron Setup

定时任务配置

Run every 10-30 minutes (time-aware scheduling optional):

python3 scripts/opportunity-scan-v5.py | python3 scripts/opportunity-report.sh

每10-30分钟运行一次（可选择时间感知调度）：

python3 scripts/opportunity-scan-v5.py | python3 scripts/opportunity-report.sh

Migration from v4

从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

可直接替换使用，所有v5功能均有合理默认值：

小时级趋势闸门默认开启（设置
```
hourlyTrendGate: false
```
可关闭）
小时级反向趋势惩罚为-30分（可配置）
输出新增
```
hourlyTrend
```
和
```
trendAligned
```
字段
```
disqualifiedAssets
```
字段展示被过滤的标的
自动新增聪明资金交易者数量400+的评分等级