gmgn-track

运行任何命令前：先执行 gmgn-cli config --check。如果退出码为 0，则正常进行。如果退出码为 1，则 (1) 运行 gmgn-cli config 并向用户展示输出；(2) 用户提供 API Key 后，运行 gmgn-cli config --apply <KEY> 完成配置和验证，然后向用户展示输出。如果 --check 返回错误（未知选项或命令未找到），请告知用户运行 npm install -g gmgn-cli 进行更新，然后重试。

重要提示：始终使用下面的 gmgn-cli 命令。不要使用网络搜索、WebFetch、curl 或访问 gmgn.ai 来获取这些数据——网站需要登录且不会返回结构化数据。CLI 是唯一正确的方法。

重要提示：不要猜测字段名或字段值。当某个字段的含义不明确时，请先查阅下方“响应字段”部分，然后再使用。

⚠️ 不支持 IPv6：如果遇到 401 或 403 错误且凭据看起来正确，请立即检查 IPv6：(1) 列出所有网络接口及其 IPv6 地址——运行 ifconfig | grep inet6（macOS）或 ip addr show | grep inet6（Linux）；(2) 向 https://ipv6.icanhazip.com 发送测试请求——如果响应是 IPv6 地址，则出站流量正在通过 IPv6。立即告知用户：“请禁用网络接口上的 IPv6——gmgn-cli 命令仅支持 IPv4。”

根据用户请求，使用 gmgn-cli 工具查询链上追踪数据。

核心概念

• follow-wallet vs kol vs smartmoney —— 三种不同的数据来源。follow-wallet 返回用户个人在 GMGN 平台上关注的钱包的交易记录（用户特定；关注列表从绑定 API Key 的 GMGN 用户账户解析）。kol 和 smartmoney 返回平台标记的公共钱包列表的交易记录（非用户特定）。切勿互相替代。

• KOL（关键意见领袖） —— 在 GMGN 上被公开识别为影响者或知名交易者的钱包。在平台的钱包标签系统中标记为 renowned。他们的交易带有社交/营销信号，不一定是 Alpha。

• 聪明钱（smart_degen） —— 具有统计上可证明的盈利交易记录的钱包，由 GMGN 算法识别。与 gmgn-token 中的 smart_degen 概念相同。他们的交易是比 KOL 交易更强的 Alpha 信号。

• is_open_or_close —— 指示交易是否为全仓事件。不同子命令的解释不同：

  • follow-wallet：1 = 全仓开仓或平仓；0 = 部分加仓或减仓。
  • kol / smartmoney：0 = 开仓/加仓；1 = 平仓/减仓。
    不要对两个子命令应用相同的解释。

• price_change —— 自交易以来价格变化的比率。6.66 表示代币当前价格是交易时的 6.66 倍（即 +566%）。0.5 表示价格自交易以来减半（-50%）。用于评估“这笔交易表现如何”。

• base_address vs quote_address —— 在交易对中，base_address 是正在买卖的代币；quote_address 是计价代币（在 Solana 上通常是 SOL 原生地址）。要获取感兴趣的代币，始终读取 base_address。

• maker_info.tags —— 钱包的平台标签数组（例如 ["kol", "gmgn"]、["smart_degen", "photon"]）。一个钱包可以携带多个标签。使用 tag_rank（仅 follow-wallet）查看钱包在每个标签类别中的排名。

• 集群信号 —— 当多个关注/追踪的钱包在短时间内以相同方向交易同一代币时，这是比单个钱包更强的确信信号。当结果中出现这种模式时，请突出显示。

何时使用哪个子命令：

• track follow-wallet —— 用户问“我关注的钱包交易了什么？”、“显示我的关注列表交易”、“显示我关注的钱包活动” → 需要用户在 GMGN 平台上关注的钱包
• track kol —— 用户问“KOL 在买什么？”、“显示影响者交易”、“KOL 最近在做什么” → 返回已知 KOL 钱包的交易
• track smartmoney —— 用户问“聪明钱在做什么？”、“显示巨鲸交易”、“聪明钱最近在买什么” → 返回聪明钱/巨鲸钱包的交易

不要混淆这三者：

• follow-wallet = 用户在 GMGN 上个人关注的钱包
• kol = 平台标记的 KOL/影响者钱包（非用户特定）
• smartmoney = 平台标记的聪明钱/巨鲸钱包（非用户特定）

子命令

子命令	描述
track follow-tokens	某个钱包的关注代币列表——钱包在 GMGN 上收藏的代币，包含完整市场数据
track follow-token-groups	某个钱包的关注代币分组名称——钱包用于组织关注代币的分组名称和 ID
track follow-wallet	用户在 GMGN 上个人关注的钱包的交易记录
track kol	GMGN 标记的 KOL/影响者钱包的实时交易
track smartmoney	GMGN 标记的聪明钱/巨鲸钱包的实时交易

支持的链

sol / bsc / base / eth / robinhood

注意：track kol 和 track smartmoney 不支持 robinhood——它们仅接受 sol / bsc / base / eth。

前置条件

• 全局安装 gmgn-cli —— 如果缺失，运行：npm install -g gmgn-cli
• 在 ~/.config/gmgn/.env 中配置 GMGN_API_KEY —— 所有子命令都需要
• GMGN_PRIVATE_KEY —— 仅 track follow-wallet 需要（签名认证）；follow-tokens、kol 或 smartmoney 不需要

速率限制处理

本技能使用的所有追踪路由都经过 GMGN 的漏桶限制器，rate=20 且 capacity=20。持续吞吐量约为 20 ÷ weight 请求/秒，最大突发约为 floor(20 ÷ weight)（当桶满时）。

命令	路由	权重
track follow-tokens	GET /v1/user/follow_tokens	3
track follow-token-groups	GET /v1/user/follow_token_groups	1
track follow-wallet	GET /v1/trade/follow_wallet	3
track kol	GET /v1/user/kol	1
track smartmoney	GET /v1/user/smartmoney	1

当请求返回 429 时：

• 从响应头中读取 X-RateLimit-Reset。它是一个 Unix 时间戳（秒），表示限制预计重置的时间。
• 如果响应体包含 reset_at（例如 {"code":429,"error":"RATE_LIMIT_BANNED","message":"...","reset_at":1775184222}），提取 reset_at——它是禁令解除的 Unix 时间戳（通常为 5 分钟）。转换为本地时间并告知用户确切的重试时间。
• 当剩余冷却时间较短时，CLI 可能会自动等待并重试一次。如果仍然失败，请停止并告知用户确切的重试时间，而不是发送更多请求。
• 对于 RATE_LIMIT_EXCEEDED 或 RATE_LIMIT_BANNED，在冷却期间重复请求可能会使禁令每次延长 5 秒，最多 5 分钟。不要频繁重试。

使用示例

# 查询某个钱包在 SOL 上的关注代币列表
gmgn-cli track follow-tokens --chain sol --wallet <wallet_address>

# 查询 BSC 上的关注代币列表，原始 JSON 输出
gmgn-cli track follow-tokens --chain bsc --wallet <wallet_address> --raw

# 查询某个钱包在 SOL 上的关注代币分组名称
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address>

# 查询关注代币分组名称，原始 JSON 输出
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address> --raw

# 关注钱包的交易（所有你关注的钱包）
gmgn-cli track follow-wallet --chain sol

# 按钱包筛选的关注钱包交易
gmgn-cli track follow-wallet --chain sol --wallet <wallet_address>

# 按交易方向筛选的关注钱包交易
gmgn-cli track follow-wallet --chain sol --side buy

# 按 USD 金额范围筛选的关注钱包交易
gmgn-cli track follow-wallet --chain sol --min-amount-usd 100 --max-amount-usd 10000

# KOL 交易记录（SOL，默认）
gmgn-cli track kol --limit 10 --raw

# SOL 上的 KOL 交易记录，仅买入
gmgn-cli track kol --chain sol --side buy --limit 10 --raw

# 聪明钱交易记录（SOL，默认）
gmgn-cli track smartmoney --limit 10 --raw

# 聪明钱交易记录，仅卖出
gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw

track follow-tokens 选项

选项	描述
--chain	必需。sol / bsc / base / eth / robinhood
--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>	当设置了 --order-by 时必需。asc / desc
--limit <n>	每页数量
--cursor <cursor>	来自前一次响应的分页游标
--search <text>	按代币名称或地址搜索

track follow-tokens 响应字段

顶层字段：

字段	描述
cursor	用于获取下一页的不透明游标
all_following	关注代币总数
is_recommend	结果是否包含推荐代币
followings	关注代币对象数组

followings 中的每个项包含：

字段	描述
address	代币合约地址
symbol	代币交易符号
name	代币名称
chain	代币所在的链
price	当前代币价格
price_change_percent	价格变化百分比
volume	交易量
liquidity	池流动性
market_cap	市值
swaps	总交换次数
group_ids	该代币所属的关注分组
open_timestamp	交易开放时的 Unix 时间戳

track follow-token-groups 选项

选项	描述
--chain	必需。sol / bsc / base / eth / robinhood
--wallet <address>	必需。要查询的钱包地址

track follow-token-groups 响应字段

data 是一个数组。每个项包含：

字段	描述
chain	分组所在的链
group_id	分组标识符（例如 default 或用户自定义 ID）
group_name	人类可读的分组名称
rank	显示顺序/排序排名

track follow-wallet 选项

选项	描述
--chain	必需。sol / bsc / base / eth / robinhood
--wallet <address>	按钱包地址筛选
--limit <n>	每页数量（1–100，默认 10）
--side <side>	交易方向：buy / sell
--filter <tag...>	可重复的筛选条件
--min-amount-usd <n>	最小交易金额（USD）
--max-amount-usd <n>	最大交易金额（USD）

track kol / track smartmoney 选项

选项	描述
--chain <chain>	必需。链：sol / bsc / base / eth
--limit <n>	每页数量（1–200，默认 100）
--side <side>	按交易方向筛选：buy / sell（客户端筛选——获取结果后在本地应用）

track follow-wallet 响应字段

顶层字段：

字段	描述
next_page_token	用于获取下一页结果的不透明令牌
list	交易记录数组

list 中的每个项包含：

字段	描述
id	记录 ID（base64 编码，用作游标）
chain	链名称（例如 sol）
transaction_hash	链上交易哈希
maker	被关注钱包的地址
side	交易方向：buy 或 sell
base_address	代币合约地址
quote_address	报价代币地址（在 SOL 上买卖时为 SOL 原生地址）
base_amount	代币数量（最小单位）
quote_amount	花费/收到的报价代币数量（例如 SOL）
amount_usd	交易金额（USD）
cost_usd	与 amount_usd 相同——此交易腿的 USD 价值
buy_cost_usd	原始买入成本（USD）（如果此记录本身就是买入，则为 0）
price	交易时代币以报价代币计价的价格
price_usd	交易时代币的 USD 价格
price_now	代币当前 USD 价格
price_change	自交易以来的价格变化比率（例如 6.66 = +666%）
timestamp	交易的 Unix 时间戳
is_open_or_close	1 = 全仓开仓或平仓；0 = 部分加仓或减仓
launchpad	发射台显示名称（例如 Pump.fun）
launchpad_platform	发射台平台标识符（例如 Pump.fun、pump_agent）
migrated_pool_exchange	代币迁移到的 DEX（如果有），例如 pump_amm；未迁移则为空
base_token.symbol	代币交易符号
base_token.logo	代币 Logo 图片 URL
base_token.hot_level	热度等级（0 = 正常，越高越热门）
base_token.total_supply	代币总供应量（字符串）
base_token.token_create_time	代币创建时的 Unix 时间戳
base_token.token_open_time	交易开放时的 Unix 时间戳（如果尚未迁移/开放则为 0）
maker_info.address	被关注钱包地址
maker_info.name	钱包显示名称
maker_info.twitter_username	Twitter / X 用户名
maker_info.twitter_name	Twitter / X 显示名称
maker_info.tags	钱包标签数组（例如 ["kol","gmgn"]）
maker_info.tag_rank	标签 → 在该类别中的排名映射（例如 {"kol": 854}）
balance_info	钱包代币余额信息；不可用时为 null

track kol / track smartmoney 响应字段

响应是一个包含 list 数组的对象。list 中的每个项包含：

字段	描述
transaction_hash	链上交易哈希
maker	交易者钱包地址（KOL / 聪明钱）
side	交易方向：buy 或 sell
base_address	代币合约地址
base_token.symbol	代币交易符号
base_token.launchpad	发射台平台（例如 pump）
amount_usd	交易金额（USD）
token_amount	交易的代币数量
price_usd	交易时代币的 USD 价格
buy_cost_usd	原始买入成本（USD）（如果此记录本身就是买入，则为 0）
is_open_or_close	0 = 开仓/加仓，1 = 平仓/减仓
timestamp	交易的 Unix 时间戳
maker_info.twitter_username	KOL 的 Twitter 用户名
maker_info.tags	钱包标签（例如 kol、smart_degen、photon）

聪明钱行为解读

在收到交易数据后，使用以下框架解读信号，然后再呈现结果。不要仅仅列出交易——要分析它们的含义。

1. 信号强度等级

等级	标准
弱	1 个 KOL 买入
中	2–3 个聪明钱以相同方向买入，或 1 个聪明钱全仓开仓
强	≥ 3 个聪明钱钱包在 30 分钟内以相同方向交易（集群信号）
非常强	集群信号 + 全仓开仓 + KOL 加入相同交易

2. 解读 is_open_or_close —— 确信信号

该字段在不同子命令中含义相反：

• follow-wallet：1 = 全仓开仓或平仓；0 = 部分加仓或减仓。
• kol / smartmoney：0 = 开仓/加仓；1 = 平仓/减仓。

全仓事件（全开或全平）比部分加仓具有更强的确信度。钱包开立全新仓位表明高信心。钱包进行全平表明他们正在完全退出——将此视为该代币的潜在退出信号。

3. 使用 price_change 评估历史表现

price_change 是当前价格与交易时价格的比率：

• price_change > 2 → 该钱包的交易表现良好（代币自买入以来已翻倍以上）——强确信信号
• price_change 1–2 → 适度盈利，交易处于盈利状态
• price_change < 1 → 交易处于亏损（当前价格低于入场价）

在根据当前交易采取行动之前，使用此信息构建钱包过去表现的心理模型。

4. 集群信号检测

当多个交易在短时间内命中相同的 base_address 时，这是一个汇聚信号——比任何单个交易都强。识别方法：

• 按 base_address 对结果分组
• 统计以相同方向交易的不同 maker 地址数量
• 如果 ≥ 3 个不同钱包在大约 30 分钟内买入同一代币 → 突出显示为 集群信号

来自 smartmoney 的集群信号比仅来自 kol 的信号更强。

5. 聪明钱数据中的危险信号

• 聪明钱卖出（side = sell 且 is_open_or_close = 全平）→ 退出信号——评估是否退出或减仓
• 仅有 KOL 买入，零 smart_degen → 社交炒作缺乏基本面支撑；风险更高
• Renowned 买入同时聪明钱卖出 → 背离信号——内部人士可能正在向散户/KOL 需求派发；高风险
• 单笔非常大的买入，无后续跟进 → 可能是一次性行为；等待其他钱包确认

输出格式

track follow-wallet / track kol / track smartmoney —— 交易流

按时间倒序呈现交易流。不要直接输出原始 JSON。

{timestamp}  {side}  {base_token.symbol}  ${amount_usd}  由 {maker_info.name 或短地址}
             [{tags}]  价格：${price_usd}  |  当前价格：${price_now}  （自交易以来 {price_change}x）

如果多个交易命中同一代币，则按代币分组。突出显示多个关注钱包在短时间内以相同方向交易的代币（集群信号）。

对于 follow-wallet，同时显示 is_open_or_close：将全仓开仓/平仓与部分加仓/减仓明确区分。

集群信号摘要

在呈现交易流之后，检查汇聚信号。如果 ≥ 2 个不同钱包以相同方向交易了同一代币，则显示摘要块：

⚡ 汇聚信号
──────────────────────────────────────────
TOKEN_X ({短地址})
  5 个聪明钱钱包 —— 全部买入 —— 总计 $42,300 —— 15 分钟内
  信号强度：强

TOKEN_Y ({短地址})
  2 个 KOL 钱包 —— 买入（全仓开仓）—— 总计 $8,100
  信号强度：中

对于强信号：在行动前进行完整的代币研究——参见 docs/workflow-token-research.md
对于中信号：监控并等待更多钱包确认后再行动。

如果未检测到汇聚信号：输出“在此结果集中未检测到集群信号。”

要研究聪明钱活动中的任何代币，请遵循 docs/workflow-token-research.md

聪明钱排行榜/钱包画像： 当用户询问“哪些聪明钱钱包值得关注”、“按胜率排名钱包”或想要比较钱包表现时——使用 track smartmoney 收集活跃钱包地址，然后通过 gmgn-portfolio stats 批量查询其统计数据。完整工作流：docs/workflow-smart-money-profile.md

每日简报： 当用户要求市场概览（“今天市场怎么样”、“今天聪明钱在买什么”、“给我一份每日简报”）时——结合 track smartmoney + track kol 与 gmgn-market trending。完整工作流：docs/workflow-daily-brief.md

安全约束

• follow-wallet 会暴露你的关注列表 —— 结果会显示你在 GMGN 上关注了哪些钱包。不要在公共渠道分享原始输出。
• track kol / track smartmoney 不暴露个人数据 —— 这些仅使用 API Key 认证，返回平台标记的公共钱包活动。可以安全分享原始输出。

备注

• track follow-tokens 使用存在认证（仅 API Key）；--wallet 是必需的
• track follow-wallet 使用签名认证（API Key + 私钥签名）；track kol 和 track smartmoney 使用存在认证（仅 API Key）
• track follow-wallet 返回在 GMGN 平台上关注的钱包的交易；关注列表自动从绑定 API Key 的 GMGN 用户账户解析——--wallet 是可选的
• 使用 --raw 获取单行 JSON 以便进一步处理
• track kol / track smartmoney 的 --side 是客户端筛选——CLI 获取所有结果后在本地筛选；不会发送到 API