Price Alert

${var} — Optional. Pass one or more target_price levels (comma-separated USD numbers, scientific notation allowed) to fire a one-time alert when the price crosses any of them. Empty = only ATH and sharp-move gates run. Pass dry-run to skip notify (state still updates). Pass set-target:<price> — the shape the Telegram force-reply sends (step 7) — to register a target and get a one-line confirmation.

Today is ${today}. The scheduled digests (digest, token-movers, ...) run at fixed hours. None of them tell the operator "the price just hit a new high" or "the token moved 28% in the last hour" — both are events that warrant attention the moment they happen, not 14 hours later in a daily digest. This skill closes that window.

Why this exists

Scheduled daily digests are calm summaries. Real moves need real-time signal. Three classes of move are worth a same-day ping:

• New all-time high. The single most narrative-shaping price event a token can have. Worth marking on the timeline regardless of size.
• Sharp 1h moves (±20%). Either a buyer wave or a liquidation cascade — both change what the operator does next (post about it, watch for follow-through, check the chart).
• Operator-set target crossings. The operator may want to know when price clears $X (often a personal stretch goal or a level tied to a tweet/launch). One alert per target per direction.

Everything else is noise not worth a same-day ping.

Config

Reads:

• memory/MEMORY.md "Tracked Token" section — the tracked token's contract/chain. If absent, exit silently.
• memory/topics/price-alert-state.json — last-known ATH, last-alert timestamps per event type, target-crossing history. Created with defaults on first run.

Writes:

• memory/topics/price-alert-state.json — updated state every run.
• memory/logs/${today}.md — one log block per run, even on OK.
• Notification via ./notify — only when a gate fires.

No new secrets. Uses keyless DexScreener; falls back to WebFetch when a public curl GET is flaky (there is no network sandbox).

State schema

{
  "contract": "0xbf8e8f0e8866a7052f948c16508644347c57aba3",
  "chain": "base",
  "ath": {
    "price_usd": 0.000003757,
    "observed_at": "2026-05-10T19:00:00Z",
    "announced_at": "2026-05-10T19:30:00Z"
  },
  "last_alerts": {
    "ath": "2026-05-10T19:30:00Z",
    "sharp_move": null,
    "target_hit": null
  },
  "targets": {
    "0.000005": {
      "side": "above",
      "first_seen_below_at": "2026-05-11T08:00:00Z",
      "hit_at": null,
      "announced_at": null
    }
  }
}

Key invariants:

• ath.price_usd only ever monotonically increases. If a run sees a lower price than the stored ATH, leave the ATH alone.
• last_alerts.* powers the 4h dedup window. Each gate has its own clock.
• targets.${price}.side is above if current_price < target when the target was first observed (operator is waiting for the price to climb to it), and below otherwise. Set once, never flipped.
• targets.${price}.hit_at is set the run the cross happens. announced_at is set the run the notification fires. They differ only if the run lands inside a dedup window — but target alerts never re-fire, so hit_at == announced_at in practice.

Steps

1. Parse var

• If ${var} starts with set-target: → set FROM_REPLY=1, MODE=execute. Strip the set-target: prefix (${var#set-target:}); the remainder is the target(s) list, parsed exactly like the comma-split below. This is the shape scripts/telegram-route.sh sends when the operator replies to the step-7 force-reply prompt. The run proceeds normally (register the target, don't fire on first observation) and closes the loop with a confirmation in step 7.
• Else if ${var} matches ^dry-run → MODE=dry-run. Strip the prefix; remainder (if any) is treated as targets.
• Otherwise MODE=execute.
• Split the remainder on , (commas) and strip whitespace.
• For each token: if it parses as a positive float (scientific notation OK, e.g. 5e-6), include it. Reject zero / negative / non-numeric tokens and log PRICE_ALERT_BAD_TARGET: ${token} — continue with the surviving targets.
• If after filtering the remainder was non-empty but yielded zero valid targets → log PRICE_ALERT_BAD_VAR: ${var} and exit. Normally no notify — but if FROM_REPLY=1, first close the loop with ./notify "Couldn't read \"${var#set-target:}\" as a price. Reply with a number like 0.000005." (a force-reply always deserves an acknowledgement).
• If the remainder was empty, TARGETS=() is fine — ATH and sharp-move gates still run.

2. Resolve tracked token

mkdir -p memory/topics
[ -f memory/topics/price-alert-state.json ] || cat > memory/topics/price-alert-state.json <<'EOF'
{"contract":null,"chain":null,"ath":null,"last_alerts":{"ath":null,"sharp_move":null,"target_hit":null},"targets":{}}
EOF

Parse the "Tracked Token" table in memory/MEMORY.md. Pull CONTRACT (column 2 of the first data row) and CHAIN (column 3, lowercased). If the section is missing, the table is empty, or the contract field doesn't match ^0x[0-9a-fA-F]{40}$ → log PRICE_ALERT_NO_TOKEN and exit (no notify, no state write).

If the state file's contract is set and differs from the resolved contract → log PRICE_ALERT_TOKEN_CHANGED and reset the state file to defaults with the new contract/chain. ATH starts over with the new token.

3. Fetch current price (DexScreener primary)

RESP=$(curl -fsS "https://api.dexscreener.com/latest/dex/tokens/${CONTRACT}" 2>/dev/null || echo "")

If the response is empty, falsy, or jq can't parse it → fall back to WebFetch on the same URL with prompt "Return the raw JSON body verbatim." and try again. If both paths fail → log PRICE_ALERT_FETCH_FAIL and exit with status ERROR (no notify, no state mutation beyond touching last_run_at).

From the parsed JSON:

• Filter .pairs[] to entries where .chainId == "${CHAIN}".
• Of those, pick the entry with the highest .liquidity.usd — call this the deepest pool. If no pair matches the chain, fall back to the highest-liquidity pair across all chains and mark chain=fallback in the log.
• Extract: CURRENT_PRICE=.priceUsd (float), H1_CHANGE_PCT=.priceChange.h1 (float, may be missing → treat as 0), H24_CHANGE_PCT=.priceChange.h24 (float, may be missing → treat as 0), POOL_URL=.url.

If CURRENT_PRICE is missing, zero, or non-numeric → log PRICE_ALERT_BAD_PRICE and exit ERROR.

4. Evaluate ATH gate

prior_ath = state.ath.price_usd  (null on first run)
new_ath   = (prior_ath is null) OR (CURRENT_PRICE > prior_ath)

If new_ath:

• Always update state.ath.price_usd = CURRENT_PRICE, state.ath.observed_at = NOW.
• Notify only if the last ath alert was >4h ago (or never). On the first run after token initialisation, suppress the notification (we don't know if this is genuinely an ATH or just the starting baseline) — set state.ath.announced_at = NOW so subsequent strict-higher prices alert correctly.
• If suppressed because prior_ath is null (first run), record verdict ATH_BASELINE for the log; no notify.
• Otherwise verdict for this gate is ATH.

5. Evaluate sharp-move gate

sharp = abs(H1_CHANGE_PCT) >= 20.0

If sharp:

• If state.last_alerts.sharp_move is within the last 4h → verdict SHARP_MOVE_DEDUPED, no notify.
• Otherwise verdict SHARP_MOVE, notify, set state.last_alerts.sharp_move = NOW.

Sign of H1_CHANGE_PCT decides the direction word in the message (up for ≥0, down for <0).

6. Evaluate target-crossing gate

For each target in TARGETS:

• If the target isn't yet in state.targets: this is the first time the operator has set it. Record side (above if CURRENT_PRICE < target, else below), first_seen_below_at=NOW, hit_at=null, announced_at=null. Do not notify on first observation. This avoids "the price was already there when you set the target" noise.
• If the target is in state.targets and hit_at is already set → skip; target-hit alerts are one-shot per side.
• Otherwise check the cross:
  • side=above & CURRENT_PRICE >= target → crossed.
  • side=below & CURRENT_PRICE <= target → crossed.
• On cross: set hit_at=NOW, announced_at=NOW, verdict TARGET_HIT for this target, notify (subject to 4h dedup on last_alerts.target_hit).

Targets that crossed in prior runs stay in the state file with hit_at set so they don't refire if the price wobbles back.