Skip to content

Quickstart

End-to-end Phase 1 walkthrough: clone, install, capture a universe, backfill OHLCV, compute the correlation network, and generate an HTML report. The full sequence completes in under five minutes once the Birdeye API key is set.

Requirements

  • Python 3.11+
  • uv for dependency management
  • Git
  • A Birdeye API key — Lite tier ($39/mo) covers Phase 1 backfills

Install

git clone https://github.com/joerein-iu/MemeNet.git
cd MemeNet
uv sync

uv sync installs the runtime and development dependencies into a local .venv/. No global installs.

Configure Birdeye

cp .env.example .env
# edit .env to set BIRDEYE_API_KEY

The key is read by pydantic-settings at runtime; no plaintext key ever lives in code or config files.

Capture a universe snapshot

uv run memenet universe snapshot

This pages the Birdeye token list, drops stablecoins / wrapped majors / SOL liquid-staking derivatives, and persists the top-50 memecoin ranking under data/universe/. Costs ~30 CU.

Plan the backfill (no CU spent)

uv run memenet backfill

Prints the per-coin fetch windows, total request count, and total CU spend the backfill would consume. No HTTP calls are made until you pass --confirm.

Run the backfill

uv run memenet backfill --confirm

Fetches 90 days of 15-minute OHLCV for every coin in the universe. Default daily CU budget is 30,000; a fresh 90-day backfill at 50 coins runs roughly 2,250 CU.

Compute the rolling correlation network

uv run memenet network compute

Drives the rolling pipeline: a 24-hour correlation matrix is built every hour over the backfilled OHLCV, Louvain is run on each window, and Granger causality with Benjamini-Hochberg correction picks out the statistically significant lead-lag pairs from the most recent window. Outputs:

  • data/network_state/snapshot=<ts>.json — one Output A per window step.
  • data/hubs/snapshot=<ts>.json — Output B for the latest window.
  • data/regime_indicators/series.parquet — the four indicator series (mean correlation, stability, cluster persistence, universe churn).

Pass --window-hours / --step-hours to change the cadence; --correlation-threshold overrides the edge threshold from the config.

Generate the signals (Outputs C and D)

uv run memenet signals run

Re-runs the rolling pipeline, builds the laggard detector from the Granger-derived follower map, and emits any LaggardAlerts (Output D) fired at the latest bar plus any RotationEvents (Output C) implied by the change between the two most recent snapshots. Alerts land under data/signals/{laggard,rotation}/<alert_id>.json.

Run the walk-forward backtest

uv run memenet backtest run

Splits the on-disk OHLCV into train / validate / test (default 30/30/30 days), trains the laggard detector on the train window, replays the test window through the engine with no-look-ahead enforced, simulates fills through the configurable cost model, and evaluates the 8 validation gates. Output: an HTML report at data/reports/backtest_laggard_<timestamp>.html with the gate scorecard, headline metrics (Sharpe + bootstrap 95% CI), equity curve, and the per-trade ledger.

Common flags:

  • --slippage-pct 0.03 for the 3% stress run (Gate G3)
  • --breakout-pct 0.06 to require a 6% hub move
  • --hold-minutes 30 to test a tighter exit policy

Render the HTML report

uv run memenet report generate

Re-runs the rolling pipeline (with shorter defaults — 14 days, 6h step — so the report builds in well under a minute) and writes a self-contained interactive HTML to data/reports/network_rolling_<timestamp>.html. The report includes:

  • The latest correlation network as an interactive plotly graph.
  • The hub table with BH-corrected p-values per follower (Output B).
  • Four time-series charts: mean correlation, stability, cluster persistence, universe churn.
  • The Granger pair counts in the page header (how many tested vs how many survived the BH correction).

Pass --static for the Phase 1 single-snapshot report instead.

Verify

uv run pytest

131 unit tests, all offline. The optional pytest -m live runs the Birdeye smoke test against your real API key.

What's next

Phase 3 implements the laggard (Output D) and rotation (Output C) signals on top of Phase 2's lead-lag graph, plus the walk-forward backtest engine and the eight validation gates. Phase 3.5 adds the calibrated confidence multiplier and circuit breakers that gate every signal through Output E. Watch the changelog for releases.