@gangfun/cli 0.1.4 → 0.3.0

package/src/chain.js

@@ -1,89 +1,280 @@
-import { createPublicClient, http, formatEther, parseEther, encodeFunctionData, decodeEventLog } from 'viem'
+import { createPublicClient, http, formatEther, parseEther, encodeFunctionData, decodeEventLog, zeroAddress } from 'viem'
 import { bsc } from 'viem/chains'
-import { LAUNCHPAD_ABI, ERC20_ABI } from './abi.js'
+import { SOFT_ABI, V2_ABI, ERC20_ABI } from './abi.js'
+
+export const ADDR = {
+  v2: '0x1B8F3f69DFa0a7F63d308C7EB0Fd38D8b099966E',
+  soft: '0x4E6f13c8A453c1b8b4E20b590082bb233a5b80d7',
+  u: '0xF81C4E51c48466c6025B0165b1Ea0F6978c712cb',
+  s: '0x60aee38576035E757deD30fF8db8A8DA476430C1',
+  wbnb: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
+}
+
+const FORBIDDEN_CREATE = new Set([ADDR.soft, ADDR.u, ADDR.s].map((a) => a.toLowerCase()))
 
 export const CONFIG = {
   rpc: process.env.GANG_RPC_URL || 'https://bsc-dataseed.binance.org',
-  launchpad: process.env.GANG_LAUNCHPAD || '0x315Ba2e8952D06094CC636b2B84229FA32fb23A7',
+  launchpad: process.env.GANG_LAUNCHPAD || ADDR.v2,
   chainId: '56',
 }
 
 export const client = createPublicClient({ chain: bsc, transport: http(CONFIG.rpc) })
-const pad = (functionName, args = []) => client.readContract({ address: CONFIG.launchpad, abi: LAUNCHPAD_ABI, functionName, args })
-const erc = (address, functionName, args = []) => client.readContract({ address, abi: ERC20_ABI, functionName, args })
-
 export const fmt = (wei) => formatEther(wei)
 export const fmtTok = (units) => Number(formatEther(units)).toLocaleString('en-US', { maximumFractionDigits: 2 })
-export { parseEther, encodeFunctionData }
+export { parseEther, encodeFunctionData, zeroAddress }
 
-export async function tokenInfo(token, me) {
-  const [c, name, symbol, locked, grad, cap] = await Promise.all([
-    pad('curves', [token]), erc(token, 'name'), erc(token, 'symbol'), erc(token, 'locked'),
-    pad('GRADUATION_BNB'), pad('MAX_PER_WALLET'),
-  ])
-  const [creator, realBnb, sold, graduated, pair] = c
-  if (creator === '0x0000000000000000000000000000000000000000') {
+const erc = (address, functionName, args = []) => client.readContract({ address, abi: ERC20_ABI, functionName, args })
+const read = (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args })
+
+export function assertCreateTarget(addr = CONFIG.launchpad) {
+  const a = String(addr || '').toLowerCase()
+  if (a !== ADDR.v2.toLowerCase()) {
     throw new Error(
-      `not a Gang token: ${token} (launchpad ${CONFIG.launchpad}). ` +
-      `Upgrade: npm i -g @gangfun/cli@0.1.3 --registry=https://npm.pkg.github.com  OR  ` +
-      `export GANG_LAUNCHPAD=0x315Ba2e8952D06094CC636b2B84229FA32fb23A7`
+      `create refused: only LaunchpadV2 ${ADDR.v2} (got ${addr}). ` +
+      `Soft/LaunchpadU/LaunchpadS are not create routes — buy/sell/claim existing only. ` +
+      `Unset GANG_LAUNCHPAD or set it to V2.`,
     )
   }
-  // curve end price (1e-7 BNB) for graduated tokens; live spot otherwise
-  const price = graduated ? 100000000000n : await pad('spotPrice', [token])
+}
+
+const PADS = [
+  { id: 'v2', address: ADDR.v2, kind: 'v2', abi: V2_ABI },
+  { id: 'soft', address: ADDR.soft, kind: 'soft', abi: SOFT_ABI },
+  { id: 'u', address: ADDR.u, kind: 'v2', abi: V2_ABI },
+  { id: 's', address: ADDR.s, kind: 'v2', abi: V2_ABI },
+]
+
+/** Resolve which pad hosts `token` by probing curves(token).creator != 0. */
+export async function resolvePad(token) {
+  for (const pad of PADS) {
+    try {
+      const c = await read(pad.address, pad.abi, 'curves', [token])
+      const creator = Array.isArray(c) ? c[0] : c.creator
+      if (creator && creator !== zeroAddress) {
+        return { ...pad, curve: c }
+      }
+    } catch { /* wrong ABI shape or empty */ }
+  }
+  throw new Error(
+    `not a Gang token on known pads (V2/Soft/U/S): ${token}. ` +
+    `Upgrade: npm i -g @gangfun/cli@latest  OR  npm i -g github:gangfun/cli`,
+  )
+}
+
+function softInfoFromCurve(c) {
+  const [creator, realBnb, sold, graduated, pair] = c
+  return { kind: 'soft', creator, raised: realBnb, sold, graduated, pair, quote: ADDR.wbnb, gradAmt: null, taxed: false, virtualQuote: null, refPair: null }
+}
+
+function v2InfoFromCurve(c) {
+  const [creator, quote, realQuote, sold, gradAmt, virtualQuote, graduated, taxed, pair, refPair] = c
+  return { kind: 'v2', creator, raised: realQuote, sold, graduated, pair, quote, gradAmt, taxed, virtualQuote, refPair }
+}
+
+export async function tokenInfo(token, me) {
+  const pad = await resolvePad(token)
+  const base = pad.kind === 'soft' ? softInfoFromCurve(pad.curve) : v2InfoFromCurve(pad.curve)
+  const [name, symbol] = await Promise.all([erc(token, 'name'), erc(token, 'symbol')])
+  let locked = null
+  try { locked = await erc(token, 'locked') } catch { /* */ }
+  let cap = null
+  try { cap = await read(pad.address, pad.abi, 'MAX_PER_WALLET') } catch { /* */ }
+
+  let price = null
+  if (pad.kind === 'soft') {
+    try { price = base.graduated ? 100000000000n : await read(pad.address, pad.abi, 'spotPrice', [token]) } catch { /* */ }
+  } else if (base.virtualQuote && base.virtualQuote > 0n) {
+    // spot ≈ virtualQuote / (VIRTUAL_TOKEN - sold) * 1e18-ish; expose raised/grad instead
+    const vq = BigInt(base.virtualQuote)
+    const sold = BigInt(base.sold)
+    const VIRTUAL_TOKEN = 1066666666666666666666666667n
+    const tReserve = VIRTUAL_TOKEN - sold
+    if (tReserve > 0n) price = (vq * 10n ** 18n) / tReserve
+  }
+
+  const grad = base.gradAmt != null ? BigInt(base.gradAmt) : (pad.kind === 'soft' ? await read(pad.address, pad.abi, 'GRADUATION_BNB') : 15n * 10n ** 18n)
+  const raised = BigInt(base.raised)
   const info = {
-    token, name, symbol, creator, graduated, pair: graduated ? pair : null, locked,
-    priceBnb: Number(price) / 1e18,
-    fdvBnb: (Number(price) / 1e18) * 1e9,
-    raisedBnb: fmt(realBnb), graduationBnb: fmt(grad),
-    progressPct: Number((realBnb * 10000n) / grad) / 100,
-    soldTokens: fmtTok(sold), walletCapTokens: fmtTok(cap),
+    token, name, symbol, creator: base.creator, graduated: base.graduated,
+    pair: base.graduated ? base.pair : null, locked,
+    pad: pad.id, padAddress: pad.address, kind: base.kind,
+    quote: base.quote, taxed: !!base.taxed,
+    priceBnb: price != null ? Number(price) / 1e18 : null,
+    fdvBnb: price != null ? (Number(price) / 1e18) * 1e9 : null,
+    raisedBnb: fmt(raised), graduationBnb: fmt(grad),
+    progressPct: grad > 0n ? Number((raised * 10000n) / grad) / 100 : 0,
+    soldTokens: fmtTok(base.sold), walletCapTokens: cap != null ? fmtTok(cap) : null,
+    logoURI: null,
+  }
+  if (pad.kind === 'v2') {
+    try { info.logoURI = await read(pad.address, pad.abi, 'logoURIOf', [token]) } catch { /* U/S may lack */ }
   }
   if (me) {
-    const [bal, room] = await Promise.all([erc(token, 'balanceOf', [me]), pad('walletRoom', [token, me])])
-    info.myBalance = fmtTok(bal); info.myBalanceRaw = bal.toString(); info.myRoomTokens = fmtTok(room); info.myRoomRaw = room.toString()
+    const bal = await erc(token, 'balanceOf', [me])
+    info.myBalance = fmtTok(bal); info.myBalanceRaw = bal.toString()
+    try {
+      const room = await read(pad.address, pad.abi, 'walletRoom', [token, me])
+      info.myRoomTokens = fmtTok(room); info.myRoomRaw = room.toString()
+    } catch { /* */ }
   }
   return info
 }
 
 export async function listTokens(me) {
-  const n = await pad('tokenCount')
-  const addrs = await Promise.all(Array.from({ length: Number(n) }, (_, i) => pad('allTokens', [BigInt(i)])))
-  return Promise.all(addrs.map((a) => tokenInfo(a, me)))
+  const out = []
+  for (const pad of PADS) {
+    try {
+      const n = await read(pad.address, pad.abi, 'tokenCount')
+      const addrs = await Promise.all(Array.from({ length: Number(n) }, (_, i) => read(pad.address, pad.abi, 'allTokens', [BigInt(i)])))
+      for (const a of addrs) {
+        try { out.push(await tokenInfo(a, me)) } catch { /* skip */ }
+      }
+    } catch { /* pad down */ }
+  }
+  return out
 }
 
-export async function quoteBuy(token, buyer, bnb) {
-  const gross = parseEther(bnb)
-  const [tokensOut, bnbIn, fee, refund] = await pad('quoteBuy', [token, buyer, gross])
-  return { bnbGross: bnb, tokensOut, bnbIn, fee, refund, tokensOutFmt: fmtTok(tokensOut), bnbInFmt: fmt(bnbIn), feeFmt: fmt(fee), refundFmt: fmt(refund) }
+/** LaunchpadV2 curve constants (LaunchpadV2.sol) — unique off-chain path = on-chain math. */
+const V2_VIRTUAL_TOKEN = 1066666666666666666666666667n
+const V2_BPS = 10000n
+const V2_PROTOCOL_FEE_BPS = 100n // 1%
+
+const ceilDiv = (a, b) => (b === 0n ? 0n : (a + b - 1n) / b)
+
+/** Contract-equivalent buy quote (_prepBuy + _tokensOut / _quoteInFor). No Soft/U/S fallback. */
+function v2QuoteBuyFromCurve(base, quoteIn, room) {
+  const vq = BigInt(base.virtualQuote)
+  const sold = BigInt(base.sold)
+  const raised = BigInt(base.raised)
+  const gradAmt = BigInt(base.gradAmt)
+  const tokensOutOf = (net) => {
+    const k = vq * V2_VIRTUAL_TOKEN
+    const qReserve = vq + raised
+    const tReserve = V2_VIRTUAL_TOKEN - sold
+    const newT = ceilDiv(k, qReserve + net)
+    return tReserve - newT
+  }
+  const quoteInFor = (tokensOut) => {
+    const k = vq * V2_VIRTUAL_TOKEN
+    const qReserve = vq + raised
+    const tReserve = V2_VIRTUAL_TOKEN - sold
+    return ceilDiv(k, tReserve - tokensOut) - qReserve
+  }
+  const recomputeFee = (gross, netIn) => {
+    let spentGross = ceilDiv(netIn * V2_BPS, V2_BPS - V2_PROTOCOL_FEE_BPS)
+    if (spentGross > gross) spentGross = gross
+    const taxPlat = (spentGross * V2_PROTOCOL_FEE_BPS) / V2_BPS
+    const net = spentGross - taxPlat
+    const refundGross = gross - spentGross
+    return { taxPlat, net, refundGross, spentGross }
+  }
+
+  let taxPlat = (quoteIn * V2_PROTOCOL_FEE_BPS) / V2_BPS
+  let net = quoteIn - taxPlat
+  let refundGross = 0n
+  const remaining = gradAmt > raised ? gradAmt - raised : 0n
+  if (net > remaining) {
+    net = remaining
+    ;({ taxPlat, net, refundGross } = recomputeFee(quoteIn, net))
+    if (net > remaining) net = remaining
+  }
+  let tokensOut = tokensOutOf(net)
+  if (room != null && tokensOut > room) {
+    tokensOut = room
+    net = quoteInFor(room)
+    ;({ taxPlat, net, refundGross } = recomputeFee(quoteIn, net))
+  }
+  return { tokensOut, spent: quoteIn - refundGross, fee: taxPlat, refund: refundGross }
+}
+
+/** Contract-equivalent sell quote (_quoteOut + 1% platform fee). */
+function v2QuoteSellFromCurve(base, tokensIn) {
+  const vq = BigInt(base.virtualQuote)
+  const sold = BigInt(base.sold)
+  const raised = BigInt(base.raised)
+  const k = vq * V2_VIRTUAL_TOKEN
+  const qReserve = vq + raised
+  const tReserve = V2_VIRTUAL_TOKEN - sold
+  const newQ = ceilDiv(k, tReserve + tokensIn)
+  const quoteOut = qReserve - newQ
+  const fee = (quoteOut * V2_PROTOCOL_FEE_BPS) / V2_BPS
+  return { out: quoteOut - fee, fee }
+}
+
+export async function quoteBuy(token, buyer, amountHuman) {
+  const pad = await resolvePad(token)
+  const gross = parseEther(amountHuman)
+  if (pad.kind === 'soft') {
+    const [tokensOut, bnbIn, fee, refund] = await read(pad.address, pad.abi, 'quoteBuy', [token, buyer, gross])
+    return { kind: 'soft', pad: pad.id, padAddress: pad.address, amountHuman, tokensOut, spent: bnbIn, fee, refund,
+      tokensOutFmt: fmtTok(tokensOut), spentFmt: fmt(bnbIn), feeFmt: fmt(fee), refundFmt: fmt(refund), unit: 'BNB',
+      quotePath: 'onchain-quoteBuy' }
+  }
+  // Unique path: LaunchpadV2.sol _prepBuy / _tokensOut / _quoteInFor (no on-chain quoteBuy view).
+  const base = v2InfoFromCurve(pad.curve)
+  let room = null
+  try { room = await read(pad.address, pad.abi, 'walletRoom', [token, buyer]) } catch { /* */ }
+  const q = v2QuoteBuyFromCurve(base, gross, room)
+  return { kind: 'v2', pad: pad.id, padAddress: pad.address, quote: base.quote, amountHuman,
+    tokensOut: q.tokensOut, spent: q.spent, fee: q.fee, refund: q.refund,
+    tokensOutFmt: fmtTok(q.tokensOut), spentFmt: fmt(q.spent), feeFmt: fmt(q.fee), refundFmt: fmt(q.refund),
+    unit: 'quote', quotePath: 'LaunchpadV2.sol#_prepBuy', deterministic: true }
 }
 
 export async function quoteSell(token, tokensIn) {
-  const [bnbToUser, fee] = await pad('quoteSell', [token, tokensIn])
-  return { tokensIn, bnbToUser, fee, tokensInFmt: fmtTok(tokensIn), bnbToUserFmt: fmt(bnbToUser), feeFmt: fmt(fee) }
+  const pad = await resolvePad(token)
+  if (pad.kind === 'soft') {
+    const [bnbToUser, fee] = await read(pad.address, pad.abi, 'quoteSell', [token, tokensIn])
+    return { kind: 'soft', pad: pad.id, padAddress: pad.address, tokensIn, out: bnbToUser, fee,
+      tokensInFmt: fmtTok(tokensIn), outFmt: fmt(bnbToUser), feeFmt: fmt(fee), unit: 'BNB',
+      quotePath: 'onchain-quoteSell' }
+  }
+  const base = v2InfoFromCurve(pad.curve)
+  const q = v2QuoteSellFromCurve(base, tokensIn)
+  return { kind: 'v2', pad: pad.id, padAddress: pad.address, quote: base.quote, tokensIn, out: q.out, fee: q.fee,
+    tokensInFmt: fmtTok(tokensIn), outFmt: fmt(q.out), feeFmt: fmt(q.fee), unit: 'quote',
+    quotePath: 'LaunchpadV2.sol#_quoteOut', deterministic: true }
+}
+
+export async function isAgent(account) {
+  // Prefer V2 gate (create path); fall back Soft.
+  try { return await read(ADDR.v2, V2_ABI, 'isAgent', [account]) } catch { /* */ }
+  try { return await read(ADDR.soft, SOFT_ABI, 'isAgent', [account]) } catch { /* */ }
+  return false
 }
 
-export const isAgent = (a) => pad('isAgent', [a])
 export const balanceOf = (token, a) => erc(token, 'balanceOf', [a])
-export const allowance = (token, a) => erc(token, 'allowance', [a, CONFIG.launchpad])
+export async function allowance(token, owner, spender) {
+  return erc(token, 'allowance', [owner, spender])
+}
 
 export const calldata = {
-  buy: (token, minTokensOut) => encodeFunctionData({ abi: LAUNCHPAD_ABI, functionName: 'buy', args: [token, minTokensOut] }),
-  sell: (token, tokensIn, minBnbOut) => encodeFunctionData({ abi: LAUNCHPAD_ABI, functionName: 'sell', args: [token, tokensIn, minBnbOut] }),
-  approve: (amount) => encodeFunctionData({ abi: ERC20_ABI, functionName: 'approve', args: [CONFIG.launchpad, amount] }),
-  create: (name, symbol) => encodeFunctionData({ abi: LAUNCHPAD_ABI, functionName: 'create', args: [name, symbol] }),
+  softBuy: (token, minTokensOut) => encodeFunctionData({ abi: SOFT_ABI, functionName: 'buy', args: [token, minTokensOut] }),
+  softSell: (token, tokensIn, minBnbOut) => encodeFunctionData({ abi: SOFT_ABI, functionName: 'sell', args: [token, tokensIn, minBnbOut] }),
+  v2Buy: (token, quoteIn, minTokensOut) => encodeFunctionData({ abi: V2_ABI, functionName: 'buy', args: [token, quoteIn, minTokensOut] }),
+  v2Sell: (token, tokensIn, minQuoteOut) => encodeFunctionData({ abi: V2_ABI, functionName: 'sell', args: [token, tokensIn, minQuoteOut] }),
+  approve: (spender, amount) => encodeFunctionData({ abi: ERC20_ABI, functionName: 'approve', args: [spender, amount] }),
+  createV2: (name, symbol, logoURI, taxed, pairOrQuote) =>
+    encodeFunctionData({ abi: V2_ABI, functionName: 'create', args: [name, symbol, logoURI, taxed, pairOrQuote] }),
 }
 
 export async function decodeTx(hash) {
   const r = await client.waitForTransactionReceipt({ hash, timeout: 120_000 })
   const events = []
+  const known = new Map(PADS.map((p) => [p.address.toLowerCase(), p]))
   for (const log of r.logs) {
-    if (log.address.toLowerCase() !== CONFIG.launchpad.toLowerCase()) continue
+    const pad = known.get(log.address.toLowerCase())
+    if (!pad) continue
     try {
-      const ev = decodeEventLog({ abi: LAUNCHPAD_ABI, data: log.data, topics: log.topics })
-      const a = Object.fromEntries(Object.entries(ev.args).map(([k, v]) => [k, typeof v === 'bigint' ? (k.toLowerCase().includes('token') && k !== 'token' ? fmtTok(v) : fmt(v)) : v]))
-      events.push({ event: ev.eventName, ...a })
-    } catch { /* not ours */ }
+      const ev = decodeEventLog({ abi: pad.abi, data: log.data, topics: log.topics })
+      const a = Object.fromEntries(Object.entries(ev.args).map(([k, v]) => {
+        if (typeof v !== 'bigint') return [k, v]
+        const lk = k.toLowerCase()
+        if (lk.includes('token') && k !== 'token' && !lk.includes('amount')) return [k, fmtTok(v)]
+        return [k, fmt(v)]
+      }))
+      events.push({ event: ev.eventName, pad: pad.id, ...a })
+    } catch { /* */ }
   }
   return { hash, status: r.status, block: Number(r.blockNumber), events }
 }

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 })
+    }
+  }
+}