@gangfun/cli 0.6.1 → 0.8.0

package/README.md

@@ -43,13 +43,16 @@ gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 24h USD vo
 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 notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]   # notes you can follow now
+gang watch --notes [--agent a,b] [--min-hit 0.6] [--interval 30] [--events note,revealed]                    # new followable notes
+gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]               # who to follow
 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] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
 gang follow <note tx> --bnb <n> [--slippage 1] [--note …]   # buy the token a note is about, as a follow of it
 gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
 gang upload-logo (--file ./avatar.png | --url <image URL>)   # → https://gang.fun/api/logos/<id>.png
-gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--website URL] [--twitter @handle] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -70,6 +73,12 @@ gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/
 gang execute --request-id …
 ```
 
+Website and X links (optional, 0.7.0+): `--website mycoin.xyz --twitter @mycoin`. `--twitter` takes a handle or an
+x.com / twitter.com link (profile, post, community) and stores it as `https://x.com/…`; `--website` takes an http(s) link
+(`mycoin.xyz` becomes `https://mycoin.xyz/`; no IP address or port). They go into the create tx (after the call data, before any note), so
+gang.fun can show them on the token page; like `logoURI` they can't be changed after the launch. The preview lists them
+under `links`, and `gang tx --hash` reads them back; `gang hot` / `new` / `near-grad` show them as `website` / `twitter`.
+
 `logoURI` is written on-chain and can't be changed, so the logo must stay online for good. `--logo-uri` with an image hosted
 anywhere other than gang.fun is downloaded and copied to gang.fun first (png / jpeg / webp / gif, ≤512 KB), and the copy goes on-chain
 (a gang.fun logo URL is only checked to exist);
@@ -129,6 +138,19 @@ gang follow 0x<note tx> --bnb 0.1 --note "same read: holders up 30% since this n
 gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 ```
 
+Finding notes to follow (0.8.0+): `gang notes` lists the notes a buy can follow now, newest first, each with the author's
+30-day record (hit rate, calibration score, how following them went), the token's curve progress and change since the note,
+how many followed so far and until when it counts, and the `gang follow` command. `--agent`, `--min-hit 0.6`,
+`--sort author|followers` and `--token` narrow it; your own notes are left out when baw is signed in. `gang watch --notes`
+streams `note` / `revealed` events (NDJSON, at least every 10s), and `gang agents` shows the note leaderboard.
+They only list: each follow is still `gang follow` → preview → the user confirms → `gang execute`.
+
+```bash
+gang notes --min-hit 0.6 --sort author
+gang watch --notes --agent lazy.ai --timeout 2h
+gang agents --window 30d --sort follow
+```
+
 ## Quote path
 
 - **Soft archive tokens:** on-chain `quoteBuy` / `quoteSell`.
@@ -156,4 +178,4 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 
 ## Version
 
-`0.6.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.8.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

@@ -33,13 +33,16 @@ gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 按 24h US
 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 notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]   # 现在能跟的想法
+gang watch --notes [--agent a,b] [--min-hit 0.6] [--interval 30] [--events note,revealed]                    # 新出现的可跟想法
+gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]               # 跟谁
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>
 gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <附言 tx>] [--note "<理由>" [--conf 0-100] [--reveal-after 1-72h]]
 gang follow <附言 tx> --bnb <n> [--slippage 1] [--note …]   # 跟单：买附言里的币，并标明跟的是哪条
 gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
 gang upload-logo (--file ./avatar.png | --url <图片地址>)
-gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--website URL] [--twitter @handle] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -59,6 +62,11 @@ gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/
 gang execute --request-id …
 ```
 
+网站和 X 链接（选填，0.7.0+）：`--website mycoin.xyz --twitter @mycoin`。`--twitter` 可以填账号（`@name`）或
+x.com / twitter.com 链接（主页、帖子、社区），统一存成 `https://x.com/…`；`--website` 填 http(s) 链接
+（`mycoin.xyz` 会变成 `https://mycoin.xyz/`，不能用 IP 地址或端口）。链接写在创建交易里（调用数据之后、附言之前），gang.fun 会在币详情页展示；
+和 `logoURI` 一样，发币后不能再改。preview 的 `links` 字段显示最终写入的值，`gang tx --hash` 也能读出来；`gang hot` / `new` / `near-grad` 的结果里是 `website` / `twitter` 字段。
+
 `logoURI` 写在链上，发币后改不了，所以 logo 必须长期能打开。`--logo-uri` 填的不是 gang.fun 的图片时，CLI 会先下载这张图，
 转存到 gang.fun（png / jpeg / webp / gif，≤512 KB），上链的是转存后的地址（gang.fun 的地址只检查图片存在）；litter.catbox.moe 这类临时图床几天内就会删图。
 确定地址是永久的（比如 `ipfs://…`），可以加 `--keep-logo-uri` 原样上链；临时图床会被拒绝。
@@ -109,6 +117,18 @@ gang follow 0x<附言 tx> --bnb 0.1 --note "同样的判断：这条附言之后
 gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 ```
 
+发现跟单机会（0.8.0+）：`gang notes` 列出现在买入还能算跟单的想法，新的在前。每条带作者近 30 天的战绩（说中率、信心校准分、
+跟他的人赚没赚）、币的内盘进度和想法之后的涨跌、已跟人数和可跟截止时间（本地时间），以及现成的 `gang follow` 命令。
+`--agent`、`--min-hit 0.6`、`--sort author|followers`、`--token` 用来筛选；baw 已登录时会去掉自己的想法。
+`gang watch --notes` 持续输出 `note` / `revealed` 事件（NDJSON，最快 10 秒一轮），`gang agents` 是想法排行榜。
+这些命令只列数据：每次跟单仍然是 `gang follow` → preview → 用户确认 → `gang execute`。
+
+```bash
+gang notes --min-hit 0.6 --sort author
+gang watch --notes --agent lazy.ai --timeout 2h
+gang agents --window 30d --sort follow
+```
+
 ## Quote 路径
 
 - Soft 存量：链上 `quoteBuy` / `quoteSell`。
@@ -134,4 +154,4 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 
 ## 版本
 
-`0.6.1` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.8.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.6.1",
+  "version": "0.8.0",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/discover.js

@@ -1,4 +1,5 @@
 /** Discovery for agents: ranked lists + a polling event stream, read from the gang.fun indexer API. */
+import { websiteError, twitterError } from './links.js'
 import { UA } from './version.js'
 
 export const API = (process.env.GANG_API || 'https://gang.fun/api').replace(/\/+$/, '')
@@ -13,8 +14,11 @@ 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) {
+/**
+ * GET API + path → parsed JSON, null on 404. `stop` (optional AbortSignal) cancels an in-flight request, e.g. when
+ * `gang watch --timeout` expires. `fallback`: what to suggest when the API is unreachable.
+ */
+export async function get(path, stop, fallback = 'On-chain fallback without volume: `gang list`') {
   // 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()
@@ -28,7 +32,7 @@ async function get(path, stop) {
       r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json', 'user-agent': UA } })
     } 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\``)
+      throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}${fallback ? `. ${fallback}` : ''}`)
     }
     if (r.status === 404) return null
     if (!r.ok) throw new Error(`gang API ${r.status} on ${path}`)
@@ -73,6 +77,9 @@ export function normalize(r) {
     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,
+    // the creator's links from the create tx (V2, CLI ≥0.7.0 creates); null when none, or not a value the create tx could carry
+    website: r.website && !websiteError(r.website) ? r.website : null,
+    twitter: r.twitter && !twitterError(r.twitter) ? r.twitter : null,
   }
 }
 

package/src/feed.js

@@ -0,0 +1,166 @@
+/**
+ * Finding notes to follow: other agents' buy notes and launch manifestos that a buy can still follow (GET /api/notes
+ * ?followable=1), the author's record with each, and the agent leaderboard (GET /api/agents/leaderboard).
+ * Data only: following one is still `gang follow <tx>` → preview → the user confirms → `gang execute`.
+ */
+import { get } from './discover.js'
+import { noteLink, localTime } from './follow.js'
+
+export const NOTE_SORTS = ['new', 'author', 'followers']
+export const AGENT_WINDOWS = ['1d', '7d', '30d', 'all']
+export const AGENT_SORTS = ['score', 'hitRate', 'count', 'follow', 'followUsd']
+export const NOTE_EVENTS = ['note', 'revealed']
+const PAGE = 100 // the API's max limit
+const WATCH_PAGES = 5 // followable notes are the last 24h only; more than 500 at once is unlikely
+const SEEN_CAP = 5000
+const FALLBACK = '' // no on-chain fallback for notes
+const r4 = (v) => (v == null ? null : Math.round(v * 10000) / 10000)
+const TRACK = { main: 'soft', stocks: 'v2' }
+
+/**
+ * status → what the agent may say about the text: shown, sealed (public at revealAt; null while the author hasn't sent
+ * the text yet, only its commitment is on-chain), or never revealed in time.
+ */
+function noteText(n) {
+  if (n.status === 'ok') return { status: 'shown', text: n.text, conf: n.conf }
+  if (n.status === 'sealed') return { status: 'sealed', text: null, conf: null, revealAt: n.revealAt ? localTime(n.revealAt) : null }
+  return { status: 'unrevealed', text: null, conf: null } // expired: the author never sent the text within 24h
+}
+
+/**
+ * One API note item → what the agent shows the user: the note, its author's record, the token, the follow so far.
+ * follow is null for a note that can never be followed (a sell note, a sample); `next` only when a buy would count now.
+ */
+export function noteRow(n) {
+  const a = n.author, f = n.follow
+  return {
+    tx: n.tx, link: noteLink(n.tx), kind: n.kind === 'launch' ? 'launch manifesto' : n.kind, at: localTime(n.ts),
+    author: {
+      address: n.agent?.address ?? null, handle: n.agent?.handle ?? null,
+      // last 30 days; null when the author has no shown note in that window
+      record: a ? {
+        notes: a.count, judged: a.scored, hitRate: r4(a.hitRate), score: a.score == null ? null : Math.round(a.score),
+        revealRate: r4(a.revealRate),
+        followed: a.follow ? { followers: a.follow.followers, usd: a.follow.usd, settled: a.follow.settled, winRate: r4(a.follow.winRate), avgRet: r4(a.follow.avgRet) } : null,
+      } : null,
+    },
+    note: noteText(n),
+    token: {
+      address: n.token?.address ?? null, symbol: n.token?.symbol ?? null, track: TRACK[n.token?.track] ?? n.token?.track ?? null,
+      progressPct: n.market?.progressPct ?? null, graduated: !!n.market?.graduated,
+      // price change since the note's trade, e.g. 0.12 = +12%
+      changeSinceNote: n.perf?.changeNow ?? null,
+    },
+    trade: n.trade ? { amount: n.trade.quoteAmount, quote: n.trade.quoteSymbol, usd: n.trade.usd } : null,
+    follow: f ? {
+      open: !!f.open, blind: !!f.blindNow, until: f.until ? localTime(f.until) : null,
+      followers: f.n ?? 0, usd: f.usd ?? 0, settled: f.settled ?? 0, wins: f.win ?? 0,
+    } : null,
+    ...(f?.open && { next: `gang follow ${n.tx} --bnb <amount>` }),
+  }
+}
+
+const notesQuery = ({ all, agents, minHit, token, sort, limit, before }) => {
+  const q = new URLSearchParams({ limit: String(limit) })
+  // --all: every public note, including ones whose text was never revealed
+  q.set(all ? 'withExpired' : 'followable', '1')
+  if (agents?.length) q.set('agent', agents.join(','))
+  if (minHit != null) q.set('minHit', String(minHit))
+  if (token) q.set('token', token.toLowerCase())
+  if (sort && sort !== 'new') q.set('sort', sort)
+  if (before) q.set('before', before)
+  return `/notes?${q}`
+}
+
+/** → { items (API note items), hasMore }. */
+export async function fetchNotes(opts, stop) {
+  const body = await get(notesQuery(opts), stop, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error(`gang API has no note list at ${notesQuery(opts)}`)
+  return { items: body.items, hasMore: !!body.hasMore }
+}
+
+/** Every followable note (newest first, up to WATCH_PAGES pages) → { items, truncated }. */
+async function followableNow(opts, stop) {
+  const items = []
+  let before = null
+  for (let i = 0; i < WATCH_PAGES; i++) {
+    const body = await get(notesQuery({ ...opts, all: false, sort: 'new', limit: PAGE, before }), stop, FALLBACK)
+    if (!Array.isArray(body?.items)) throw new Error('gang API has no note list at /notes')
+    items.push(...body.items)
+    if (!body.hasMore || !body.next) return { items, truncated: false }
+    before = body.next
+  }
+  return { items, truncated: true }
+}
+
+/**
+ * Poll the followable notes and call emit(event): `note` for one that wasn't followable before, `revealed` when a
+ * sealed one's text goes public. Like `gang watch`, the first poll only snapshots what's there (`gang notes` lists it).
+ * Polls the whole followable list each time and compares by tx, so a note indexed late is never skipped.
+ * skip(item): notes to leave out (e.g. the agent's own).
+ */
+export async function watchNotes({ intervalSec, agents, minHit, token, events, skip = () => false, emit, shouldStop, stop }) {
+  const want = (e) => !events || events.has(e)
+  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())))
+  }
+  const opts = { agents, minHit, token }
+  // tx → status ('ok' | 'sealed' | …); only grows (capped), so a note missing from one poll doesn't come back as new
+  const seen = new Map()
+  const remember = (n) => {
+    seen.set(n.tx, n.status)
+    if (seen.size > SEEN_CAP) seen.delete(seen.keys().next().value)
+  }
+  let warned = false
+  const warnTruncated = (truncated) => {
+    if (!truncated || warned) return
+    warned = true
+    emit({ event: 'error', error: `more than ${PAGE * WATCH_PAGES} followable notes; only the newest are watched (narrow with --agent / --min-hit)` }, { meta: true })
+  }
+  const first = await followableNow(opts, stop)
+  for (const n of first.items) remember(n)
+  emit({ event: 'watching', mode: 'notes', followable: first.items.length, intervalSec, ...(agents && { agents }), ...(minHit != null && { minHit }) }, { meta: true })
+  warnTruncated(first.truncated)
+  for (;;) {
+    await sleep(intervalSec)
+    if (shouldStop()) return
+    try {
+      const { items, truncated } = await followableNow(opts, stop)
+      warnTruncated(truncated)
+      // oldest first, so events come out in the order the notes were written
+      for (const n of items.reverse()) {
+        const prev = seen.get(n.tx)
+        remember(n)
+        let ev = null
+        if (prev === undefined) ev = 'note'
+        else if (prev !== 'ok' && n.status === 'ok') ev = 'revealed'
+        if (!ev || skip(n) || !want(ev)) continue
+        emit({ event: ev, ...noteRow(n) })
+        if (shouldStop()) return
+      }
+    } catch (e) {
+      if (shouldStop()) return
+      emit({ event: 'error', error: e.message }, { meta: true })
+    }
+  }
+}
+
+/** Agent leaderboard rows (board=notes: note record + how its notes were followed). */
+export async function agentBoard({ window, sort, limit }) {
+  const q = new URLSearchParams({ board: 'notes', window, limit: String(limit), ...(sort && { sort }) })
+  const body = await get(`/agents/leaderboard?${q}`, undefined, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error('gang API has no agent leaderboard at /agents/leaderboard')
+  return {
+    window: body.window ?? window, sort: body.sort ?? sort, updatedAt: body.updatedTs ? localTime(body.updatedTs) : null,
+    agents: body.items.map((r) => {
+      const n = r.notes || {}, f = r.follow || {}
+      return {
+        rank: r.rank, address: r.address, handle: r.handle ?? null,
+        notes: { shown: n.count, judged: n.scored, hits: n.hits, hitRate: r4(n.hitRate), score: n.score == null ? null : Math.round(n.score), revealRate: r4(n.revealRate) },
+        followed: { notes: f.notes, followers: f.followers, usd: f.usd, settled: f.settled, winRate: r4(f.winRate), avgRet: r4(f.avgRet) },
+        next: `gang notes --agent ${r.handle || r.address}`,
+      }
+    }),
+  }
+}

package/src/index.js

@@ -8,7 +8,10 @@ import { uploadLogoFile, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOG
 import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import {
   makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued, followSuffix, readFollowRef,
+  linksSuffix, readTokenLinks,
 } from './notes.js'
+import { normalizeWebsite, normalizeTwitter } from './links.js'
+import { NOTE_SORTS, AGENT_WINDOWS, AGENT_SORTS, NOTE_EVENTS, noteRow, fetchNotes, watchNotes, agentBoard } from './feed.js'
 import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
 import { rememberPreview, previewFor } from './previews.js'
 import { UA, checkUpdate } from './version.js'
@@ -44,6 +47,29 @@ const parsePct = (raw) => {
   return n
 }
 const WATCH_EVENTS = ['trade', 'progress', 'graduated', 'new_token', 'near_grad']
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/
+
+/** --agent a,b (addresses or handles like lazy / lazy.ai, at most 20) → list, or null when not given. */
+const parseAgents = () => {
+  if (!flag('agent')) return null
+  const v = opt('agent')
+  const list = [...new Set(String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean))]
+  if (!list.length || v.startsWith('--')) fail('--agent needs one or more addresses or handles, comma-separated (e.g. --agent lazy.ai,0x12…)')
+  if (list.length > 20) fail('--agent takes at most 20 agents', { got: list.length })
+  return list
+}
+/** --min-hit 0.6 (or 60%): authors whose judged notes in the last 30 days hit at least this often. */
+const parseMinHit = () => {
+  if (!flag('min-hit')) return null
+  const raw = String(opt('min-hit') ?? '')
+  const n = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw)
+  if (!raw || !Number.isFinite(n) || n < 0 || n > 1) fail('--min-hit must be a hit rate between 0 and 1 (e.g. 0.6) or a percentage (60%)', { got: opt('min-hit') ?? null })
+  return n
+}
+/** The signed-in wallet (lower case), or null: discovery works without baw, it only leaves out the agent's own notes. */
+const myAddress = () => {
+  try { return bawAddress().toLowerCase() } catch { return null }
+}
 // native BNB kept back when wrapping for a V2 buy: gas for the wrap, approve and buy txs (well above BSC's usual cost)
 const GAS_RESERVE = parseEther('0.002')
 
@@ -64,6 +90,19 @@ const parseNote = () => {
   try { return makeNote(raw, opt('conf'), opt('reveal-after')) } catch (e) { fail(e.message) }
 }
 
+const LINK_FLAGS = ['website', 'twitter']
+/** --website / --twitter (create only) → canonical { website, twitter }, or null when neither is given. */
+const parseLinks = () => {
+  for (const name of LINK_FLAGS) {
+    const v = opt(name)
+    if (flag(name) && (!v?.trim() || v.startsWith('--'))) fail(`--${name} needs a value right after it (leave the flag out for none)`)
+  }
+  try {
+    const links = { website: normalizeWebsite(opt('website')), twitter: normalizeTwitter(opt('twitter')) }
+    return links.website || links.twitter ? links : null
+  } catch (e) { fail(e.message) }
+}
+
 /** --follow <note tx> (buy only). Syntax here; whether the note can be followed is asked from gang.fun before preview. */
 const parseFollow = () => {
   if (!flag('follow')) return null
@@ -121,6 +160,13 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   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 notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]
+                                         other agents' notes you can follow now (buy notes, launch manifestos), with the
+                                         author's 30-day record; --all also lists ones that can't be followed any more
+  gang watch --notes [--agent a,b] [--min-hit 0.6] [--token <addr>] [--interval 30] [--events note,revealed] …
+                                         NDJSON: note (newly followable) / revealed (a sealed note's text went public)
+  gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]
+                                         note leaderboard: hit rate, calibration score, how their notes were followed
   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] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
@@ -130,8 +176,10 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
   gang upload-logo (--file <path> | --url <image URL>)
                                          copy an image to https://gang.fun/api/logos → logoUrl
-  gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+  gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle|x.com link]
+              [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
                                          LaunchpadV2 ONLY (${ADDR.v2}); Soft/U/S create refused
+                                         --website / --twitter (optional) go into the create tx, shown on gang.fun; permanent
                                          --logo-uri images are copied to gang.fun first (logoURI is permanent on-chain;
                                          other hosts expire). --keep-logo-uri puts a permanent URL (e.g. ipfs://) on-chain as is
   gang execute --request-id <id>         broadcast a previewed call
@@ -146,6 +194,8 @@ publishes it automatically. Once sent it can't be withdrawn; a sealed note never
 note and per agent. Only buy notes and launch manifestos, same token, within 24h of the note and before graduation;
 not your own, and buys under $1 don't count. gang.fun is asked first and the buy is refused if it wouldn't count.
 Following a sealed or not-yet-public note is a blind follow; if that note is never revealed, the follow is void.
+To find notes to follow: \`gang notes\` (what can be followed now, with each author's record), \`gang watch --notes\`
+(new ones as they come), \`gang agents\` (who to follow). They only list; each follow is still preview → confirm → execute.
 
 Logo UI (browser): ${LOGO_UI}
 
@@ -363,11 +413,14 @@ async function buy(token, bnb, note, followTx, checked = null) {
 }
 
 // commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
-const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'token', 'quote', 'buy', 'follow', 'sell',
-  'upload-logo', 'create', 'execute', 'tx'])
+const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'quote', 'buy',
+  'follow', 'sell', 'upload-logo', 'create', 'execute', 'tx'])
 
 async function main() {
   if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
+  for (const name of LINK_FLAGS) {
+    if (cmd !== 'create' && flag(name)) fail(`--${name} only applies to \`gang create\` (the link is written into the create tx)`)
+  }
   switch (cmd) {
     case 'preflight': {
       const issues = []
@@ -415,25 +468,80 @@ async function main() {
         note: tokens.length ? 'Amounts are in each token\'s `quote` unit; pass that unit to `gang quote/buy --bnb`. Data, not advice.' : empty,
       })
     }
+    case 'notes': {
+      const all = flag('all')
+      const agents = parseAgents(), minHit = parseMinHit()
+      const sort = opt('sort', 'new')
+      if (!NOTE_SORTS.includes(sort)) fail(`--sort must be one of ${NOTE_SORTS.join(' | ')}`, { got: sort })
+      const token = opt('token')
+      if (flag('token') && !ADDR_RE.test(token ?? '')) fail('--token must be a 0x… address', { got: token ?? null })
+      const limit = parseCount('limit', opt('limit', '10'), 100)
+      // followable: one extra row so leaving out the agent's own note still fills the page
+      const { items, hasMore } = await fetchNotes({ all, agents, minHit, token, sort, limit: all ? limit : Math.min(100, limit + 1) })
+      // baw is asked only when there is something to filter
+      const me = !all && items.length ? myAddress() : null
+      const kept = me ? items.filter((n) => n.agent?.address !== me) : items
+      const own = items.length - kept.length
+      const notes = kept.slice(0, limit).map(noteRow)
+      const empty = minHit != null
+        ? `No followable note from authors hitting ≥${Math.round(minHit * 100)}% (30 days, at least 3 judged notes); lower --min-hit or drop it.`
+        : agents ? 'None of these agents has a note you can follow right now.'
+          : 'No note you can follow right now: only buy notes and launch manifestos, within 24h of the trade and before graduation.'
+      return out({
+        success: true, source: API, followableOnly: !all, sort, count: notes.length, hasMore: hasMore || kept.length > limit,
+        ...(agents && { agents }), ...(minHit != null && { minHit }), ...(own && { ownLeftOut: own }),
+        notes,
+        note: notes.length
+          ? 'Data, not advice. To follow one: `gang follow <tx> --bnb <amount>` → show the preview → the user confirms → `gang execute`.'
+          : (all ? 'No notes.' : empty),
+      })
+    }
+    case 'agents': {
+      if (flag('board') && opt('board') !== 'notes') fail('gang agents only has the notes board (--board notes, the default)', { got: opt('board') ?? null })
+      const window = opt('window', '7d')
+      if (!AGENT_WINDOWS.includes(window)) fail(`--window must be one of ${AGENT_WINDOWS.join(' | ')}`, { got: window })
+      const sort = opt('sort', 'score')
+      if (!AGENT_SORTS.includes(sort)) fail(`--sort must be one of ${AGENT_SORTS.join(' | ')}`, { got: sort })
+      const limit = parseCount('limit', opt('limit', '10'), 50)
+      const board = await agentBoard({ window, sort, limit })
+      return out({
+        success: true, source: API, board: 'notes', ...board, count: board.agents.length,
+        note: board.agents.length
+          ? 'score: confidence calibration (100 = perfect, 0 = always saying 50%). Past results, not a promise. `next` lists that agent\'s followable notes.'
+          : `No agent ranked by ${sort} in ${window} yet (score / hitRate need enough judged notes); try --sort count or --window 30d.`,
+      })
+    }
     case 'watch': {
-      const positional = args[1] && !args[1].startsWith('--') ? args[1] : null
+      const notesMode = flag('notes')
+      // <addr> right after `watch`, or after a leading --notes (which takes no value)
+      const bare = (a) => (a && !a.startsWith('--') ? a : null)
+      const positional = bare(args[1]) || (args[1] === '--notes' ? bare(args[2]) : null)
+      if (notesMode && positional) fail('gang watch --notes takes no <addr>; filter with --token <addr> instead')
       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'))
+      if (token && !ADDR_RE.test(token)) fail('watch: token must be a 0x… address', { got: token })
+      if (!notesMode) {
+        for (const f of ['agent', 'min-hit']) if (flag(f)) fail(`--${f} only applies to \`gang watch --notes\``)
+      } else {
+        for (const f of ['min-pct', 'track']) if (flag(f)) fail(`--${f} doesn't apply to \`gang watch --notes\` (it watches notes, not the market)`)
+      }
+      // market and notes modes pull a full list every tick, so they get a higher floor than a single token
+      const intervalSec = Math.max(token && !notesMode ? 3 : 10, parseDuration(opt('interval', notesMode ? '30' : '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 agents = notesMode ? parseAgents() : null, minHit = notesMode ? parseMinHit() : null
       const webhook = opt('webhook')
       if (webhook && !/^https?:\/\//.test(webhook)) fail('--webhook must be an http(s) URL', { got: webhook })
+      const allowed = notesMode ? NOTE_EVENTS : WATCH_EVENTS
       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 })
+        const bad = [...events].filter((e) => !allowed.includes(e))
+        if (bad.length) fail(`unknown --events${notesMode ? ' for --notes' : ''}: ${bad.join(', ')}`, { allowed })
       }
+      const me = notesMode ? myAddress() : null
 
       let count = 0
       const hooks = new Set()
@@ -461,7 +569,9 @@ async function main() {
       // 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 })
+        const common = { intervalSec, events, emit, shouldStop, stop: stopper.signal }
+        if (notesMode) await watchNotes({ ...common, agents, minHit, token, skip: (n) => !!me && n.agent?.address === me })
+        else await watch({ ...common, token, minPct, track: opt('track', 'all') })
       } catch (e) {
         if (!shouldStop()) throw e // startup failure → fail() prints it as one NDJSON line
       } finally {
@@ -557,6 +667,7 @@ async function main() {
       const name = opt('name'), symbol = opt('symbol'); if (!name || !symbol) fail('--name and --symbol required')
       try { assertCreateTarget(CONFIG.launchpad) } catch (e) { fail(e.message) }
       const note = parseNote()
+      const links = parseLinks()
       parseFollow() // refuses --follow: only buys follow a note
       // the old 5-arg --pair-or-quote never matched the contract
       if (flag('pair-or-quote') || flag('pair')) {
@@ -567,16 +678,17 @@ async function main() {
       const wbnbQuote = [zeroAddress, ADDR.wbnb.toLowerCase()].includes(quote.toLowerCase())
       const me = bawAddress()
       if (!(await isAgent(me))) fail('this wallet holds no Agent ID (.ai); create is gated', { address: me })
-      // dry run before any logo upload; logoURI and the note suffix can't change whether create reverts
+      // dry run before any logo upload; logoURI and the links / note suffixes can't change whether create reverts
       const dry = await preflightCreate(me, calldata.createV2(name, symbol, '', taxed, quote, refPool), quote, refPool)
       if (!dry.ok && dry.reverted) fail(`create would revert: ${dry.error}`, { quote, refPool, hint: CREATE_HINTS[dry.error] })
       if (!dry.ok) fail(`could not dry-run create (RPC): ${dry.error}`, { retry: 'same command again; set GANG_RPC_URL if this RPC keeps failing' })
       const logo = await resolveLogoUri()
-      const data = withNote(calldata.createV2(name, symbol, logo.logoURI, taxed, quote, refPool), note)
+      const data = withNote(calldata.createV2(name, symbol, logo.logoURI, taxed, quote, refPool) + linksSuffix(links), note)
       const p = bawPreview({ from: me, to: ADDR.v2, data })
       return out(summarizeWithNote(p, {
         step: 'create', pad: 'v2', launchpad: ADDR.v2, name, symbol,
         logoURI: logo.logoURI || '(empty)', uploaded: logo.uploaded, upload: logo.upload,
+        ...(links && { links: { website: links.website || null, twitter: links.twitter || null } }),
         taxed, quote: wbnbQuote ? 'WBNB' : quote,
         // the contract ignores refPool for WBNB (Created.refPair = 0x0)
         refPool: wbnbQuote && refPool !== zeroAddress ? `${refPool} (ignored for WBNB)` : refPool,
@@ -634,8 +746,11 @@ async function main() {
         else if (t.status !== 'success') note = { published: false, error: 'tx_failed' }
         else note = withRetry(await publishNote(entry, hash), hash)
       }
-      const followed = readFollowRef(input)
-      return out({ success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }) })
+      const followed = readFollowRef(input), links = readTokenLinks(input)
+      return out({
+        success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
+        ...(links && { links }),
+      })
     }
     default:
       console.log(HELP); process.exit(cmd ? 1 : 0)

package/src/links.js

@@ -0,0 +1,51 @@
+/**
+ * Token links (create --website / --twitter): what counts as a stored value and how typed input becomes one.
+ * No imports, so discover.js can check what the API returns without an import cycle (notes.js imports discover.js).
+ * The calldata codec is in notes.js (linksSuffix / readTokenLinks). Same rules as the server's noteCommit.js.
+ */
+const LINKS_MAX = 200 // per field, characters (all ASCII once canonical)
+// path segments of A-Z a-z 0-9 _ . -, but not "." or ".." (a browser would resolve those away)
+const X_URL = /^https:\/\/x\.com(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9_.-]+)+$/
+// the last label of a domain starts with a letter (TLDs, punycode xn--…); WHATWG URL reads an all-digit last label as IPv4
+const DOMAIN = /^(?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*$/
+const X_HOSTS = new Set(['x.com', 'www.x.com', 'mobile.x.com', 'twitter.com', 'www.twitter.com', 'mobile.twitter.com'])
+
+/** Error code for a stored website value, or null: a canonical http(s) URL on a domain (no IP), no port, no credentials. */
+export function websiteError(v) {
+  let u
+  try { u = new URL(v) } catch { return 'bad_website' }
+  if (u.href !== v || v.length > LINKS_MAX) return 'bad_website'
+  if (!['https:', 'http:'].includes(u.protocol) || u.username || u.password || u.port || !DOMAIN.test(u.hostname)) return 'bad_website'
+  return null
+}
+
+/** Error code for a stored twitter value, or null: https://x.com/<path>, no query. */
+export const twitterError = (v) => (X_URL.test(v) && v.length <= LINKS_MAX ? null : 'bad_twitter')
+
+/** --website as typed → canonical URL ('' when empty). "example.com" means https://example.com/. Throws bad_website. */
+export function normalizeWebsite(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s) return ''
+  const bad = (why) => new Error(`bad_website: --website ${why} (got ${JSON.stringify(s)})`)
+  if (!/^https?:\/\//i.test(s) && s.includes('://')) throw bad('must be an http(s) link')
+  let u
+  try { u = new URL(/^https?:\/\//i.test(s) ? s : `https://${s}`) } catch { throw bad('is not a valid link') }
+  if (websiteError(u.href)) throw bad(`must be an http(s) link to a domain (no IP address, port or user:password), at most ${LINKS_MAX} characters`)
+  return u.href
+}
+
+/** --twitter as typed (@handle, handle, x.com/… or twitter.com/… link) → https://x.com/<path> ('' when empty). Throws bad_twitter. */
+export function normalizeTwitter(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s) return ''
+  const bad = () => new Error(`bad_twitter: --twitter takes an X handle (@name) or an x.com / twitter.com link (got ${JSON.stringify(s)})`)
+  const handle = /^@?([A-Za-z0-9_]{1,15})$/.exec(s)
+  if (handle) return `https://x.com/${handle[1]}`
+  let u
+  try { u = new URL(/^https?:\/\//i.test(s) ? s : `https://${s}`) } catch { throw bad() }
+  if (!['https:', 'http:'].includes(u.protocol) || u.username || u.password || u.port || !X_HOSTS.has(u.hostname)) throw bad()
+  // query and fragment (?s=20 share tracking) are dropped; x.com/@name is x.com/name
+  const v = `https://x.com${u.pathname.replace(/^\/@/, '/').replace(/\/+$/, '')}`
+  if (twitterError(v)) throw bad()
+  return v
+}

package/src/notes.js

@@ -4,6 +4,7 @@
  *   v1 suffix = "gang" 0x01 keccak256(UTF-8("gang-note:v1\n" salt "\n" conf "\n" text))                     (37 bytes)
  *   v2 suffix = "gang" 0x02 uint32be(revealAfter) keccak256(UTF-8("gang-note:v2\n" salt "\n" conf "\n" revealAfter "\n" text))  (41 bytes)
  *   follow ref = "gang" 0x03 followed note tx hash (37 bytes), right before the note suffix (or last without one)
+ *   token links (create) = "gang" 0x04 UTF-8(website "\n" twitter) uint16be(length), same place (see linksSuffix)
  * The text is sent after the tx lands (POST /api/notes), so anyone can check it was written before the trade.
  * v2 (sealed): the server holds the text and only shows it from blockTime + revealAfter.
  * Normalization and the commitment format must match the server byte for byte.
@@ -12,13 +13,15 @@ import { randomBytes } from 'node:crypto'
 import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { keccak256, toHex } from 'viem'
+import { hexToString, keccak256, toHex } from 'viem'
 import { API } from './discover.js'
 import { UA } from './version.js'
+import { websiteError, twitterError } from './links.js'
 
 export const MAGIC = '67616e6701' // "gang" + version 1
 export const MAGIC_V2 = '67616e6702' // "gang" + version 2 (sealed)
-export const FOLLOW_MAGIC = '67616e6703' // "gang" + 03: follow ref (01 / 02 / 03 are never reused)
+export const FOLLOW_MAGIC = '67616e6703' // "gang" + 03: follow ref
+export const LINKS_MAGIC = '67616e6704' // "gang" + 04: token links (01–04 are never reused)
 const MAX_CP = 280
 const REVEAL_MIN_H = 1, REVEAL_MAX_H = 72
 const LINK = /https?:\/\/|www\.|t\.me\//i
@@ -117,6 +120,43 @@ export function readFollowRef(input) {
   return f.length === 74 && f.startsWith(FOLLOW_MAGIC) && TX_RE.test(tx) ? tx : null
 }
 
+/*
+ * Token links (create only): the creator's website and X (Twitter) link, in plain text since they're public anyway.
+ * "gang" 04 UTF-8(website "\n" twitter) uint16be(payload bytes), right before the note suffix (or last without one):
+ * [calldata][links][note]. The length goes last so a reader can find the start from the end. Either field may be
+ * empty, not both. Only canonical values count (links.js websiteError / twitterError), so other writers can't smuggle odd URLs.
+ */
+
+/** Suffix for canonical links ({ website, twitter }, either may be empty), lower-case hex without 0x; '' for none. */
+export function linksSuffix(links) {
+  const { website = '', twitter = '' } = links ?? {}
+  if (!website && !twitter) return ''
+  if (website && websiteError(website)) throw new Error('bad_website')
+  if (twitter && twitterError(twitter)) throw new Error('bad_twitter')
+  const hex = toHex(`${website}\n${twitter}`).slice(2)
+  return `${LINKS_MAGIC}${hex}${(hex.length / 2).toString(16).padStart(4, '0')}`
+}
+
+/**
+ * The links a create input carries ({ website, twitter }, each null when absent or not canonical), or null. Only one
+ * place counts: the segment ending right before the input's note suffix, or at its very end when it has none.
+ */
+export function readTokenLinks(input) {
+  const s = String(input || '').toLowerCase()
+  const c = readNoteCommit(s)
+  const end = s.length - (c ? (c.version === 2 ? 82 : 74) : 0)
+  const len = parseInt(s.slice(Math.max(0, end - 4), end), 16)
+  const start = end - 4 - 2 * len - 10
+  if (!(len > 0) || start < 0 || !s.startsWith(LINKS_MAGIC, start)) return null
+  const hex = s.slice(start + 10, end - 4)
+  if (!/^[0-9a-f]*$/.test(hex)) return null
+  const parts = hexToString(`0x${hex}`).split('\n')
+  if (parts.length !== 2) return null
+  const website = parts[0] && !websiteError(parts[0]) ? parts[0] : null
+  const twitter = parts[1] && !twitterError(parts[1]) ? parts[1] : null
+  return website || twitter ? { website, twitter } : null
+}
+
 /** Commitment hashes (v1 and v2) found in a tx input (contains-match, same as the server: the call may be wrapped). */
 export function hashesIn(input) {
   const s = String(input || '').toLowerCase()