btc-momentum-analyzer

BTC Kinetic Energy Theory Analyzer

Feature Overview

This Skill implements a MACD-based multi-timeframe nested kinetic energy theory analysis system, providing:

Multi-timeframe data acquisition: Obtain BTC K-line data for 8 timeframes from the OKX API
- 2-day (2d), 1-day (1d), 12-hour (12h), 6-hour (6h)
- 4-hour (4h), 2-hour (2h), 1-hour (1h), 30-minute (30m)
Technical indicator calculation:
- EMA26, EMA52 (short-term and medium-term trend lines)
- MACD(12, 26, 9): DIF (yellow line), DEA (white line), Histogram
Segment classification: Market state identification for each timeframe
- Upward segment (DEA > 0)
- Downward segment (DEA < 0)
- Transition period and breakout attempts

Kinetic energy theory analysis(see THEORY.md for details):
- Unit adjustment cycle: Determine which adjustment cycle is currently in progress
- Discrete regulation: Detect discrete kinetic energy adjustment patterns
- Continuous gap divergence: Divergence between price and histogram + gaps
- Yellow-white line divergence: Divergence detection between DIF and DEA
- Hidden signals: Hidden kinetic energy changes
Multi-timeframe linkage:
- Influence of higher timeframes on lower timeframes
- Multi-cycle resonance confirmation
- Recursive analysis of nested relationships
Trading signal generation:
- Buy/sell point identification (rules defined in THEORY.md)
- Stop-loss and take-profit suggestions
- Confidence assessment

Kinetic Energy Theory System

For complete theoretical definitions, please refer to THEORY.md, including:

Precise definitions of upward segments / downward segments
Identification method for unit adjustment cycles
Detection algorithm for discrete regulation
Judgment criteria for continuous gap divergence
Analysis rules for yellow-white line divergence
Trigger conditions for buy points / sell points
Analysis framework for timeframe linkage

Important: All trading parameters, thresholds, and rules are defined in THEORY.md; this Skill does not contain hardcoded trading logic.

Architecture description: Local Loop + Container Analysis

Data acquisition runs on the local machine (OKX API accessible), and analysis runs in the container/Claude.

本地机器（Mac）                     容器（Claude Code on the Web）
─────────────────                   ─────────────────────────────
local_loop.py                       btc-momentum-analyzer skill
  ↓ 每 6 小时                         ↓ 读取数据库
  OKX API 获取 K 线                   data/database/btc_database.json
  ↓ 计算 MACD/EMA                     ↓ 动能理论分析
  保存到 btc_database.json            生成多时间级别报告
  ↓ git commit & push
  (容器 git pull 拿到最新数据)

First-time initialization (run once locally)

cd /path/to/MACD
# 初始化数据库（下载历史数据）
python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --init

# 验证数据
python3 .claude/skills/btc-momentum-analyzer/scripts/database_manager.py --status

Start the local Loop (keep data up to date)

# 每 6 小时更新一次，同时 git push（推荐）
python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --git-push

# 只更新一次（手动触发）
python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --once --git-push

# 自定义间隔（如每 1 小时）
python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --interval 60 --git-push

# 更新所有 8 个时间级别
python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --all-timeframes --git-push

Set up scheduled tasks using launchd / cron (optional)

# 添加 crontab（每 6 小时运行一次）
crontab -e
# 添加这行：
0 */6 * * * cd /path/to/MACD && python3 .claude/skills/btc-momentum-analyzer/scripts/local_loop.py --once --git-push >> /tmp/btc_loop.log 2>&1

Usage Guide

One-click analysis (recommended)

Prerequisite: the local loop is already running and has pushed the latest data, and the container has executed git pull.

Claude will automatically execute the complete analysis process; you only need to ask:

Example Questions：

"Analyze the current momentum state of BTC"
"Which unit adjustment cycle is BTC currently in?"
"Detect BTC divergence across multiple timeframes"
"Is there a buy point for BTC? Give me a detailed analysis"

The Skill will automatically:

Fetch real-time data for 8 timeframes (OKX API)
Calculate all indicators (EMA26/52, MACD)
Perform nested momentum analysis
Generate a detailed report

Manually read the database inside the container

The container cannot access external APIs, so it directly reads the locally committed database:

# 查看数据库状态（最新时间戳、各时间级别 K 线数量）
python3 .claude/skills/btc-momentum-analyzer/scripts/database_manager.py --status

# 读取并打印指定时间级别的最新指标（快速核查）
python3 - <<'EOF'
import json
with open('data/database/btc_database.json') as f:
    db = json.load(f)
for tf in ['1d', '12h', '6h', '4h']:
    c = db['timeframes'][tf]['candles'][-1]
    print(f"{tf:5s}  close={c['close']:>10.2f}  DIF={c['dif']:>8.1f}  DEA={c['dea']:>8.1f}  Hist={c['histogram']:>8.1f}  [{c['datetime']}]")
EOF

Local manual full workflow (when the local machine has internet access)

# 获取数据
python3 .claude/skills/btc-momentum-analyzer/scripts/fetch_btc_data.py \
  --symbol BTC-USDT --timeframes 1d,12h,6h,4h --limit 200 \
  --output data/btc_latest.json

# 计算指标
python3 .claude/skills/btc-momentum-analyzer/scripts/calculate_indicators.py \
  data/btc_latest.json --ema-periods 26,52 --macd-params 12,26,9 \
  --output data/btc_indicators.json

Typical output examples

Full momentum analysis report

=========================
BTC 动能理论分析报告
分析时间: 2025-12-10 16:30:00 UTC
=========================

## 多时间级别嵌套分析

【2日线级别】
线段状态: 上涨线段
- DEA: +1250.3 (0轴上方，强势多头)
- DIF: +1580.7
- Histogram: +330.4 (持续扩张)
- 线段持续时间: 8 根 K 线
- EMA 排列: EMA26 (98,500) > EMA52 (96,200) ✓
- 单位调整周期: 第 2 个周期
- 周期间背离: 无
- 黄白线背离: 无（DIF 和 DEA 同向上升）

【1日线级别】
线段状态: 上涨线段
- DEA: +850.5 (0轴上方)
- DIF: +920.3
- Histogram: +69.8 (正柱，动能减弱)
- 线段持续时间: 12 根 K 线
- EMA 排列: EMA26 (98,200) > EMA52 (96,800) ✓
- 单位调整周期: 第 1 个周期
- 周期间背离: 无
- 黄白线背离: ⚠️ 轻微背离（价格新高，DIF 未新高）
- 与上级关系: 与 2日线 共振向上

【12小时级别】
线段状态: 上涨线段
- DEA: +420.8
- DIF: +380.2
- Histogram: -40.6 (负柱，动能转弱)
- 线段持续时间: 18 根 K 线
- EMA 排列: EMA26 (98,100) > EMA52 (97,200) ✓
- 单位调整周期: 第 2 个周期
- 周期间背离: ✓ 检测到背离（第1周期高点 vs 第2周期）
- 黄白线背离: ✓ 顶背离（DIF 下穿 DEA，死叉）
- 分立调控: 无
- 与上级关系: 1日线 上涨，但 12h 动能衰竭

【6小时级别】
线段状态: 过渡期（上涨线段后调整）
- DEA: +180.3
- DIF: +120.5
- Histogram: -59.8 (负柱，回调)
- 线段持续时间: 6 根 K 线（过渡期）
- EMA 排列: EMA26 (97,800) < EMA52 (97,850) ✗ (短期破位)
- 单位调整周期: N/A（处于过渡期）
- 分立调控: ✓ 检测到（第 3-5 根 K 线出现离散调整）
- 与上级关系: 12h 背离警告，6h 进入调整

【4小时级别】
线段状态: 过渡期
- DEA: +80.2
- DIF: +50.1
- Histogram: -30.1
- 线段持续时间: 10 根 K 线
- EMA 排列: EMA26 (97,600) < EMA52 (97,700) ✗
- 连续跳空背离: 无
- 黄白线背离: ✓ 死叉背离
- 与上级关系: 6h 调整延续至 4h

【2小时级别】
线段状态: 下跌线段（警告）
- DEA: -20.5 (已下穿 0 轴)
- DIF: -45.3
- Histogram: -24.8
- 线段持续时间: 4 根 K 线
- EMA 排列: EMA26 (97,400) < EMA52 (97,650) ✗
- 单位调整周期: 第 1 个周期（下跌段开始）
- 与上级关系: 4h 调整转为 2h 下跌

【1小时级别】
线段状态: 下跌线段
- DEA: -35.8
- DIF: -50.2
- Histogram: -14.4
- 线段持续时间: 8 根 K 线
- EMA 排列: EMA26 (97,350) < EMA52 (97,550) ✗
- 单位调整周期: 第 1 个周期
- 连续跳空背离: 无
- 黄白线背离: 无（同向下跌）
- 与上级关系: 2h 下跌延续至 1h

【30分钟级别】
线段状态: 下跌线段
- DEA: -45.2
- DIF: -55.8
- Histogram: -10.6
- 线段持续时间: 12 根 K 线
- EMA 排列: EMA26 (97,300) < EMA52 (97,500) ✗
- 单位调整周期: 第 1 个周期
- 隐形信号: ⚠️ 柱状图收敛（可能即将反转）
- 与上级关系: 1h 下跌延续

---

## 多时间级别联动总结

【大周期趋势】(2日线 - 1日线)
✓ 上涨线段确认
- 2日线 处于第 2 个单位调整周期，强势上涨
- 1日线 出现轻微黄白线背离，需警惕

【中周期调整】(12h - 6h - 4h)
⚠️ 调整期
- 12h 检测到周期间背离 + 黄白线死叉背离
- 6h 发现分立调控，进入过渡期
- 4h 延续调整，动能持续减弱

【小周期下跌】(2h - 1h - 30m)
✗ 短期下跌
- 2h 已确认下跌线段（DEA 下穿 0 轴）
- 1h, 30m 延续下跌，但 30m 出现柱状图收敛（隐形反转信号）

---

## 交易信号与建议

【当前市场状态】
多空分歧：大周期多头 vs 小周期空头

【买点分析】
❌ 不建议立即开多单
原因：
1. 12h 级别出现明显顶背离（价格新高，DIF 未新高）
2. 6h 检测到分立调控，市场处于调整期
3. 2h/1h 已确认下跌线段，短期趋势向下
4. 需等待小周期企稳后再考虑入场

【潜在买点触发条件】（参考 THEORY.md 规则）
1. 30m 级别 DEA 上穿 0 轴，确认反转
2. 1h 级别 EMA26 重新上穿 EMA52
3. 2h 级别调整结束，与 4h 恢复共振
4. 大周期 1日线、2日线 保持上涨线段

【卖点分析】
⚠️ 空单风险提示
原因：
1. 大周期（2日线、1日线）仍处于强势上涨线段
2. 当前下跌可能只是大周期的正常回调
3. 30m 柱状图收敛，可能即将反弹

【建议操作】
观望为主，等待以下情况之一：
1. 30m 反转信号确认 → 小仓位做多（顺大周期）
2. 2h DEA 继续下穿至 -100 以下 → 考虑短线空单
3. 1日线 DEA 下穿 0 轴 → 大周期转向，谨慎做空

【风险等级】: 中等
【置信度】: 60% (观望建议)

---

## 关键监控指标

1. **30分钟 Histogram**: 收敛后是否放量反转
2. **2小时 DEA**: 是否继续下探或企稳
3. **12小时 黄白线**: 背离后是否形成新的多头排列
4. **1日线 EMA26/EMA52**: 是否保持多头排列

=========================
报告生成时间: 2025-12-10 16:30:12 UTC
数据来源: OKX API
理论依据: THEORY.md (用户自定义动能理论)
=========================

Data source description

Data flow: local → container

Environment	Data acquisition	Analysis
Local machine (Mac)	`local_loop.py` Call OKX API ✅	Optional
Container (Claude Code on Web)	OKX/Binance API 403 blocked ❌	Read `btc_database.json` ✅

Correct workflow：

Run locally local_loop.py --git-push(keep the database up to date)
Run in container git pull(pull the latest database)
The container calls the btc-momentum-analyzer skill to perform analysis

OKX API (used locally)

Free public API, no Key required
Endpoint:https://www.okx.com/api/v5/market/candles
Rate limit: 20 req/2s
Supports all timeframes: 2D, 1D, 12H, 6H, 4H, 2H, 1H, 30m

Output format

Text report (default)

A structured multi-timeframe nested report, including:

Detailed analysis for each timeframe
Line segment state, unit cycle, divergence detection
Multi-timeframe linkage summary
Trading signals and action recommendations
Key monitoring indicators

JSON report

--format json

Machine-readable format, suitable for further processing or storage.

Simplified report

--detail simple

Contains only key information and trading recommendations, suitable for quick viewing.

Analysis depth control

Adjust the level of detail of the analysis as needed:

Full analysis (default)

python3 scripts/analyze_momentum.py data.json --detail full

Includes complete analysis of all 8 timeframes

Focused analysis

python3 scripts/analyze_momentum.py data.json --focus 1h,4h,1d

Analyze only the specified timeframe, but still consider the linkage relationships with higher and lower timeframes

Quick scan

python3 scripts/analyze_momentum.py data.json --mode quick

Output only the current line segment state and key signals, skipping detailed analysis

Error handling

The script has built-in multi-layer error handling:

API rate limiting: automatically wait and retry
Network errors: automatically retry 3 times, then fall back to cache after failure
Missing data: skip missing timeframes and log a warning
Calculation exceptions: return null values without interrupting the process
THEORY.md parsing errors: use default rules and warn the user

Performance optimization

Parallel data fetching: 8 timeframes requested in parallel to shorten wait time
Incremental updates: Only fetch newly added candlesticks to reduce data transfer
Smart caching: Dynamically set cache expiration time based on timeframe
Lazy loading: Calculate detailed indicators only when needed

Related files

THEORY.md - Complete definition of momentum theory (core, requires user input)
EXAMPLES.md - Usage examples and Q&A
MACD.pine - Referenced Pine Script strategy (for reference only)
README.md - Existing strategy document

Supported question types

This Skill is automatically activated when the following keywords are detected:

Momentum analysis：

"BTC momentum", "Bitcoin momentum status"
"Analyze BTC", "BTC market analysis"

Segments and cycles：

"Uptrend segment", "Downtrend segment", "segment status"
"unit adjustment cycle", "which cycle"
"inter-cycle divergence"

Divergence and signals：

"continuous gap divergence", "histogram divergence"
"yellow-white line divergence", "DIF DEA divergence"
"discrete regulation", "hidden signal"

Trading-related：

"buy point", "sell point", "trading signal"
"open long", "open short", "stop loss"

Timeframe：

"1 hour", "4 hour", "daily"
"multiple timeframes", "timeframe linkage"

Limitations and notes

THEORY.md must be complete：
- This Skill does not contain any hardcoded trading logic
- All rules, parameters, and thresholds are read from THEORY.md
- If THEORY.md is incomplete, analysis results may be inaccurate
Data latency：
- OKX API data may have a 1-2 second delay
- Data updates more slowly for large timeframes (2-day chart)
Indicator precision：
- MACD calculated in Python may differ slightly from TradingView
- The EMA initial value calculation method must be consistent with your theory
API limits：
- OKX: 20 requests/2 seconds
- 8 timeframes = 8 requests, completed in about 1 second
Risk notice：
- This Skill only provides analysis for reference and does not constitute investment advice
- Conflicting signals may appear across multiple timeframes and require comprehensive judgment

Maintenance and updates

Script location：.claude/skills/btc-momentum-analyzer/scripts/
Theory updates: Changes to THEORY.md take effect immediately, no restart required
Parameter adjustment: All parameters are configured in THEORY.md
Version control: Submit updates via git, team members sync automatically

Next steps

Complete THEORY.md：
- Define all momentum theory concepts
- Specify buy/sell point trigger conditions
- Configure all thresholds and parameters

Test data retrieval：

python3 scripts/fetch_btc_data.py --symbol BTC-USDT --timeframes 1h --limit 10

Verify indicator calculations：
- Compare Python calculation results with TradingView
- Ensure EMA26/52 and MACD values match
Full analysis test：
- Run the complete analysis workflow
- Check report format and content
- Adjust THEORY.md based on actual trading experience

Important Note: The core of this Skill is THEORY.md. Please be sure to completely fill in all rules and definitions in this file. The Skill will analyze strictly according to the theory you define and will not add any subjective judgment.