@gangfun/cli 0.2.1 → 0.3.0

package/README.md

@@ -10,15 +10,10 @@ Node ≥ 18. Also install Binance Agentic Wallet CLI (`baw`):
 
 ```bash
 npm i -g @binance/agentic-wallet
-npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com
+npm i -g @gangfun/cli@latest
 ```
 
-Package: [GitHub Packages `@gangfun/cli`](https://github.com/gangfun/cli/pkgs/npm/cli). Auth:
-
-```ini
-@gangfun:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-```
+Package: [`@gangfun/cli` on npm](https://www.npmjs.com/package/@gangfun/cli) (public registry, no auth). Upgrade with the same command.
 
 **Alternate** (public git tip):
 
@@ -44,6 +39,10 @@ npx skills add gangfun/gang-launchpad/skill
 ```bash
 gang preflight
 gang list
+gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 24h USD volume
+gang new [--limit 10] [--max-age 2h]
+gang near-grad [--min-pct 50] [--limit 10]
+gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>          # Soft archive: BNB; V2: quote ERC-20 (LaunchpadV2.sol math)
 gang buy --token <addr> --bnb <n> [--slippage 1]
@@ -74,6 +73,20 @@ gang execute --request-id …
 
 Buy / sell / create: **preview → you confirm → execute**. `requestId` expires in ~5 minutes.
 
+### Discovery (0.3.0+)
+
+`hot` / `new` / `near-grad` / `watch` read the gang.fun indexer (`GANG_API`) and cover the V2 and Soft tracks. Each row has
+`quote` (the unit to pass to `--bnb`), `progressPct`, `remaining`/`remainingUsd`, `volume24hUsd`, `holders`, `ageMin` and a `next` command.
+Graduated tokens are hidden unless `--include-graduated` is passed.
+
+`gang watch` polls and prints NDJSON. The minimum interval is 3s with `<addr>` and 10s for the whole market. With `<addr>` it emits `trade` / `progress` (25/50/75/90%) / `graduated`.
+Without it, it emits `new_token` / `near_grad` (crosses `--min-pct`) / `graduated`. `--max-events 1` blocks until the next event and
+`--webhook` POSTs each event. Details: [skill/references/discover.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/discover.md).
+
+```bash
+gang watch --events new_token,near_grad --max-events 1 --timeout 30m
+```
+
 ## Quote path
 
 - **Soft archive tokens:** on-chain `quoteBuy` / `quoteSell`.
@@ -94,7 +107,8 @@ Buy / sell / create: **preview → you confirm → execute**. `requestId` expire
 | `GANG_LAUNCHPAD` | Create target (default LaunchpadV2 `0x1B8F3f69…966E`) |
 | `GANG_RPC_URL` | BSC HTTP RPC |
 | `GANG_LOGO_API` | Logo upload endpoint (default `https://gang.fun/api/logos`) |
+| `GANG_API` | Indexer API for discovery (default `https://gang.fun/api`) |
 
 ## Version
 
-`0.2.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · distribute via [GitHub Packages](https://github.com/gangfun/cli/pkgs/npm/cli) (not npmjs)
+`0.3.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`

package/README.zh-CN.md

@@ -10,10 +10,10 @@ Node ≥ 18。另需 `baw`：
 
 ```bash
 npm i -g @binance/agentic-wallet
-npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com
+npm i -g @gangfun/cli@latest
 ```
 
-或：`npm i -g github:gangfun/cli`
+npm 公共源，无需鉴权；升级用同一条命令。或（git 最新）：`npm i -g github:gangfun/cli`
 
 Skill：`npx skills add gangfun/gang-launchpad/skill`
 
@@ -29,6 +29,10 @@ Skill：`npx skills add gangfun/gang-launchpad/skill`
 ```bash
 gang preflight
 gang list
+gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 按 24h USD 成交量
+gang new [--limit 10] [--max-age 2h]
+gang near-grad [--min-pct 50] [--limit 10]
+gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>
 gang buy --token <addr> --bnb <n> [--slippage 1]
@@ -53,6 +57,14 @@ gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
 gang execute --request-id …
 ```
 
+### 发现（0.3.0+）
+
+`hot` / `new` / `near-grad` / `watch` 读 gang.fun indexer（`GANG_API`），同时覆盖 V2 与 Soft。每行带 `quote`（`--bnb` 的单位）、
+`progressPct`、`remaining`/`remainingUsd`、`volume24hUsd`、`holders`、`ageMin` 和 `next` 命令；已毕业默认隐藏（`--include-graduated` 显示）。
+
+`gang watch` 轮询并输出 NDJSON（最短间隔：单币 3s，全市场 10s）：带 `<addr>` 推 `trade` / `progress`（25/50/75/90%）/ `graduated`；不带则推 `new_token` / `near_grad`（越过 `--min-pct`）/ `graduated`。
+`--max-events 1` = 阻塞到下一个事件；`--webhook` 把每个事件 POST 出去。详见 [skill/references/discover.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/discover.md)。
+
 ## Quote 路径
 
 - Soft 存量：链上 `quoteBuy` / `quoteSell`。
@@ -71,7 +83,8 @@ gang execute --request-id …
 | `GANG_LAUNCHPAD` | 发币目标（默认 V2） |
 | `GANG_RPC_URL` | BSC RPC |
 | `GANG_LOGO_API` | Logo 上传 API（默认 `https://gang.fun/api/logos`） |
+| `GANG_API` | 发现命令用的 indexer API（默认 `https://gang.fun/api`） |
 
 ## 版本
 
-`0.2.1` · [gangfun/cli](https://github.com/gangfun/cli)
+`0.3.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gangfun/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/chain.js

@@ -57,7 +57,7 @@ export async function resolvePad(token) {
   }
   throw new Error(
     `not a Gang token on known pads (V2/Soft/U/S): ${token}. ` +
-    `Upgrade: npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com  OR  npm i -g github:gangfun/cli`,
+    `Upgrade: npm i -g @gangfun/cli@latest  OR  npm i -g github:gangfun/cli`,
   )
 }
 

package/src/discover.js

@@ -0,0 +1,266 @@
+/** Discovery for agents: ranked lists + a polling event stream, read from the gang.fun indexer API. */
+export const API = (process.env.GANG_API || 'https://gang.fun/api').replace(/\/+$/, '')
+
+const SOFT_GRAD_BNB = 20
+const MILESTONES = [25, 50, 75, 90]
+const MARKET_PAGES = 10 // × 200 rows per track
+const TRADE_PAGE = 50
+const TRADE_PAGES = 4
+const SEEN_CAP = 2000
+const num = (v) => (v == null || v === '' ? 0 : Number(v))
+const usd = (v) => (Number.isFinite(v) ? Math.round(v * 100) / 100 : null)
+const now = () => Math.floor(Date.now() / 1000)
+
+/** `stop` (optional AbortSignal) cancels an in-flight request, e.g. when `gang watch --timeout` expires. */
+async function get(path, stop) {
+  // own controller instead of AbortSignal.any (Node ≥20.3); listener removed after each request so a
+  // long-lived `stop` signal doesn't pile up one listener per poll
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(new Error('timed out after 15s')), 15_000)
+  const onStop = () => ctl.abort(new Error('stopped'))
+  if (stop?.aborted) onStop()
+  else stop?.addEventListener('abort', onStop, { once: true })
+  try {
+    let r
+    try {
+      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json' } })
+    } catch (e) {
+      if (stop?.aborted) throw e
+      throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}. On-chain fallback without volume: \`gang list\``)
+    }
+    if (r.status === 404) return null
+    if (!r.ok) throw new Error(`gang API ${r.status} on ${path}`)
+    try {
+      return await r.json()
+    } catch (e) {
+      // body read can also hit the 15s timeout or a truncated/non-JSON body; keep the path in the message
+      if (stop?.aborted) throw e
+      throw new Error(`gang API bad response on ${path}: ${ctl.signal.reason?.message || e.message}`)
+    }
+  } finally {
+    clearTimeout(timer)
+    stop?.removeEventListener('abort', onStop)
+  }
+}
+
+/** "90" | "45s" | "30m" | "2h" | "1d" → seconds */
+export function parseDuration(raw, name) {
+  const m = String(raw ?? '').trim().match(/^(\d+(?:\.\d+)?)([smhd]?)$/i)
+  if (!m) throw new Error(`--${name} must look like 90, 45s, 30m, 2h or 1d (got ${raw})`)
+  return Math.round(Number(m[1]) * { '': 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase()])
+}
+
+/**
+ * One shape for both API tracks. `v2` = quote-ERC20 curves (/stocks/tokens, LaunchpadV2 family);
+ * `soft` = legacy BNB curve (/tokens, 20 BNB graduation). Amounts are human units of `quote`.
+ */
+export function normalize(r) {
+  const v2 = r.track === 'stocks'
+  const quote = v2 ? (r.quoteSymbol || '?') : 'BNB'
+  const raised = v2 ? num(r.raisedQuote) : num(r.raisedBnb)
+  const target = v2 ? num(r.gradAmtQuote) : SOFT_GRAD_BNB
+  const remaining = r.graduated ? 0 : (v2 ? num(r.graduationRemainingQuote) : Math.max(0, target - raised))
+  const quoteUsd = v2 ? num(r.quoteUsd) : num(r.bnbUsd)
+  return {
+    address: r.address, symbol: r.symbol, name: r.name, track: v2 ? 'v2' : 'soft',
+    quote, quoteAddress: v2 ? r.quoteAddress : null, taxed: v2 ? !!r.taxed : false,
+    graduated: !!r.graduated, pair: r.pair || null,
+    progressPct: num(r.progressPct), raised, graduationTarget: target, remaining,
+    remainingUsd: quoteUsd ? usd(remaining * quoteUsd) : null,
+    priceUsd: r.priceUsd ?? null, fdvUsd: usd(num(r.fdvUsd)),
+    volume24hUsd: usd(num(r.volume24hUsd)), trades24h: num(r.trades24h), trades: num(r.trades), holders: num(r.holders),
+    createdAt: r.createdAt, ageMin: r.createdAt ? Math.floor((now() - r.createdAt) / 60) : null,
+    lastTradeAt: r.lastTradeAt || null, creatorHandle: r.creatorHandle || null, logoUrl: r.logoUrl || null,
+  }
+}
+
+async function pages(path, stop) {
+  const rows = []
+  for (let offset = 0, i = 0; i < MARKET_PAGES; i++) {
+    const sep = path.includes('?') ? '&' : '?'
+    const page = await get(`${path}${sep}limit=200&offset=${offset}`, stop)
+    // list routes always exist: a 404 is an outage, never "no tokens"
+    if (!page) throw new Error(`gang API 404 on ${path}`)
+    rows.push(...(page.items || []))
+    if (!page.hasMore || page.nextOffset == null) return { rows, truncated: false }
+    offset = page.nextOffset
+  }
+  return { rows, truncated: true }
+}
+
+/** All indexed tokens, normalized and de-duplicated. track: all | v2 | soft */
+export async function fetchMarket(track = 'all', stop) {
+  if (!['all', 'v2', 'soft'].includes(track)) throw new Error(`--track must be all, v2 or soft (got ${track})`)
+  const none = { rows: [], truncated: false }
+  const [v2, soft] = await Promise.all([
+    track === 'soft' ? none : pages('/stocks/tokens', stop),
+    track === 'v2' ? none : pages('/tokens?sort=new', stop),
+  ])
+  const seen = new Map()
+  for (const r of [...v2.rows, ...soft.rows]) {
+    const t = normalize(r)
+    if (!seen.has(t.address)) seen.set(t.address, t)
+  }
+  return { tokens: [...seen.values()], truncated: v2.truncated || soft.truncated }
+}
+
+const hint = (t) => `gang quote --token ${t.address} --bnb <amount in ${t.quote}>`
+const withHint = (t) => ({ ...t, next: t.graduated ? `trade on PancakeSwap (pair ${t.pair})` : hint(t) })
+
+/** hot = 24h USD volume on the curve; new = newest first; near-grad = closest to graduation. */
+export function rank(tokens, sort, { limit = 10, minPct = 50, maxAgeSec = null, includeGraduated = false } = {}) {
+  let list = includeGraduated ? tokens : tokens.filter((t) => !t.graduated)
+  if (sort === 'hot') {
+    // graduated rows carry DEX volume with trades24h = 0, so volume alone also qualifies
+    list = list.filter((t) => t.trades24h > 0 || t.volume24hUsd > 0)
+      .sort((a, b) => (b.volume24hUsd - a.volume24hUsd) || (b.trades24h - a.trades24h))
+  } else if (sort === 'new') {
+    const t0 = now()
+    if (maxAgeSec != null) list = list.filter((t) => t0 - t.createdAt <= maxAgeSec)
+    list.sort((a, b) => b.createdAt - a.createdAt)
+  } else if (sort === 'near-grad') {
+    list = list.filter((t) => !t.graduated && t.progressPct >= minPct)
+      .sort((a, b) => (b.progressPct - a.progressPct) || ((a.remainingUsd ?? Infinity) - (b.remainingUsd ?? Infinity)))
+  }
+  return list.slice(0, limit).map(withHint)
+}
+
+async function tokenDetail(addr, stop) {
+  const r = await get(`/tokens/${addr.toLowerCase()}`, stop)
+  if (!r) throw new Error(`token not indexed by ${API}: ${addr}. On-chain view: \`gang token --token ${addr}\``)
+  return normalize(r)
+}
+
+/** One page of trades, newest first. */
+async function tradePage(t, offset = 0, stop) {
+  const base = t.track === 'v2' ? '/stocks/tokens' : '/tokens'
+  const page = await get(`${base}/${t.address}/trades?limit=${TRADE_PAGE}&offset=${offset}`, stop)
+  const items = (page?.items || []).map((x) => ({
+    side: x.side, trader: x.trader, traderHandle: x.traderHandle || null,
+    amount: num(x.quoteIn ?? x.bnb), quote: t.quote, tokens: num(x.tokens),
+    price: num(x.price), at: x.ts, tx: x.tx,
+  }))
+  return { items, next: page?.hasMore && page.nextOffset != null ? page.nextOffset : null }
+}
+
+const tradeKey = (x) => `${x.tx}:${x.side}:${x.trader}:${x.tokens}`
+
+/**
+ * Trades not in `seen`, oldest first. Pages back until a page contains a known trade; `gap` = gave up
+ * after TRADE_PAGES pages of only-unseen trades, so older ones in between were skipped.
+ */
+async function freshTrades(t, seen, stop) {
+  const fresh = []
+  const local = new Set() // offsets shift when trades land mid-pagination → same row on two pages
+  for (let offset = 0, i = 0; i < TRADE_PAGES; i++) {
+    const { items, next } = await tradePage(t, offset, stop)
+    let hit = false
+    for (const x of items) {
+      const k = tradeKey(x)
+      if (seen.has(k)) hit = true
+      else if (!local.has(k)) { local.add(k); fresh.push(x) }
+    }
+    if (hit || next == null) return { fresh: fresh.reverse(), gap: false }
+    offset = next
+  }
+  return { fresh: fresh.reverse(), gap: true }
+}
+
+const crossed = (prev, cur, levels) => levels.filter((m) => prev < m && cur >= m)
+const brief = (t) => ({
+  token: t.address, symbol: t.symbol, track: t.track, quote: t.quote, progressPct: t.progressPct,
+  remaining: t.remaining, remainingUsd: t.remainingUsd, volume24hUsd: t.volume24hUsd, holders: t.holders,
+})
+
+/**
+ * Poll the API and call emit(event) for each change. Token mode: trade / progress / graduated.
+ * Market mode: new_token / near_grad (crossing minPct upward) / graduated.
+ * The first tick only snapshots state; current matches come from `gang near-grad` / `gang new`.
+ * `stop` (AbortSignal) cancels in-flight requests; errors after shouldStop() flips are dropped, not emitted.
+ */
+export async function watch({ token, intervalSec = 10, minPct = 50, track = 'all', events = null, emit, shouldStop, stop }) {
+  const want = (e) => !events || events.has(e)
+  // wakes early once shouldStop() flips (e.g. --timeout) instead of overshooting a full interval
+  const sleep = async (s) => {
+    const end = Date.now() + s * 1000
+    while (Date.now() < end && !shouldStop()) await new Promise((r) => setTimeout(r, Math.min(1000, end - Date.now())))
+  }
+
+  if (token) {
+    // graduation always ends a token watch; when --events filters it out, end with a meta line instead
+    const finish = (t) => (want('graduated')
+      ? emit({ event: 'graduated', ...brief(t), pair: t.pair })
+      : emit({ event: 'ended', reason: 'graduated', token: t.address, pair: t.pair }, { meta: true }))
+    let t = await tokenDetail(token, stop)
+    const seen = new Set((await tradePage(t, 0, stop)).items.map(tradeKey))
+    const remember = (k) => {
+      seen.add(k)
+      if (seen.size > SEEN_CAP) seen.delete(seen.values().next().value) // Set keeps insertion order → drops oldest
+    }
+    emit({ event: 'watching', mode: 'token', ...brief(t), graduated: t.graduated, intervalSec }, { meta: true })
+    if (t.graduated) return finish(t)
+    for (;;) {
+      await sleep(intervalSec)
+      if (shouldStop()) return
+      try {
+        const cur = await tokenDetail(token, stop)
+        const { fresh, gap } = await freshTrades(cur, seen, stop)
+        // advance state only after both reads succeed, so a failed tick can't swallow a prev → cur transition
+        const prev = t
+        t = cur
+        if (gap) emit({ event: 'error', error: `more than ${TRADE_PAGE * TRADE_PAGES} trades since last poll; older ones skipped` }, { meta: true })
+        for (const x of fresh) {
+          remember(tradeKey(x))
+          if (want('trade')) emit({ event: 'trade', token: t.address, symbol: t.symbol, ...x, progressPct: t.progressPct })
+          if (shouldStop()) return
+        }
+        for (const m of crossed(prev.progressPct, t.progressPct, MILESTONES)) {
+          if (want('progress')) emit({ event: 'progress', milestone: m, ...brief(t), next: hint(t) })
+          if (shouldStop()) return
+        }
+        if (!prev.graduated && t.graduated) return finish(t)
+      } catch (e) {
+        if (shouldStop()) return
+        emit({ event: 'error', error: e.message }, { meta: true })
+      }
+      if (shouldStop()) return
+    }
+  }
+
+  const first = await fetchMarket(track, stop)
+  // only grows: a token missing from one poll must not come back as new_token
+  const known = new Map(first.tokens.map((t) => [t.address, t]))
+  emit({ event: 'watching', mode: 'market', track, tokens: known.size, minPct, intervalSec }, { meta: true })
+  let warned = false
+  const warnTruncated = (truncated) => {
+    if (!truncated || warned) return
+    warned = true
+    emit({ event: 'error', error: `market list capped at ${MARKET_PAGES * 200} tokens per track; tokens beyond the cap are not watched` }, { meta: true })
+  }
+  warnTruncated(first.truncated)
+  for (;;) {
+    await sleep(intervalSec)
+    if (shouldStop()) return
+    try {
+      const { tokens, truncated } = await fetchMarket(track, stop)
+      warnTruncated(truncated)
+      for (const t of tokens) {
+        const prev = known.get(t.address)
+        known.set(t.address, t)
+        const out = []
+        if (!prev) out.push({ event: 'new_token', ...withHint(t) })
+        else if (!prev.graduated && t.graduated) out.push({ event: 'graduated', ...brief(t), pair: t.pair })
+        else if (!t.graduated && prev.progressPct < minPct && t.progressPct >= minPct) {
+          out.push({ event: 'near_grad', ...brief(t), next: hint(t) })
+        }
+        for (const ev of out) {
+          if (want(ev.event)) emit(ev)
+          if (shouldStop()) return
+        }
+      }
+    } catch (e) {
+      if (shouldStop()) return
+      emit({ event: 'error', error: e.message }, { meta: true })
+    }
+  }
+}

package/src/index.js

@@ -5,13 +5,19 @@ import {
 } from './chain.js'
 import { bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
 import { uploadLogoFile, LOGO_UI } from './logo.js'
+import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
 const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def }
 const flag = (name) => args.includes(`--${name}`)
 const out = (o) => console.log(JSON.stringify(o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
-const fail = (msg, extra = {}) => { out({ success: false, error: msg, ...extra }); process.exit(1) }
+// `gang watch` speaks NDJSON, so its failures are one line too (with event/fatal for stream consumers)
+const fail = (msg, extra = {}) => {
+  if (cmd === 'watch') console.log(JSON.stringify({ event: 'error', fatal: true, success: false, error: msg, ...extra }))
+  else out({ success: false, error: msg, ...extra })
+  process.exit(1)
+}
 
 const parseSlippage = (raw) => {
   const s = Number(raw)
@@ -19,10 +25,29 @@ const parseSlippage = (raw) => {
   return s
 }
 
+const parseCount = (name, raw, max) => {
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < 1 || n > max) fail(`--${name} must be an integer between 1 and ${max}`, { got: raw })
+  return n
+}
+const parsePct = (raw) => {
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0 || n > 100) fail('--min-pct must be a number between 0 and 100', { got: raw })
+  return n
+}
+const WATCH_EVENTS = ['trade', 'progress', 'graduated', 'new_token', 'near_grad']
+
 const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet) · LaunchpadV2 create
 
   gang preflight                         check sign-in, Developer Mode, tradeAllTokens, Agent ID
   gang list                              tokens across V2 / Soft / U / S
+  gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]
+                                         curve tokens ranked by 24h USD volume
+  gang new [--limit 10] [--max-age 2h] [--track …]      newest curve tokens first
+  gang near-grad [--min-pct 50] [--limit 10] [--track …]  closest to graduation
+  gang watch [<addr>] [--interval 10] [--min-pct 50] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
+                                         NDJSON stream (min interval: 3s token, 10s market). <addr>: trade / progress / graduated.
+                                         no addr: new_token / near_grad / graduated across the market
   gang token --token <addr>              one token (auto-resolves pad)
   gang quote --token <addr> --bnb <n>    Soft: BNB quote; V2/U/S: quote-token amount (same flag)
   gang buy --token <addr> --bnb <n> [--slippage 1]      Soft: payable BNB; V2: approve quote then buy
@@ -34,7 +59,7 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang tx --hash <0x..>                  wait for receipt and decode Gang events
 
 Logo UI (browser): ${LOGO_UI}
-env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API`
+env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API})`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -87,6 +112,85 @@ async function main() {
       const me = bawStatus() === 'CONNECTED' ? bawAddress() : undefined
       return out({ success: true, createPad: ADDR.v2, tokens: await listTokens(me) })
     }
+    case 'hot':
+    case 'new':
+    case 'near-grad': {
+      const limit = parseCount('limit', opt('limit', '10'), 100)
+      const minPct = parsePct(opt('min-pct', '50'))
+      const maxAgeSec = opt('max-age') ? parseDuration(opt('max-age'), 'max-age') : null
+      const track = opt('track', 'all')
+      const includeGraduated = flag('include-graduated')
+      const market = await fetchMarket(track)
+      const tokens = rank(market.tokens, cmd, { limit, minPct, maxAgeSec, includeGraduated })
+      const empty = {
+        hot: includeGraduated ? 'No token traded in the last 24h.' : 'No curve token traded in the last 24h.',
+        new: maxAgeSec != null ? `No curve token created in the last ${opt('max-age')}.` : 'No curve tokens.',
+        'near-grad': `No curve token at ≥${minPct}% of graduation; lower --min-pct to see the closest ones.`,
+      }[cmd]
+      return out({
+        success: true, source: API, sort: cmd, track, count: tokens.length,
+        ...(cmd === 'near-grad' ? { minPct } : {}), ...(maxAgeSec != null ? { maxAgeSec } : {}),
+        ...(market.truncated ? { truncated: true } : {}),
+        tokens,
+        note: tokens.length ? 'Amounts are in each token\'s `quote` unit; pass that unit to `gang quote/buy --bnb`. Data, not advice.' : empty,
+      })
+    }
+    case 'watch': {
+      const positional = args[1] && !args[1].startsWith('--') ? args[1] : null
+      if (positional && flag('token')) fail('give the token either as <addr> or via --token, not both')
+      if (!positional && flag('token') && !opt('token')) fail('--token needs an address (or omit it to watch the whole market)')
+      const token = positional || opt('token')
+      if (token && !/^0x[0-9a-fA-F]{40}$/.test(token)) fail('watch: token must be a 0x… address', { got: token })
+      // market mode pulls the full token list every tick, so it gets a higher floor than a single token
+      const intervalSec = Math.max(token ? 3 : 10, parseDuration(opt('interval', '10'), 'interval'))
+      const maxEvents = opt('max-events') ? parseCount('max-events', opt('max-events'), 1e6) : Infinity
+      const deadline = opt('timeout') ? Date.now() + parseDuration(opt('timeout'), 'timeout') * 1000 : Infinity
+      const minPct = parsePct(opt('min-pct', '50'))
+      const webhook = opt('webhook')
+      if (webhook && !/^https?:\/\//.test(webhook)) fail('--webhook must be an http(s) URL', { got: webhook })
+      let events = null
+      if (opt('events')) {
+        events = new Set(opt('events').split(',').map((s) => s.trim().replace(/-/g, '_')).filter(Boolean))
+        const bad = [...events].filter((e) => !WATCH_EVENTS.includes(e))
+        if (bad.length) fail(`unknown --events: ${bad.join(', ')}`, { allowed: WATCH_EVENTS })
+      }
+
+      let count = 0
+      const hooks = new Set()
+      const line = (o) => console.log(JSON.stringify({ ...o, emittedAt: Math.floor(Date.now() / 1000) }))
+      // meta events (watching / error / ended / timeout) go to stdout only and do not count toward --max-events
+      const emit = (ev, { meta = false } = {}) => {
+        line(ev)
+        if (meta) return
+        count++
+        if (webhook) {
+          const p = fetch(webhook, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(ev), signal: AbortSignal.timeout(10_000),
+          }).then((r) => { if (!r.ok) line({ event: 'error', error: `webhook ${r.status}` }) })
+            .catch((e) => line({ event: 'error', error: `webhook: ${e.message}` }))
+            .finally(() => hooks.delete(p))
+          hooks.add(p)
+        }
+      }
+      // aborts in-flight API requests at the deadline so --timeout isn't stretched by a slow API.
+      // setTimeout caps at 2^31-1 ms (~24.8d) and fires at once beyond it; longer timeouts rely on sleep's check.
+      const stopper = new AbortController()
+      const delay = deadline - Date.now()
+      const deadlineTimer = delay <= 2 ** 31 - 1 ? setTimeout(() => stopper.abort(), delay) : null
+      // the timer runs on the monotonic clock and may beat Date.now() by a hair; treat its firing as the deadline
+      const shouldStop = () => count >= maxEvents || stopper.signal.aborted || Date.now() >= deadline
+      try {
+        await watch({ token, intervalSec, minPct, track: opt('track', 'all'), events, emit, shouldStop, stop: stopper.signal })
+      } catch (e) {
+        if (!shouldStop()) throw e // startup failure → fail() prints it as one NDJSON line
+      } finally {
+        clearTimeout(deadlineTimer)
+      }
+      if (count < maxEvents && (stopper.signal.aborted || Date.now() >= deadline)) line({ event: 'timeout', events: count })
+      await Promise.allSettled([...hooks])
+      return
+    }
     case 'token': {
       const token = opt('token'); if (!token) fail('--token required')
       const me = bawStatus() === 'CONNECTED' ? bawAddress() : undefined