memenet

Memecoin correlation network research toolkit.

A reproducible research framework for analyzing capital rotation patterns across Solana memecoins using correlation networks and lead-lag analysis.

Status: stable. v1.0.0 is the first stable release covering all five outputs (A through E), the eight-gate validation framework, the polling-based paper-trading loop, and the optional FastAPI webhook emitter. Schema and CLI changes from this point on will follow semantic versioning: minor bumps add features (Phase 6 / Phase 6.5 narrative detection coming as v1.1.0 / v1.2.0), major bumps break compatibility.

What it produces

memenet computes five research outputs over a configurable universe of Solana memecoins:

Output	What it is	Cadence
A Network State	cluster structure, internal correlation, capital concentration	hourly
B Hub Identification	which coins lead vs. lag within each cluster	daily
C Rotation Events	capital flowing from one cluster to another	event-driven
D Laggard Candidates	coins that historically follow a hub's moves	event-driven
E Regime State	self-diagnosis of the current market regime; gates A–D when degraded	hourly

All five outputs validate against pydantic v2 schemas (see memenet/schemas/) and are written to Parquet. An optional FastAPI emitter (Phase 5) forwards C, D, and E to a configured webhook.

Why regime gating matters

No quant system handles regime change perfectly. Output E is the system's self-diagnosis — when correlations break down, when the universe churns beyond historical norms, when the live distribution drifts from the training distribution, downstream signals are suppressed or attenuated rather than fired with stale assumptions. Goal: fail into "no signal" rather than "wrong signal" when operating outside the model's competence.

Quickstart

The toolkit is in Phase 2 (rolling networks + lead-lag MVP). It produces Output A (NetworkStateSnapshot), Output B (HubSnapshot), and the regime-indicator time series that feeds Output E in Phase 3.5. Outputs C and D land in Phase 3.

# 1. clone and install
git clone https://github.com/joerein-iu/MemeNet.git
cd MemeNet
uv sync

# 2. configure Birdeye
cp .env.example .env
# edit .env to set BIRDEYE_API_KEY

# 3. capture a point-in-time top-50 ranking
uv run memenet universe snapshot

# 4. plan the OHLCV backfill (no CU spent yet)
uv run memenet backfill

# 5. confirm and execute the backfill
uv run memenet backfill --confirm

# 6. compute the rolling correlation network + Granger lead-lag,
#    writing Output A (one per window step) and Output B (latest hubs)
uv run memenet network compute

# 7. emit Outputs C (rotation) and D (laggard) for the latest bar
uv run memenet signals run

# 8. run the walk-forward backtest with the 8 validation gates
uv run memenet backtest run

# 9. generate the network HTML report (Phase 2)
uv run memenet report generate

The HTML report lands at data/reports/network_<timestamp>.html by default. Open it in any browser.

Cost guardrails

• memenet backfill (without --confirm) prints the planned CU spend and exits without making any HTTP calls. Run this first to see the bill before paying it.
• The Birdeye client tracks cumulative CU per UTC day in data/_budget.json and refuses further requests once the --daily-cu-budget cap (default 30,000 CU/day) would be exceeded.
• The backfill planner consults previously-fetched data on disk and only fetches the missing tail; re-running the same backfill the next day is effectively free.

Verification

# unit tests (offline, no Birdeye access)
uv run pytest

# optional live Birdeye smoke test
uv run pytest -m live

Documentation

Full documentation: https://joerein-iu.github.io/MemeNet/

• Quickstart
• Methodology
• Output schemas — one page per output (A through E)

Scope

In scope (V1): Solana memecoins, top 50 by rolling 30-day market cap, 15-minute OHLCV bars, 90+ days of history for backtesting, optional 30+ days forward paper trading.

Out of scope (V1): EVM chains, sub-15-minute resolution, real-money trading (the toolkit emits signals; it does not place orders), on-chain wallet flow analysis (deferred to V2).

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow, code style, and how to run the test suite.

All contributors must follow the Code of Conduct.

License

MIT — see LICENSE.