Metadata-Version: 2.4
Name: launchwatch-detector
Version: 0.1.0
Summary: Detect manufactured pump.fun pumps and single-block collapses from 1-minute candles
License: MIT
Project-URL: Homepage, https://launchwatch.dev
Project-URL: Research, https://launchwatch.dev/research.html
Project-URL: Feed, https://launchwatch.dev/data/orchestrated.json
Project-URL: Repository, https://gitlab.com/launchwatch/launchwatch-detector
Project-URL: GitHub, https://github.com/launchwatch/launchwatch-detector
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# launchwatch-detector

Detects **manufactured pumps** on pump.fun — tokens pushed up by bots in a nearly perfect straight line and then
emptied in a **single block** — from ordinary 1-minute candles. This is the detector behind
[launchwatch.dev](https://launchwatch.dev) (live dashboard, research note at `/research.html`, JSON feed at
`/data/orchestrated.json`).

Pure Python, no third-party dependencies, causal (no look-ahead), MIT licensed.

## Why

A recurring class of pump.fun tokens shows a fingerprint no organic market produces: nearly every 1-minute return is
positive, returns have almost no variance, the buy/sell count ratio is unnaturally stable, and log-price fits a straight line
with R² ≥ 0.98. In our observation (Sept 2026, ~900 tokens) close to 90% of them ended in a coordinated dump — dozens of wallets
selling in the same block, price −99% inside one second. No sell rule reacting to price can escape it, so the only useful
warning is *before* buying.

## Install / run

```bash
pip install -e .            # or just copy the launchwatch_detector/ directory
python -m launchwatch_detector examples/CRC_manufactured.csv examples/JJQ_organic_second_wave.csv
```

Output (abridged):

```json
{"manufactured": true, "detected_utc": "2026-09-04 21:30 UTC", "peak_gain_pct": 4.5,
 "collapse": {"utc": "2026-09-04 21:42 UTC", "drop_pct": -99.99, "sol_volume": 2781.3, "sells": 49},
 "minutes_to_collapse": 12.0, "file": "examples/CRC_manufactured.csv"}
{"manufactured": false, "file": "examples/JJQ_organic_second_wave.csv"}
```

## API

```python
from launchwatch_detector import early_signal, find_collapse, analyse

sig = early_signal(bars, window=8, min_r2=0.98)   # -> (minute_ms, close) or None, causal
col = find_collapse(bars, from_ms=sig[0])         # -> {"minute_ms", "drop_pct", "sol_volume", "sells"} or None
analyse(bars)                                     # both, plus peak gain and minutes-to-collapse
```

`bars` is a list of dicts with `minute_ms, open, high, low, close, sol_volume, buys, sells` (see `examples/*.csv`;
`buys`/`sells` are trade counts in the minute). Any source of 1-minute candles with trade counts works — the reference
deployment builds them from a pump.fun trade stream.

## Definitions (same as the live site)

- **manufactured**: within the last `window` (8) bars — share of positive 1-min returns ≥ 0.9, coefficient of variation of
  returns < 0.5, standard deviation of buy/sell ratio < 0.15, R² of log-price vs time ≥ 0.98, total move > +2%.
- **collapse**: a 1-minute bar whose low is below 40% of the previous close (single-block dump), searched up to 6 h after detection.

## Limitations

- Needs ≥ 8 minutes of the pattern; buyers in the first minutes are not warned in time.
- ~10–15% of detections fade instead of collapsing. Every detection is manufactured; not every one is dumped.
- Tuned on pump.fun bonding-curve tokens; thresholds may need adjustment for other venues.

## Examples

`examples/` contains three real 1-minute series derived from public on-chain data:
`CRC_manufactured.csv` and `ARROW_manufactured.csv` (both collapsed by 44 wallets in one block) and
`JJQ_organic_second_wave.csv` (an organic token, for contrast).

## Source

Canonical repository: https://github.com/launchwatch/launchwatch-detector · mirror: https://gitlab.com/launchwatch/launchwatch-detector. Releases on PyPI as `launchwatch-detector`.

## License

MIT — see `LICENSE`.

---

## 日本語

pump.fun で繰り返し現れる「演出型パンプ」（ボットが価格をほぼ完全な直線で吊り上げ、同一ブロックでプールを空にする型）を、
普通の 1 分足から検出する純 Python ライブラリです。[launchwatch.dev](https://launchwatch.dev) の検出器そのもので、依存なし・
因果的（後出しなし）・MIT ライセンス。使い方は上の英語の節と同じです。判定の定義（8 本の窓、R² ≥ 0.98、消滅＝安値が直前終値の 40% 未満）は
サイトと同一です。検出には 8 分以上のパターンが必要で、検出のうち 1〜2 割は消滅せずに減衰します。
