token-movers

<!-- autoresearch: variation B — consolidated hub. Folds monitor-runners (GeckoTerminal on-chain runner scan w/ composite Runner Score) and token-report (verdict-first single-token deep report) behind a source + mode selector. Movers = broad market scan (CoinGecko winners/losers/trending OR GeckoTerminal runners); single-token = deep per-token report. Sharper output everywhere: enrich, score, flag pump risk, lead with the verdict. -->

> **${var}** — selects the scan. Two behavioral modes (`movers`, `single-token`) over two sources (`coingecko`, `geckoterminal`):
> - **empty** → movers scan on the default source (CoinGecko): top winners, losers, trending.
> - **`coingecko`** → same movers scan, CoinGecko source (explicit).
> - **`geckoterminal`** → movers scan on GeckoTerminal: on-chain "runners" across major chains.
> - **`geckoterminal:<chain>`** or a bare chain slug (`solana`, `eth`, `ethereum`, `base`, `bsc`, `arbitrum`, `polygon`, `optimism`, `avalanche`, `avax`) → GeckoTerminal runners scoped to that one chain.
> - **`category:<name>`** (e.g. `category:layer-2`, `category:meme`) — or a bare hyphen/space value like `layer-2` / `meme coins` → CoinGecko movers scoped to that category.
> - **`<contract>`** or **`<contract>:<chain>`** (e.g. `0xabc…`, `0xabc…:base`) → single-token deep report on that contract.
> - **`<SYMBOL>`** (e.g. `SOL`, `WIF`) → single-token deep report; resolve the symbol to its top contract first.
> - **`token`** / **`single-token`** → single-token deep report on the token configured in `memory/token-report.md`.
> - **`deep-dive:<symbol|contract>`** (e.g. `deep-dive:WIF`, `deep-dive:0xabc…:base`) → single-token deep report — the shape the Telegram force-reply sends. Strips the `deep-dive:` prefix and resolves the remainder exactly like a bare symbol/contract.
>
> Examples: `""` (global movers), `geckoterminal:base` (Base runners), `category:layer-2` (L2 movers), `0x4ed…:base` or `WIF` (single-token report).

## Preamble (every run)

1. Read `memory/MEMORY.md` for context.
2. Read the last 2 days of `memory/logs/` to avoid repeating the same movers/trending/runner names unless the move is materially different — **repeat runners across days are the real signal**. (The single-token branch reads the last **30 days** for its `TOKEN_REPORT_STATE:` delta lines — see that branch.)
3. **Parse `${var}` → `source` + `mode` (+ optional `token`/`chain`/`category`).** Trim whitespace; evaluate the rules top-to-bottom, first match wins (fully deterministic):

   0. **Force-reply intercept (Telegram deep-dive).** starts with `deep-dive:` → strip the prefix (`${var#deep-dive:}`) and treat the remainder EXACTLY as a single-token target, resolving it contract-or-symbol just like rule 8 (`token:`) does → **single-token**. Single-token branch. This is the shape the Telegram force-reply sends; it reuses all existing single-token logic (no separate handler, no confirmation — the single-token report IS the response).
   1. empty → **mode=movers, source=coingecko** (global). Go to **Movers branch**.
   2. `coingecko` (case-insensitive) → **movers / coingecko** (global). Movers branch.
   3. `geckoterminal` → **movers / geckoterminal** (all major networks). Movers branch.
   4. starts with `geckoterminal:` or `chain:` → **movers / geckoterminal**, `chain` = remainder. Movers branch.
   5. a known chain slug (`solana|eth|ethereum|base|bsc|arbitrum|polygon|optimism|avalanche|avax`) → **movers / geckoterminal**, `chain` = value. Movers branch. *(Preserves monitor-runners' `var`=chain behaviour. To report on a token that shares a chain name, e.g. the ETH token, use `token:eth` or its contract.)*
   6. starts with `category:` → **movers / coingecko**, `category` = remainder. Movers branch.
   7. equals `token` or `single-token` → **single-token**, token from `memory/token-report.md` config. Single-token branch.
   8. starts with `token:` → **single-token**, resolve remainder as contract-or-symbol. Single-token branch.
   9. matches a contract address — EVM `0x[0-9a-fA-F]{40}` or a Solana base58 address — optionally `:chain` → **single-token**, that contract. Single-token branch.
   10. contains a space or a hyphen and is not a contract (e.g. `layer-2`, `meme coins`) → **movers / coingecko**, `category` = value. Movers branch.
   11. otherwise (a bare word, a plausible ticker) → **single-token / geckoterminal**, resolve `symbol` = value to its top contract. Single-token branch.

---

# Mode: movers (default)

Produce an **actionable** movers report. Plain % change lists are noise — the value is in distinguishing real signal (on volume, from a credible cap tier / deep liquidity) from pump-and-dump noise. Run **exactly one** source path below, chosen in the preamble.

## Source: coingecko — market movers (winners / losers / trending)

### 1. Fetch data

Fetch market data and trending coins in parallel. Request multi-timeframe changes for context:

```bash
# CoinGecko auth: a free/Demo key (the common case) authenticates on
# api.coingecko.com with the `x-cg-demo-api-key` header — send it only when a key
# is set; without one the same public endpoint still works at a lower rate limit.
# (A paid Pro key instead uses pro-api.coingecko.com with `x-cg-pro-api-key`.)
# Pass the key through ./secretcurl's {ENV_NAME} placeholder so no `$SECRET` ever
# lands on the command line (a bare $COINGECKO_API_KEY is refused by the Bash
# permission analyzer). Build the header array only when the key is set, so the
# call stays keyless-public when it isn't.
CG_HDR=(); [ -n "${COINGECKO_API_KEY:+x}" ] && CG_HDR=(-H "x-cg-demo-api-key: {COINGECKO_API_KEY}")

# Top 250 coins by market cap with 1h, 24h, and 7d % change
./secretcurl -s "${CG_HDR[@]}" "https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=250&page=1&sparkline=false&price_change_percentage=1h,24h,7d"

# Trending searches (top coins people are searching for)
./secretcurl -s "${CG_HDR[@]}" "https://api.coingecko.com/ap