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 / arbitrum / hyperevm / robinhood / arc / stable

前置条件

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

速率限制处理

此技能使用的所有跟踪路由均采用 GMGN 基于套餐的漏桶限流：Free 5/5、Plus 20/20、Pro 50/50（速率/容量）。持续吞吐量约为 套餐速率 ÷ 权重 次请求/秒，最大突发请求数约为 floor(套餐容量 ÷ 权重)。

命令	路由	权重
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	10
track kol	GET /v1/user/kol	1
track smartmoney	GET /v1/user/smartmoney	1

请求返回 429 时：

• 如果是 RATE_LIMIT_EXCEEDED，请原样告知用户：已达到当前套餐的限频上限，点击 https://gmgn.ai/ai?chain=bsc&tab=paid_plans 升级套餐，获得更高速率限制。每项用户任务最多显示一次此升级指引。同一冷却期间后续出现 RATE_LIMIT_BANNED 时，不要重复显示。

• 从响应标头中读取 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 分钟。不要频繁重试。

• 如果出现 RATE_LIMIT_BANNED_MAX，表示由于冷却期间仍有请求到达，封禁已达到 5 分钟上限。停止此任务中的所有 GMGN 调用（不只是失败的调用），并告知用户确切的重置时间；任何在 reset_at 之前发出的请求都会使封禁时间重新延长至 5 分钟。

• 如果出现 403 PLAN_UPGRADE_REQUIRED，表示该端点的速率限制权重大于用户套餐容量，因此此套餐无法成功调用——不要重试或等待。请告知用户该端点在其当前套餐中不可用，并显示响应中的 upgrade_message（其中包含升级链接 https://gmgn.ai/ai?chain=bsc&tab=paid_plans）。

使用示例

# Followed token list for a wallet on SOL
gmgn-cli track follow-tokens --chain sol --wallet <wallet_address>

# Followed token list on BSC, raw JSON output
gmgn-cli track follow-tokens --chain bsc --wallet <wallet_address> --raw

# Follow token group names for a wallet on SOL
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address>

# Follow token group names, raw JSON output
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address> --raw

# Follow-wallet trades (all wallets you follow)
gmgn-cli track follow-wallet --chain sol

# Follow-wallet trades filtered by wallet
gmgn-cli track follow-wallet --chain sol --wallet <wallet_address>

# Follow-wallet filtered by trade direction
gmgn-cli track follow-wallet --chain sol --side buy

# Follow-wallet filtered by USD amount range
gmgn-cli track follow-wallet --chain sol --min-amount-usd 100 --max-amount-usd 10000

# KOL trade records (SOL, default)
gmgn-cli track kol --limit 10 --raw

# KOL trade records on SOL, buy only
gmgn-cli track kol --chain sol --side buy --limit 10 --raw

# Smart Money trade records (SOL, default)
gmgn-cli track smartmoney --limit 10 --raw

# Smart Money trade records, sell only
gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw

track follow-tokens 选项

选项	描述
--chain	必填。sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable
--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 / arbitrum / hyperevm / robinhood / arc / stable
--wallet <address>	必填。要查询的钱包地址

track follow-token-groups 响应字段

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

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

track follow-wallet 选项

选项	描述
--chain	必填。sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable
--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	以美元计的交易价值
cost_usd	与 amount_usd 相同，即此笔交易的美元价值
buy_cost_usd	原始买入成本（美元；如果此记录本身是买入，则为 0）
price	交易时以报价代币计价的代币价格
price_usd	交易时以美元计价的代币价格
price_now	代币当前的美元价格
price_change	自交易时起的价格变动比率（例如 6.66 = +666%）
timestamp	交易的 Unix 时间戳
is_open_or_close	1 = 完整开仓或平仓；0 = 部分加仓或减仓
launchpad	Launchpad 显示名称（例如 Pump.fun）
launchpad_platform	Launchpad 平台标识符（例如 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 / Smart Money）的钱包地址
side	交易方向：buy 或 sell
base_address	代币合约地址
base_token.symbol	代币代码
base_token.launchpad	Launchpad 平台（例如 pump）
amount_usd	以美元计的交易价值
token_amount	交易的代币数量
price_usd	交易时以美元计价的代币价格
buy_cost_usd	原始买入成本（美元；如果此记录是买入，则为 0）
is_open_or_close	0 = 开仓 / 加仓，1 = 平仓 / 减仓
timestamp	交易的 Unix 时间戳
maker_info.twitter_username	KOL 的 Twitter 用户名
maker_info.tags	钱包标签（例如 kol、smart_degen、photon）

Smart Money 行为解读

收到交易数据后，请先使用以下框架解读信号，再呈现结果。不要只罗列交易——要分析这些交易的意义。

1. 信号强度等级

等级	标准
弱	1 个 KOL 买入
中	2–3 个 Smart Money 同方向买入，或 1 个 Smart Money 完整开仓
强	30 分钟内 ≥ 3 个 Smart Money 钱包同方向交易（集群信号）
很强	集群信号 + 完整开仓 + KOL 参与同一笔交易

2. 解读 is_open_or_close — 信念信号

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

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

完全仓位事件（完全开仓或完全平仓）所体现的信念远强于部分加仓。钱包开出一个全新的完整仓位，表明其信心很强。钱包完全平仓则表明它正在彻底退出——应将其视为该代币的潜在退出信号。

3. 使用 price_change 评估过往表现

price_change 表示当前价格与交易时价格的比值：

• price_change > 2 → 该钱包的交易表现不错（代币现价已达到其买入价的 2 倍以上）——强烈的信念信号
• price_change 1–2 → 有小幅收益，交易处于盈利状态
• price_change < 1 → 交易处于亏损状态（当前价格低于入场价）

在对钱包当前的交易采取行动之前，可用此信息了解其过往表现。

4. 集群信号检测

当多个交易在短时间内涉及相同的 base_address 时，这是一种趋同信号，强于任何单笔交易。识别方法：

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

来自 smartmoney 的集群信号强于单独来自 kol 的信号。

5. 智能资金数据中的危险信号

• 智能资金卖出（side = sell + is_open_or_close = 完全平仓）→ 退出信号——评估是否应退出或减仓
• 只有 KOL 买入，没有 smart_degen → 有社交炒作，但缺少基本面支撑；风险较高
• 知名人士买入，同时有智能资金卖出 → 背离信号——内部人士可能正趁散户 / KOL 需求卖出；风险较高
• 单笔超大额买入，后续没有跟进 → 可能只是一次性交易；等待其他钱包确认

输出格式

track follow-wallet / track kol / track smartmoney — 交易动态

按时间倒序展示交易动态。不要直接输出原始 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)

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

对于 follow-wallet，还需显示 is_open_or_close：明确标记完全开仓 / 平仓与部分加仓 / 减仓。

集群信号摘要

展示交易动态后，检查是否存在趋同信号。如果 ≥ 2 个不同的钱包对同一代币进行了方向相同的交易，则显示摘要块：

⚡ Convergence Signals
──────────────────────────────────────────
TOKEN_X ({short_address})
  5 smart money wallets — all BUY — $42,300 total — within 15 min
  Signal strength: STRONG

TOKEN_Y ({short_address})
  2 KOL wallets — BUY (full open) — $8,100 total
  Signal strength: MEDIUM

对于强信号：采取行动前，先对代币进行全面研究——参见 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 使用 exist 身份验证（仅 API Key）；必须提供 --wallet
• track follow-wallet 使用签名身份验证（API Key + 私钥签名）；track kol 和 track smartmoney 使用 exist 身份验证（仅 API Key）
• track follow-wallet 会返回你在 GMGN 平台上关注的钱包的交易；关注列表会根据绑定到 API Key 的 GMGN 用户账户自动解析——--wallet 为可选项
• 使用 --raw 获取单行 JSON，以便进一步处理
• track kol / track smartmoney 的 --side 是客户端筛选条件——CLI 会获取所有结果，然后在本地筛选；它不会发送给 API