@gangfun/cli 0.40.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DEVELOPERS.md CHANGED
@@ -116,6 +116,7 @@ capitalization). Existing tokens keep their addresses. A suffix alone does not p
116
116
  | `NO_AGENT_ID` | This wallet has no Agent ID |
117
117
  | `DEV_MODE_OFF`, `TRADE_ALL_TOKENS_OFF` | A wallet setting (from `gang preflight`) |
118
118
  | `NETWORK` | An RPC or the API can't be reached: retry a read later |
119
+ | `NO_FUNDS` (0.41.0+) | The wallet can't pay for this trade: `fund` says how to top it up; nothing was sent |
119
120
  | `REVERT` | The simulation or the chain refused it |
120
121
  | A contract error name (such as `NotAgent`) | That contract error |
121
122
  | A lower-case word (such as `not_found`) | A specific refusal: `error` explains it |
@@ -114,6 +114,7 @@ Pad 3.0 的 owner 启用 `abcd` 部署器后,CLI 会为曲线、打新、铸
114
114
  | `NO_AGENT_ID` | 这个钱包没有 Agent ID |
115
115
  | `DEV_MODE_OFF`、`TRADE_ALL_TOKENS_OFF` | 钱包设置问题(来自 `gang preflight`) |
116
116
  | `NETWORK` | RPC 或 API 连不上,读操作可以稍后重试 |
117
+ | `NO_FUNDS`(0.41.0+) | 钱包余额不够这笔交易:`fund` 写了怎么充值;什么都没发出 |
117
118
  | `REVERT` | 模拟执行或链上拒绝了这笔交易 |
118
119
  | 合约错误名(如 `NotAgent`) | 对应的合约错误 |
119
120
  | 小写单词(如 `not_found`) | 具体的拒绝原因,见 `error` |
package/README.md CHANGED
@@ -369,7 +369,8 @@ timed-out `gang_execute`, check `gang_status` / the wallet history instead of ex
369
369
  From 0.24.0 the CLI counts how it is used, anonymously, so gang.fun can see where agents get stuck before a first trade.
370
370
  Each command adds one event:
371
371
  - the command name (and subcommand), the names of the flags given (never their values);
372
- - whether it succeeded, and if not, a short error code (`NO_AGENT_ID`, `DEV_MODE_OFF`, a Binance risk code, `USAGE`…);
372
+ - whether it succeeded, and if not, a short error code (`NO_AGENT_ID`, `DEV_MODE_OFF`, a Binance risk code, `USAGE`…); from
373
+ 0.41.0 a Binance code also carries the wallet's error name, an upper-case constant such as `SERVICE_ERROR`;
373
374
  - for `gang preflight`, which checks passed;
374
375
  - the agent host's name, when known (0.31.0+): the MCP client's own name (such as `claude-code`), or `GANG_CLIENT`. Only a
375
376
  short name made of letters, digits, spaces, `-` and `_` goes out; anything else is sent as `other`.
package/README.zh-CN.md CHANGED
@@ -317,7 +317,7 @@ Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要
317
317
 
318
318
  从 0.24.0 起,CLI 会匿名统计使用情况,让 gang.fun 知道 agent 在第一笔交易之前卡在哪一步。每条命令记一条事件:
319
319
  - 命令名(和子命令)、用到的参数名(不含参数值);
320
- - 是否成功;失败时带一个简短的错误码(`NO_AGENT_ID`、`DEV_MODE_OFF`、币安风控码、`USAGE` 等);
320
+ - 是否成功;失败时带一个简短的错误码(`NO_AGENT_ID`、`DEV_MODE_OFF`、币安风控码、`USAGE` 等);从 0.41.0 起,币安的错误码后面还会带上钱包返回的错误名(全大写常量,如 `SERVICE_ERROR`);
321
321
  - `gang preflight` 另记各项检查是否通过;
322
322
  - Agent 客户端名称(已知时,0.31.0+):MCP 客户端自己的名称(如 `claude-code`),或 `GANG_CLIENT`。只发送由字母、数字、空格、`-` 和 `_`
323
323
  组成的短名称,其他内容一律记为 `other`。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gangfun/cli",
3
- "version": "0.40.0",
3
+ "version": "0.41.0",
4
4
  "mcpName": "io.github.gangfun/gang",
5
5
  "description": "Gang launchpad CLI for Binance Agentic Wallet agents: create on GangLaunchpad (untaxed or tax tokens), 打新 fair mint, PancakeSwap pool trades, LaunchpadV2 and legacy Soft/U/S trade.",
6
6
  "type": "module",
package/src/flags.js CHANGED
@@ -19,6 +19,8 @@ export const CREATE_ACCEPTS = new Set([
19
19
  ...LAUNCH_FLAGS, 'slippage', 'use-wbnb',
20
20
  // refused further on, each with its own reason
21
21
  'follow', 'cover', 'taxed', 'pair', 'pair-or-quote', 'hours',
22
+ // every result is JSON already: agents add --json out of habit, so it is accepted and changes nothing
23
+ 'json',
22
24
  ])
23
25
 
24
26
  // every flag a buy's code reads, whatever the token's kind: a buy refuses the rest, since a misspelled --promoter would fall
@@ -26,7 +28,7 @@ export const CREATE_ACCEPTS = new Set([
26
28
  export const BUY_ACCEPTS = new Set([
27
29
  'agent', 'all', 'amount', 'bnb', 'board', 'break-bond', 'break-call-bond', 'buy-tax', 'calldata', 'cap', 'conf', 'confirm-out',
28
30
  'description', 'dev-buy', 'dev-cut', 'dev-shares', 'dividend', 'events', 'exit-fee', 'fair', 'file', 'file-logo',
29
- 'fly', 'follow', 'from', 'grad', 'guard', 'hash', 'hold', 'hours', 'include-graduated', 'interval',
31
+ 'fly', 'follow', 'from', 'grad', 'guard', 'hash', 'hold', 'hours', 'include-graduated', 'interval', 'json',
30
32
  'keep-logo-uri', 'kind', 'limit', 'logo', 'logo-file', 'logo-uri', 'max-age', 'max-events', 'min-hit', 'min-pct',
31
33
  'min-shares', 'mint-fee', 'name', 'no-post-mint', 'no-promoter', 'note', 'notes', 'pair', 'pair-or-quote', 'path', 'pay-bnb',
32
34
  'pending', 'poll', 'post-mint', 'preset', 'promoter', 'quote', 'raise', 'recipient', 'ref', 'ref-pool',
package/src/help.js ADDED
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `gang buy --help`, `gang create -h`: whether argv (after `gang`) asks a command for its help. The CLI answers with the
3
+ * help text, and the MCP server's gang_cli points to gang_help. A --help / -h right after a flag whose value may be free
4
+ * text is that value, not a request for help. No imports: the MCP server loads this too.
5
+ */
6
+ const TEXT_FLAGS = new Set(['--note', '--description', '--name', '--symbol'])
7
+
8
+ export const wantsHelp = (argv) => argv.some((a, i) => i > 0 && (a === '--help' || a === '-h') && !TEXT_FLAGS.has(argv[i - 1]))
package/src/index.js CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  CONFIG, ADDR, listTokens, tokenInfo, quoteBuy, quoteSell, isAgent, balanceOf, allowance,
4
4
  calldata, decodeTx, decodeLogs, firstByModuleType, parseEther, fmt, fmtTok, resolvePad, isAddress, client,
5
5
  } from './chain.js'
6
+ import { wantsHelp } from './help.js'
6
7
  import { baw, bawAddress, bawError, bawFailed, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
7
8
  import { uploadLogoFile, uploadMetadata, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, ipfsCid, ipfsUri, isIpfsUri, cdnUrl, LOGO_UI } from './logo.js'
8
9
  import { API, fetchMarket, get as apiGet, rank, watch, parseDuration } from './discover.js'
@@ -59,6 +60,7 @@ const out = (o) => {
59
60
  if (o && typeof o === 'object' && o.success === false) {
60
61
  process.exitCode = 1 // fail() exits 1 too: a refused send can't look like a success to a script
61
62
  if (!o.code) o = { ...o, code: codeOf(o) }
63
+ if (o.code === 'NO_FUNDS' && !o.fund) o = { ...o, fund: /^not enough (BNB|WBNB)\b/.test(String(o.error ?? '')) ? FUND_HINT : FUND_TOKEN_HINT }
62
64
  }
63
65
  if (refInfo && o && typeof o === 'object' && !('ref' in o)) o = { ...o, ref: refInfo }
64
66
  // a failed result built no tx, so it claims no tag; a bad id is always said
@@ -1405,6 +1407,14 @@ function create() {
1405
1407
  // after a clean preflight: where a first trade usually starts
1406
1408
  // gang.fun's setup page: every preflight issue code, step by step, for the user to open on their phone (gang-web-legacy /start)
1407
1409
  const SETUP_GUIDE = 'https://gang.fun/start'
1410
+ // a wallet that can't pay: what to tell the user (gang preflight prints the wallet's address)
1411
+ const FUND_HOW = 'send BNB on BNB Smart Chain (BEP-20) to the Agentic Wallet address (gang preflight shows it), keeping about 0.002 BNB more than the trade for gas'
1412
+ const FUND_HINT = `Top up: ${FUND_HOW}; then run the same command again. Nothing was sent.`
1413
+ // a token that pays in an ERC-20 quote (USDT, GANG, …): that token, plus BNB for gas
1414
+ const FUND_TOKEN_HINT = 'Top up: send the token this trade pays in (see need / have) on BNB Smart Chain (BEP-20) to the Agentic Wallet address '
1415
+ + '(gang preflight shows it), plus about 0.002 BNB for gas; then run the same command again. Nothing was sent.'
1416
+ // below this a wallet can't make a first small buy plus gas: preflight warns, without failing
1417
+ const LOW_BNB = parseEther('0.005')
1408
1418
  const PREFLIGHT_NEXT = [
1409
1419
  'gang trending: what other agents buy now',
1410
1420
  'gang notes --min-hit 0.6: followable calls by authors who hit 60%+',
@@ -1500,6 +1510,12 @@ async function pendingReport() {
1500
1510
  }
1501
1511
 
1502
1512
  async function main() {
1513
+ // agents ask a command for its help (gang buy --help, gang create -h): answer with the help, not an unknown-flag refusal
1514
+ if (cmd !== 'help' && wantsHelp(args)) {
1515
+ record(args, { success: true })
1516
+ console.log(HELP)
1517
+ return
1518
+ }
1503
1519
  if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
1504
1520
  // streams and the MCP server print no single result: count the start (MCP tools run this CLI, so each one counts itself)
1505
1521
  if (cmd === 'watch' || cmd === 'mcp') record(args, { success: true })
@@ -1614,26 +1630,39 @@ async function main() {
1614
1630
  const issues = []
1615
1631
  const status = bawStatus()
1616
1632
  if (status !== 'CONNECTED') issues.push({ code: 'NOT_SIGNED_IN', fix: 'Run `baw auth signin` and confirm in the Binance App.' })
1617
- let me = null, settings = null, agent = false
1633
+ let me = null, settings = null, agent = false, balance = null, balanceCut = false
1618
1634
  if (status === 'CONNECTED') {
1619
1635
  me = bawAddress(); settings = bawSettings()
1620
1636
  if (!settings.devMode?.enabled) issues.push({ code: 'DEV_MODE_OFF', fix: 'Enable Developer Mode in Binance App → Agentic Wallet settings.' })
1621
1637
  if (!settings.tradeAllTokens) issues.push({ code: 'TRADE_ALL_TOKENS_OFF', fix: 'Enable "Trade all tokens" in Binance App → Agentic Wallet settings, otherwise SELLING Gang tokens is blocked by risk control (buying still works).' })
1638
+ // the BNB balance, read beside the Agent ID check (after the last baw call, which blocks the event loop). Capped at
1639
+ // 3 s: with every RPC down, the transport's retries would hold preflight for far longer. Null when unread
1640
+ const cap = new Promise((r) => { const t = setTimeout(() => { balanceCut = true; r(null) }, 3000); t.unref?.() })
1641
+ balance = Promise.race([client.getBalance({ address: me }), cap]).catch(() => null)
1622
1642
  agent = await createGateAgent(me)
1623
1643
  if (!agent) issues.push({ code: 'NO_AGENT_ID', fix: 'Claim a .ai Agent ID in Binance Wallet (Agent ID banner). Gang only lets Agent ID holders buy/create.' })
1624
1644
  }
1625
1645
  // after the baw calls: they block the event loop, and the fetch's short timeout would run out meanwhile
1626
1646
  const hot = trendingBlock({ wallet: me })
1627
- return out({
1647
+ // an empty wallet is the next stop after setup: say so now, as a warning (setup itself is done)
1648
+ const bnb = balance && await balance
1649
+ const warnings = bnb != null && bnb < LOW_BNB
1650
+ ? [{ code: 'LOW_BNB', fix: 'Top up before the first trade: send BNB on BNB Smart Chain (BEP-20) to the address above, keeping about 0.002 BNB more than the trade for gas.' }]
1651
+ : []
1652
+ out({
1628
1653
  success: issues.length === 0, cliVersion: VERSION, status, address: me,
1629
1654
  // `launchpad` = createPad: kept for readers of the old field (it used to be the V2 create target)
1630
1655
  launchpad: padNets('v3').mainnet.pad, createPad: padNets('v3').mainnet.pad, createPadGen: padNets('v3').mainnet.gen, isAgent: agent,
1631
1656
  devMode: settings?.devMode?.enabled ?? null, tradeAllTokens: settings?.tradeAllTokens ?? null, issues,
1657
+ ...(bnb != null && { bnb: fmt(bnb) }), ...(warnings.length && { warnings }),
1632
1658
  note: 'New create → GangLaunchpad (gang create = gang v3 create; gang fair create for 打新). LaunchpadV2 / Soft / U / S take no new tokens: existing buy / sell only.',
1633
1659
  ...(!issues.length && { next: PREFLIGHT_NEXT }),
1634
1660
  ...(issues.length && { guide: { url: SETUP_GUIDE, note: 'Step-by-step setup (Agentic Wallet, Agent ID, Developer Mode, Trade all tokens) for the user to open on their phone; give it with the fixes.' } }),
1635
1661
  ...await hot.then((t) => (t ? { trending: t } : {})),
1636
1662
  })
1663
+ // the cut-off read is still pending and would keep the process (and an MCP host waiting on it) alive: exit once printed
1664
+ if (balanceCut) process.stdout.write('', () => process.exit(process.exitCode ?? 0))
1665
+ return
1637
1666
  }
1638
1667
  case 'list': {
1639
1668
  // --kind v3 / fair: GangLaunchpad tokens (from gang.fun); without it the V2 / Soft / U / S pads, as before
package/src/mcp.js CHANGED
@@ -10,6 +10,7 @@ import { homedir } from 'node:os'
10
10
  import { delimiter, dirname, join, sep } from 'node:path'
11
11
  import { createInterface } from 'node:readline'
12
12
  import { fileURLToPath } from 'node:url'
13
+ import { wantsHelp } from './help.js'
13
14
  import { clientOf } from './telemetry.js'
14
15
  import { VERSION } from './version.js'
15
16
 
@@ -235,6 +236,8 @@ export function invalid(t, a) {
235
236
  }
236
237
  }
237
238
  if (t.name === 'gang_cli' && Object.hasOwn(NOT_VIA_CLI, a.args[0])) return NOT_VIA_CLI[a.args[0]]
239
+ // gang buy --help prints plain text, which this tool can't return: the help is gang_help's (a --help after a text flag is its value)
240
+ if (t.name === 'gang_cli' && wantsHelp(a.args)) return NOT_VIA_CLI.help
238
241
  if (t.name === 'gang_watch') {
239
242
  const mode = a.mode || (a.token ? 'token' : 'market')
240
243
  if (mode === 'token' && !a.token) return 'mode token needs token'
package/src/telemetry.js CHANGED
@@ -66,6 +66,9 @@ export function codeOf(o = {}) {
66
66
  if (/^this wallet holds no Agent ID/i.test(msg)) return 'NO_AGENT_ID' // this wallet's: an inviter's is a usage matter
67
67
  if (/baw auth signin|not signed in/i.test(msg)) return 'NOT_SIGNED_IN'
68
68
  if (/unreachable|timed out|fetch failed|ECONN|ENOTFOUND|API 5\d\d|RPC error|data unavailable/i.test(msg)) return 'NETWORK'
69
+ // the wallet can't pay: a new wallet's usual first stop, worth telling apart from a broken command
70
+ // (BNB, WBNB, a quote's symbol such as USDT, or "quote"; case-sensitive, so a sell's "not enough tokens" stays apart)
71
+ if (/^not enough (BNB|WBNB|quote\b|[A-Z][A-Z0-9]{1,11}\b)/.test(msg)) return 'NO_FUNDS'
69
72
  if (/revert/i.test(msg)) return 'REVERT'
70
73
  // the command itself is wrong: a flag named, or a form the CLI asks for. State errors ("needs at least 3000 shares") are not
71
74
  if (/^--|^usage|^pass |^give |^use either |^unknown |^gang .*\b(needs|takes)\b|--[a-z][a-z-]+ must|must be (a|an|one|between) /i.test(msg)) return 'USAGE'
@@ -95,7 +98,18 @@ export function eventOf(argv, o = {}) {
95
98
  ? { signedIn: o.status === 'CONNECTED', agent: o.isAgent ?? null, dev: o.devMode ?? null, all: o.tradeAllTokens ?? null }
96
99
  : null
97
100
  const cl = clientOf()
98
- return { t: Math.floor(Date.now() / 1000), c, s, f, ok, code: ok ? '' : codeOf(o), pf, ...(cl && { cl }) }
101
+ return { t: Math.floor(Date.now() / 1000), c, s, f, ok, code: ok ? '' : eventCode(o), pf, ...(cl && { cl }) }
102
+ }
103
+
104
+ /**
105
+ * The event's code: codeOf, plus baw's error name after a numeric baw code (953401:SOME_NAME), so a refusal can be read
106
+ * without the message. The name is baw's constant (an upper-case word), never text.
107
+ */
108
+ function eventCode(o) {
109
+ const code = codeOf(o)
110
+ const name = String(o.errorName ?? '')
111
+ if (!/^\d{1,10}$/.test(code) || !/^[A-Z][A-Z0-9_]{1,30}$/.test(name)) return code
112
+ return `${code}:${name}`.slice(0, 48)
99
113
  }
100
114
 
101
115
  let recorded = false