btc-volume-jump-analyzer

BTC Volume Contraction/Expansion / Histogram Gap Analyzer

Feature Overview

This Skill is a jump.pine(MACD histogram gap strategy) Python port + enhancement, focused on volume contraction/expansion techniques, by default analyzing BTC 6-hour candles。

It provides two layers of analysis; combining the two gives the complete "volume contraction/expansion" assessment:

1. Histogram gaps (original jump.pine logic, per-candle state machine)

   • Uptrend segment (DEA > 0) + EMA21 > EMA52 + price standing above EMA52 − stop-loss offset
   • Detect histogram pullback(green bars shrinking / red bars expanding) followed by another gap for a trend-following entry
   • Near the zero line (0 < DEA ≤ threshold) red-bar contraction bullish candle entry
   • Gap trailing stop(move up to previous candle open − stop-loss offset), close position on stop-loss breach / leaving the uptrend segment

2. Real volume contraction / expansion

   • Volume ratio = current volume / average volume (MA, default 20)
   • Expansion (volume ratio ≥ 1.5) / contraction (volume ratio ≤ 0.7) / constant
   • Combined with candle direction: bullish expansion (strong with trend), contraction pullback (healthy retracement, prerequisite for gap), bearish expansion (distribution warning)

jump.pine's core idea:In an uptrend segment, an expansion gap after a contraction pullback is a trend-following add point. This Skill quantifies both dimensions: "histogram gaps" and "real volume scaling".

Data Accuracy

• DIF / DEA / Histogram Directly uses the precise values calculated in the database by IndicatorCalculator (MACD 12/26/9), without secondary approximation.
• EMA21 / EMA52 Recalculated by the script from closing prices using the EMA formula consistent with the indicator library (first value SMA, multiplier 2/(N+1)) (jump.pine uses EMA21/52, while the database stores EMA26/52 by default).
• K-line OHLCV is used as-is, without rounding or interpolation.

Usage

One-click analysis (recommended)

Just ask directly, for example:

• "Analyze BTC 6-hour with volume contraction/expansion"
• "Does BTC 6h currently have a gap entry signal?"
• "Is BTC 6h in volume expansion or contraction?"

Claude will run the script and interpret the results.

Command line

# 默认：读取仓库数据库 data/database/btc_database.json，分析 6h
python3 .claude/skills/btc-volume-jump-analyzer/scripts/analyze_volume_jump.py --timeframe 6h

# 指定数据文件（带指标的 JSON）
python3 .claude/skills/btc-volume-jump-analyzer/scripts/analyze_volume_jump.py \
  --input data/btc_indicators.json --timeframe 6h

# JSON 输出 + 写文件
python3 .claude/skills/btc-volume-jump-analyzer/scripts/analyze_volume_jump.py \
  --timeframe 6h --format json --output data/analysis_reports/6h_volume_jump.json

Parameters (defaults aligned with jump.pine)

Parameter	Default	Description
--timeframe	6h	Timeframe
--stop-loss-offset	300	Stop-loss offset (open − offset), from jump.pine
--zero-axis-threshold	300	DEA threshold near the zero line
--vol-period	20	Average volume period
--expand-threshold	1.5	Volume expansion ratio threshold
--shrink-threshold	0.7	Volume contraction ratio threshold
--recent	8	Number of most recent candles shown in detail
--input	Database	Custom JSON with indicators
--format	text	text or json

Note:stop-loss-offset=300 is the fixed point offset designed for BTC in jump.pine. It can be adjusted as needed under different price/ timeframe levels (for example, 6h has greater volatility and can be appropriately widened).

Data Sources / Updates

The script reads the repository database data/database/btc_database.json. To analyze the latest market conditions, first incrementally update the database:

python3 .claude/skills/btc-momentum-analyzer/scripts/database_manager.py --update --timeframes 6h

Real-time data comes from the OKX / Binance public APIs. If the runtime environment's network policy blocks the exchange APIs, the script will fall back to the existing data in the database and continue calculating as usual (the results correspond to the last K-line time in the database).

Output Description

• Current K-line / MACD: precise OHLC, EMA21/52, DIF/DEA/Histogram, segment direction
• Volume contraction/expansion: volume ratio, average volume, status, volume-price combination
• Gap strategy status: current position, stop-loss level,whether this K-line triggers entry/exit, most recent event
• Recent K-line details: bar-by-bar volume ratio/status/MACD quick reference table

Relationship with Other Skills

• btc-momentum-analyzer: complete momentum theory (segments/unit cycles/divergence), used for judging the overall trend direction.
• btc-6h-scheduled: every 6 hours, combines this Skill with momentum theory to produce a comprehensive report for BTC 6h.

Limitations

• Long-only (consistent with jump.pine, a trend-following strategy for upward segments).
• The output is mechanical signals + precise data; the final trading decision needs to combine momentum theory and multi-timeframe coordination.
• Not investment advice.