# @5409/fvg Delta Crypto Core

> FVG-Delta Crypto Core v7.0

- Skill: `starchild-ai-agent/5409-fvg-delta-crypto-core` (Agent Skill)
- Install (CLI): `npx skillmds@latest add starchild-ai-agent/5409-fvg-delta-crypto-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starchild-ai-agent/5409-fvg-delta-crypto-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: starchild-ai-agent (https://skillmd.com/u/starchild-ai-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starchild-ai-agent/5409-fvg-delta-crypto-core

---


# FVG-Delta Crypto Core v7.0

A production FastAPI service that scans MEXC UST-M perpetual futures on **closed
15-minute candles**, runs a strict lock-forward Smart-Money-Concept (SMC) staged
state machine, draws annotated chart screenshots, sends per-trade Telegram alerts,
and serves a live dashboard with an in-memory Trade History. Everything lives in
`assets/app.py`; the rest is config, docs, and entrypoints.

## The strategy — five locked stages
Each stage is searched ONCE and its bar index is stored; stages only advance, hard-
invalidate, or expire. Never skip or regress.

0. **Zone** — a clean impulse leaves an FVG. A valid impulse is a tight burst of
   **≥3 consecutive same-direction candles** that *creates* the FVG and never
   re-enters it (rejects staggered/cluttered legs).
1. **First liquidity + BoS** — the first retracement (one candle closing past the
   immediate impulse candle's open, OR a 2+ candle pullback) sets the liquidity
   line. Hard rules: a **gap** must exist between that line and the FVG (it may
   never rest on the FVG edge), and **BoS sits above liquidity for longs / below
   for shorts**. A BoS *close* through the impulse wick extreme confirms Stage 1.
2. **Sweep** — price breaks and CLOSES past the first liquidity, into the gap.
3. **FVG interaction** — price reaches the FVG. A wick THROUGH that closes back
   inside is still valid; only a CLOSE beyond the FVG invalidates.
4. **Verified entry** — an opposite-direction confirmation candle (strong body or
   long-wick rejection + opposite close). SL anchors beyond the interaction wick
   (breathing room), TP1 = midpoint, TP2 = max(3R, resting liquidity).

## Automatic leverage
`leverage = round_to_5(LEV_TARGET_SL_LOSS_PCT / stop_distance_%)`, clamped to
`[LEV_MIN, LEV_MAX]` (20–50) and the pair's exchange max. Default target = 50% of
margin at SL. Wider stop → lower leverage. TP is uncapped (rides TP1/TP2).

## Per-trade Telegram lifecycle
A confirmed Stage-4 trade emits its own alert chain, each fired once on candle
close: **Entry Confirmed → TP1 Hit** (close 50% + move SL to break-even) **→ SL Hit
/ TP2 Hit / Break-Even Close**. Only terminal Stage-4 outcomes reach Trade History;
Stage 1–3 invalidations are removed beforehand.

## Universe (why majors show up)
`load_symbols` ranks the MEXC perp universe by 24h quote turnover (`amount24`) via
`/contract/ticker` and keeps the top `UNIVERSE_TOP_N`, so BTC/ETH/SOL/XRP lead.
Tokenized equities/commodities/indices are excluded (`UNIVERSE_EXCLUDE` + the
`UNIVERSE_EXCLUDE_CONTAINS="STOCK"` substring rule for the xStock family).

## Run it
```bash
# 1. credentials (never paste keys in chat — use the secure env flow)
cp .env.example .env   # set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID
# 2. local
bash assets/run_one_shot.sh
# 3. docker / Hugging Face Spaces (Docker SDK)
docker build -t fvg-delta assets/ && docker run -p 7860:7860 --env-file .env fvg-delta
```
Endpoints: `/` (dashboard), `/trades` (Trade History dashboard), `/health`,
`/api/state`, `/api/trades`, `/api/market`, `/api/test_telegram`,
`/api/chart.png?symbol=BTC_USDT`, `/api/trade_chart.png`.
Without Telegram creds the UI still runs; alerts are skipped and logged.

Persistence: set `PERSIST_DIR` (default `/data`, the Hugging Face mounted disk). Trade
History is stored in SQLite (`fvgdelta.db`) and live state in `state.json`; both are
created if absent, read on boot, and fall back to a local `./data` dir if `/data` is
not writable.

## Tuning & gotchas
- All knobs are env vars with production-safe defaults — see
  `assets/VARIABLES_AND_SECRETS_GUIDE.txt` (§14 covers every v6.0 variable).
- Decisions use `bars[-2]` (last CLOSED candle); `bars[-1]` (forming) is never used.
- Cron/weekly times are UTC. Dashboard times render in the viewer's browser zone;
  Telegram uses its own received time (no embedded timezone).
- MEXC sends brotli — keep the `brotli` package installed and send
  `Accept-Encoding: gzip, deflate`.
- Prefer adding new tunables to `CFG` (env override + default) over hard-coding, and
  keep stage strictness intact (sequential, no skipping, close-through = invalidation).

## v7.0 highlights
- **Settings page** (`/settings`, gear icon in the header) is the single source of
  config — including the Telegram token + chat I.D (the Space is private). Values are
  written to `settings.json` on the persistent disk and hot-applied with no restart
  (precedence: settings.json > env/secret > default). Backed by `settings_schema.json`
  (human-readable labels, presets, per-field help) and served by `settings.js`.
- **Telegram delivery fixed**: the bot now uses its own IPv4-pinned aiohttp session
  (HF containers often have broken IPv6, which made the old shared session hang →
  "request timed out") plus a stdlib `urllib` fallback transport.
- **Stage 5 only** gets Telegram + browser alerts (Stage 3 is dashboard-only now).
- **Browser alert sound** (`/alert-sound`, a synthesised WAV cached to disk), toggle in
  Settings.
- **TTL**: Stage 1 & 2 live 24h; Stages 3/4/5 never expire on age.

## Files (all flat — no folders)
`app.py` (engine), `trades.html` (Trade History page), `settings.html` + `settings.js`
+ `settings_schema.json` (Settings page), `market.js` (market rail + notifications +
Telegram test + alert sound), `Dockerfile`, `start.sh`, `run_one_shot.sh`,
`preflight_check.py`, `requirements.txt`, `AGENT.md` (maintainer guide + changelog),
`STRATEGY_DETAILED_SPEC.txt`, `VARIABLES_AND_SECRETS_GUIDE.txt`, `README.md`.
Read `AGENT.md` before editing `app.py`.