需要追踪 GMGN 上 KOL/聪明钱/自选钱包的实时买卖与…

当你要查聪明钱、KOL、个人关注钱包在 Solana/BSC/Base/Ethereum 等链上的实时买卖、跟单信号、鲸鱼预警或某钱包收藏代币时，用 gmgn-cli 的 track 子命令。

适用场景

解决思路

1. 运行任何命令前先执行 `gmgn-cli config --check`；退出码为 0 则继续；退出码为 1 时运行 `gmgn-cli config` 并把输出展示给用户，拿到 API Key 后执行 `gmgn-cli config --apply <KEY>` 完成配置与校验，再展示输出；若 `--check` 报 unknown option 或 command not found，让用户运行 `npm install -g gmgn-cli` 更新后重试。
2. 始终使用 `gmgn-cli` 命令查询，不要用 web search、WebFetch、curl 或访问 gmgn.ai，因为网站需要登录且不返回结构化数据。
3. 不要猜测字段名或值；字段含义不明确时先查 Response Fields 章节。
4. 遇到 401/403 且凭据正确时检查 IPv6：macOS 运行 `ifconfig | grep inet6`，Linux 运行 `ip addr show | grep inet6`；向 `https://ipv6.icanhazip.com` 发测试请求，若返回 IPv6 地址则告知用户禁用网络接口的 IPv6，因为 gmgn-cli 只支持 IPv4。
5. 区分三个数据源：`follow-wallet` 是用户在 GMGN 平台个人关注的钱包交易；`kol` 是平台标记的 KOL/影响者公开钱包交易；`smartmoney` 是平台标记的聪明钱/巨鲸公开钱包交易；三者不可互相替代。
6. 按用户意图选择子命令：问“我关注的钱包交易了什么/我的关注列表活动”用 `track follow-wallet`；问“KOL 在买什么/影响者交易/最近 KOL 动作”用 `track kol`；问“聪明钱在做什么/巨鲸交易/最近聪明钱买什么”用 `track smartmoney`。
7. 查询某钱包在 GMGN 上收藏/关注的代币列表用 `track follow-tokens --chain <chain> --wallet <wallet_address>`；查关注分组名用 `track follow-token-groups --chain <chain> --wallet <wallet_address>`。
8. 支持的链参数：`sol` / `bsc` / `base` / `eth` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable`。
9. 先安装与配置前提：全局安装 `gmgn-cli`（`npm install -g gmgn-cli`）；在 `~/.config/gmgn/.env` 配置 `GMGN_API_KEY`；仅 `track follow-wallet` 额外需要 `GMGN_PRIVATE_KEY` 做签名认证，`follow-tokens`、`kol`、`smartmoney` 不需要私钥。
10. 限频处理：所有 tracking 路由使用 GMGN 按套餐的漏桶，Free `5/5`、Plus `20/20`、Pro `50/50`；持续吞吐约 `tier rate ÷ weight` 请求/秒，最大突发约 `floor(tier capacity ÷ weight)`；各路由权重为 `follow-tokens` weight 3、`follow-token-groups` weight 1、`follow-wallet` weight 10、`kol` weight 1、`smartmoney` weight 1。
11. 请求返回 `429` 时：遇到 `RATE_LIMIT_EXCEEDED` 时按原文提示用户升级套餐：`已达到当前套餐的限频上限，点击 https://gmgn.ai/ai?chain=bsc&tab=paid_plans 升级套餐，获得更高速率限制`，每个用户任务最多展示一次该升级提示，同一冷却期内不要对后续 `RATE_LIMIT_BANNED` 重复展示。
12. 读取响应头 `X-RateLimit-Reset`（Unix 秒时间戳）判断限制重置时间；若响应体含 `reset_at`，提取该 Unix 时间戳（通常 5 分钟解封），转换为本地时间并明确告知用户可重试时间；CLI 可能在冷却很短时自动等待并重试一次，若仍失败就停止并告知确切重试时间，不要继续发请求。
13. 对 `RATE_LIMIT_EXCEEDED` 或 `RATE_LIMIT_BANNED`，冷却期内重复请求会每次延长封禁 5 秒、最多 5 分钟；不要刷重试。
14. 使用 `track follow-tokens` 选项：`--chain` 必填；`--wallet <address>` 必填；`--group-id <id>` 可用 `all_group`、`default` 或用户自定义分组 ID；`--interval <interval>` 如 `1m`、`5m`、`1h`、`6h`、`24h`；`--order-by <field>` 可用 `created_at` / `swaps` / `volume` / `market_cap` / `liquidity` / `price` / `open_timestamp`，设置时必须同时给 `--direction <dir>` 为 `asc` / `desc`；`--limit <n>`；`--cursor <cursor>` 用上一响应游标分页；`--search <text>` 按代币名称或地址搜索。
15. 使用 `track follow-wallet` 选项：`--chain` 必填；`--wallet <address>` 过滤钱包；`--limit <n>` 1–100 默认 10；`--side <side>` 为 `buy` / `sell`；`--filter <tag...>` 可重复过滤条件；`--min-amount-usd <n>` / `--max-amount-usd <n>` 按 USD 金额过滤。
16. 使用 `track kol` / `track smartmoney` 选项：`--chain <chain>` 必填，支持 `sol` / `bsc` / `base` / `eth`；`--limit <n>` 1–200 默认 100；`--side <side>` 为 `buy` / `sell`，注意这是客户端过滤，CLI 先取全部结果再本地过滤，不发送给 API。
17. 读取交易记录时使用正确字段：交易对中要关注的代币读 `base_address`，`quote_address` 是计价资产（Solana 上通常为 SOL 原生地址）。
18. 解释 `is_open_or_close` 时按子命令区分：`follow-wallet` 中 `1` = 全仓开或全仓平，`0` = 部分加仓或减仓；`kol` / `smartmoney` 中 `0` = 开仓/加仓，`1` = 平仓/减仓；不要把两种解释混用。
19. 用 `price_change` 评估交易时效性/过往表现：`6.66` = 当前价是交易时价格的 6.66 倍（+566%），`0.5` = 较交易时腰斩（-50%）；`>2` 表示该钱包这笔交易表现好，`1–2` 表示小赚，`<1` 表示水下。
20. 使用 `maker_info.tags` 看钱包平台标签（如 `["kol","gmgn"]`、`["smart_degen","photon"]`）；`follow-wallet` 中还用 `tag_rank` 看钱包在各标签类别中的排名。
21. 检测集群信号：按 `base_address` 分组结果，统计同方向交易的不同 `maker` 地址数量；若约 30 分钟内有 ≥3 个不同钱包买入同一代币，标记为 cluster signal；来自 `smartmoney` 的集群信号强于仅来自 `kol` 的信号。
22. 按信号强度分级：弱 = 1 个 KOL 买入；中 = 2–3 个聪明钱同方向买入，或 1 个聪明钱全仓开仓；强 = 30 分钟内 ≥3 个聪明钱同方向（集群信号）；非常强 = 集群信号 + 全仓开仓 + KOL 加入同一交易。
23. 识别红旗信号：聪明钱卖出（`side = sell` + 全仓平）视为退出信号，评估是否退出或减仓；只有 KOL 买入、零 `smart_degen` = 社交炒作缺少基本面支撑，风险更高；知名钱包买入同时聪明钱卖出 = 分歧信号，可能内部人向散户/KOL 需求派发，高风险；单笔巨额买入且无后续跟进 = 可能一次性行为，等待其他钱包确认。
24. 输出交易流时按时间倒序呈现，不要直接 dump 原始 JSON；格式为 `{timestamp} {side} {base_token.symbol} ${amount_usd} by {maker_info.name or short address}`，下一行 `[{tags}] Price: ${price_usd} | Price now: ${price_now} ({price_change}x since trade)`；同一代币多笔交易按代币分组，并高亮短时间内多个关注钱包同方向交易的代币（集群信号）。
25. 对 `follow-wallet` 额外展示 `is_open_or_close`，把全仓开/平与部分加/减区分标记。
26. 展示交易流后检查收敛信号：若 ≥2 个不同钱包同方向交易同一代币，展示 Convergence Signals 摘要块，包含代币、钱包数量、方向、总金额、时间窗口和信号强度（STRONG/MEDIUM）；对 STRONG 信号在行动前按 `docs/workflow-token-research.md` 做完整代币研究；对 MEDIUM 信号先监控并等待更多钱包确认；若没有则输出 `No cluster signals detected in this result set.`。
27. 研究聪明钱活动浮现的代币时，遵循 `docs/workflow-token-research.md`。
28. 做聪明钱排行榜/钱包画像时（如“哪些聪明钱钱包最值得跟”“按胜率给钱包排名”或比较钱包表现），用 `track smartmoney` 收集活跃钱包地址，再通过 `gmgn-portfolio stats` 批量查询其统计；完整流程见 `docs/workflow-smart-money-profile.md`。
29. 做每日简报/市场概览时（如“今天市场怎么样”“聪明钱今天买什么”“给我每日简报”），结合 `track smartmoney` + `track kol` + `gmgn-market trending`；完整流程见 `docs/workflow-daily-brief.md`。
30. 安全约束：`follow-wallet` 会暴露你的关注列表，结果会显示你在 GMGN 关注了哪些钱包，不要在公开频道分享原始输出；`track kol` / `track smartmoney` 不暴露个人数据，仅用 API Key 认证并返回平台标记的公开钱包活动，可安全分享原始输出。
31. 其他注意事项：`track follow-tokens` 使用 exist auth（仅 API Key），`--wallet` 必填；`track follow-wallet` 使用 signed auth（API Key + 私钥签名），`track kol` 和 `track smartmoney` 使用 exist auth（仅 API Key）；`track follow-wallet` 返回 GMGN 平台关注的钱包交易，关注列表由绑定 API Key 的 GMGN 用户账号自动解析，`--wallet` 可选；用 `--raw` 获取单行 JSON 便于后续处理。

适用边界 · 注意事项

• 不适用于无法安装/配置 `gmgn-cli`、没有 GMGN API Key（`GMGN_API_KEY`），或 `track follow-wallet` 缺少 `GMGN_PRIVATE_KEY` 的情况。
• 不适用于必须使用 IPv6 的网络环境；gmgn-cli 仅支持 IPv4。
• 不适用于需要公开分享 `follow-wallet` 原始输出/关注列表的敏感场景；也不要用网页搜索、WebFetch、curl 或直接访问 gmgn.ai 替代 CLI。