Binance TWAP Detector

A real-time desktop tool for spotting TWAP-style execution (Time-Weighted Average Price orders) in Binance spot and USDT-M futures trade feeds. It back-loads up to 100,000 historical aggregated trades for a symbol, then streams live trades over WebSocket and runs five complementary detectors in parallel to flag periodic, sustained, or round-number execution patterns — the kind a large player leaves behind when slicing a big order into many smaller ones.

Built with PyQt6. All parameters are live-adjustable from the GUI.

⚠️ Not financial advice. This is a market-microstructure analysis tool. Detections are statistical signals, not confirmed orders, and false positives are expected. Use it to investigate, not to trade blindly.

---

Detection modes

Each mode targets a different execution profile. They run concurrently and overlap intentionally — multiple modes firing on the same flow is a confidence signal.

Mode	Target	Method
A — strict	Exact/near-exact same-size, equally-spaced runs	Buckets trades by (size, side); finds runs whose median inter-trade interval is stable within a tolerance. Configurable size tolerance % and a min-interval floor to reject same-millisecond order-book sweeps.
B-fast	Sub-second / HFT-paced TWAPs (period 0.2–2 s)	30 s FFT, 50 ms buckets, on signed volume.
B-short	Medium TWAPs (period 1–20 s), fast retail bots	5 min FFT, 200 ms buckets.
B-long	Slow institutional TWAPs (period 2–200 s), multi-hour to multi-day	30 min FFT with persistence tracking — a peak must survive N consecutive passes to promote from candidate to confirmed. The primary detector for large whale activity.
C — sustained flow	One-sided pressure that isn't strictly periodic (large flow, small slices)	CVD slope + trade-size z-score over a rolling window vs. a longer baseline.
D — round-number bursts	Hand-rolled / third-party algos using round sizes	Clusters round-numbered trades by canonical size and side; requires a minimum same-size count and side concentration.

The B-mode FFT detectors apply a side-imbalance filter (won't attribute a side to balanced flow), a data-readiness gate (won't run an FFT until the window is sufficiently filled), and band-edge artifact rejection. Each mode has its own minimum-quantity filter to ignore dust trades.

---

Screenshots / UI

• Left panel — collapsible parameter groups, one per mode, all live-adjustable.
• Top-right — live trade feed (newest first, up to 50,000 rows). Trades that are members of a detection are highlighted and tagged by mode (e.g. B-long: SELL 5.00s @ SNR 8.3 (confirmed)). Confirmed B-long trades get a distinct gold highlight.
• Bottom-right — one detections table per mode, in tabs.
• Show flagged only toggle filters the feed to detection members.

---

Requirements

• Python 3.10+
• See requirements.txt: PyQt6, requests, numpy, websocket-client, python-dotenv

Install

git clone https://github.com/n-urs/binance-twap-detector.git
cd binance-twap-detector
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -r requirements.txt

Run

python twap_detector.py

Then in the GUI:

1. Enter a symbol (default ETHUSDT) and pick spot or futures.
2. Set Historical N (how many past aggTrades to back-load, up to 100,000).
3. Click Start. The tool fetches history, then connects the live feed.
4. Adjust any parameter on the fly. Use Pause/Resume to stop and resume the live feed without re-fetching history (it gap-fills the missed window on resume). Stop tears everything down.

API key (optional)

The detector uses public Binance endpoints only (aggTrades REST + the @aggTrade WebSocket), so no API key is required. If you want to provide one anyway, copy the template and fill it in:

cp config.env.example config.env

Use a read-only key with no withdrawal permissions. config.env is gitignored and must never be committed.

---

Notes & limitations

• Binance pushes aggTrade events on a ~100 ms server-side cadence, so periods below ~200 ms get smeared and are hard to detect cleanly (relevant to B-fast).
• FFT detectors operate on signed volume, so they react to net directional periodicity; balanced two-sided flow is filtered out.
• B-long needs its full window of data before it can produce a confirmed detection — expect to wait ~30+ minutes of live data on a fresh start.
• Detections are heuristics. Tune thresholds (SNR, persistence, min-interval, min-qty) per symbol and tempo.

Companion tool

benford.py in this repo is a separate, unrelated tool (Benford's-law digit analysis of trade sizes). It is not required by the TWAP detector.

License

MIT