**重要提示：始终使用 gmgn-cli 命令。切勿使用网页搜索、WebFetch、curl 或访问 gmgn.ai 获取数据——该网站需要登录，且不会返回结构化数据。CLI 是唯一正确的获取方式。**

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

重要提示：切勿猜测字段名称或值。当某个字段含义不明确时，请在下方的响应字段参考表中查找后再使用。

使用 gmgn-cli 工具根据用户请求查询代币信息。

核心概念

• 代币地址 —— 在链上唯一标识一个代币的合约地址。所有代币子命令均需提供。格式：SOL 为 base58，BSC/Base 为 0x... 十六进制。
• 链 —— 区块链网络：sol = Solana，bsc = BNB 智能链，base = Base（Coinbase L2），eth = Ethereum 主网。
• 市值 —— token info 不直接返回此值。需通过 price × circulating_supply 计算（两者均为响应中的顶层字段，单位已为人可读）。
• 流动性 —— 主交易池中代币储备的美元价值。流动性低（< $10,000）意味着买卖时价格冲击/滑点较高。
• 持有者 —— 当前持有该代币的钱包。token holders 返回按当前余额排序的钱包列表。
• 交易者 —— 任何曾与该代币进行过交易（买入或卖出）的钱包，无论是否仍持有。token traders 包含当前持有者和历史交易者。
• **智能资金（smart_degen）** —— GMGN 算法标记的有盈利交易记录的钱包。smart_degen_count 高是看涨信号。
• **KOL（renowned）** —— 被 GMGN 标记的知名影响者、基金或公众人物钱包。其持仓公开追踪。
• 蜜罐（Honeypot） —— 买入交易成功但卖出交易始终失败的代币。用户资金将永久被困。仅可在 BSC/Base 上检测（is_honeypot 字段）；Solana 上不适用。
• 放弃权限（mint / freeze / ownership） —— 开发者已永久放弃相关权限。在 Solana 上：renounced_mint（无法创建新供应量）和 renounced_freeze_account（无法冻结钱包）均为 true 才是安全基线。在 EVM 上：owner_renounced 为 "yes" 表示无管理员后门。
• **跑路风险比（rug_ratio）** —— 0–1 的风险评分，用于估算跑路可能性。数值高于 0.3 为高风险。不要将其视为二元的安全/不安全标志，应结合其他信号综合判断。
• 绑定曲线（Bonding curve） —— 启动平台（如 Pump.fun、letsbonk）使用的定价机制。购买越多，价格越高。当曲线填满后，代币“毕业”至开放 DEX 池。is_on_curve: true 表示代币尚未毕业。
• 钱包标签 —— GMGN 分配给钱包的标签：smart_degen（智能资金）、renowned（KOL）、sniper（在代币开放时首发买入）、bundler（机器人打包买入）、rat_trader（内部人/提前交易）。使用 --tag 参数可按这些标签过滤 token holders / token traders。

子命令

支持的链

sol / bsc / base / eth

前置条件

• 已全局安装 gmgn-cli —— 若缺失，请运行：npm install -g gmgn-cli
• 已在 ~/.config/gmgn/.env 中配置 GMGN_API_KEY

速率限制处理

本技能所用的所有代币路由均通过 GMGN 的漏桶限流器，参数为 rate=10 和 capacity=10。持续吞吐量约为 10 ÷ weight 次请求/秒，最大突发量约为 floor(10 ÷ weight)（当桶满时）。

当请求返回 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 分钟。请勿频繁重试。

首次设置（若未配置 GMGN_API_KEY）：

1. 生成密钥对并将公钥显示给用户：

   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null

请告知用户：*"这是你的 Ed25519 公钥。前往 https://gmgn.ai/ai，将公钥粘贴到 API 密钥创建表单中，然后将页面上显示的 API 密钥值发送给我。"*

1. 等待用户提供的 API 密钥后，执行以下配置：

   mkdir -p ~/.config/gmgn
   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
   chmod 600 ~/.config/gmgn/.env

参数 — token info / token security / token pool

参数 — token holders / token traders

--order-by 可选值

--tag 可选值

--tag + --order-by 组合使用指南

--tag 和 --order-by 相互独立 — 所有 --order-by 值均可与 --tag 任意组合使用。省略 --tag 表示不进行钱包筛选。

常见使用场景推荐组合：

响应字段说明

token info — 关键字段

响应包含五个嵌套对象：pool、dev、link、stat、wallet_tags_stat。解析时使用点号访问（例如 link.website、stat.top_10_holder_rate、dev.creator_address）。

顶层字段

**pool 对象** — 主要流动性池详情

**dev 对象** — 代币创建者 / 开发者信息

**link 对象** — 社交与探索链接

**stat 对象** — 链上统计数据

**wallet_tags_stat 对象** — 钱包类型分布

token security — 关键字段

合约安全

持有集中度与风险

交易风险

token pool — 关键字段

token holders / token traders — 响应字段

响应为一个对象，包含一个 list 数组。list 中的每一项代表一个钱包。

身份与持仓

交易概览

成本与盈亏

转账历史

时间信息

钱包身份信息

最近交易记录

以下每一项均为包含 name、address、timestamp、tx_hash、type 的对象

使用示例

token info — 获取基础信息和价格

# 获取 SOL 代币当前价格和市值
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# 获取 BSC 代币的基础信息
gmgn-cli token info --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# 获取 Base 代币的基础信息
gmgn-cli token info --chain base --address 0x4200000000000000000000000000000000000006

# 获取 ETH 代币的基础信息
gmgn-cli token info --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

# 原始 JSON 输出，用于下游处理
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --raw

token security — 购买前检查安全性

# 检查 SOL 代币是否已放弃铸造权和冻结权限
gmgn-cli token security --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# 检查 BSC 代币是否为蜜罐，以及合约是否已验证
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# 检查 Base 代币的税收、跑路风险比和内部持有集中度
gmgn-cli token security --chain base --address 0x4200000000000000000000000000000000000006

# 检查 ETH 代币是否存在蜜罐和合约风险
gmgn-cli token security --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

# 原始输出，便于解析关键字段（如 is_honeypot、buy_tax、rug_ratio）
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 --raw

token pool — 检查流动性深度

# 获取 SOL 代币的池子信息（流动性、储备金、DEX）
gmgn-cli token pool --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# 获取 BSC 代币的池子信息
gmgn-cli token pool --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# 获取 ETH 代币的池子信息
gmgn-cli token pool --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

token holders — 分析持币分布

# 按持币比例排序的前 20 名持币者（默认）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# 按持币比例排序的前 50 名持币者
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 50 --order-by amount_percentage --direction desc

# 前 50 名“聪明钱”持币者（最高信心钱包）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 50 --tag smart_degen --order-by amount_percentage

# 按实现利润排名的前 20 名 KOL 钱包（已获利离场者）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by profit --direction desc --limit 20

# 持有最大未实现利润的“聪明钱”（坐拥最大收益者）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by unrealized_profit --direction desc --limit 20

# 最近频繁买入的持币者（买入动量信号）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20

# 最频繁卖出的持币者（退出信号 / 分发预警）
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by sell_volume_cur --direction desc --limit 20

# BSC 代币持币者 —— 按利润排名的 KOL 钱包
gmgn-cli token holders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
  --tag renowned --order-by profit --direction desc --limit 50

# ETH 代币持币者 —— 按持币比例排名的“聪明钱”
gmgn-cli token holders --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --tag smart_degen --order-by amount_percentage --direction desc --limit 20

# 原始输出，用于后续分析
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 100 --raw

token traders — --tag + --order-by 组合指南

使用此表选择适用于常见 token traders 场景的组合：

token traders — 寻找活跃交易者

GMGN 技术代币分析技能

常用命令示例

# 按持币量排名前 20 的活跃交易者（默认）
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# 按已实现利润排序的“聪明钱”交易者
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by profit --direction desc --limit 50

# 按未实现利润排序的 KOL 交易者（仍持有且有账面收益）
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by unrealized_profit --direction desc --limit 20

# 按买入金额最高排序的“聪明钱”交易者（激进吸筹信号）
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20

# 按卖出金额排序的“聪明钱”交易者（可能在抛售）
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by sell_volume_cur --direction desc --limit 20

# 表现最差的 KOL 交易者（亏损最多，反向信号）
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by profit --direction asc --limit 20

# BSC 链代币按利润排序的交易者
gmgn-cli token traders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
  --tag smart_degen --order-by profit --direction desc --limit 50

# ETH 链代币按利润排序的交易者
gmgn-cli token traders --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --tag smart_degen --order-by profit --direction desc --limit 50

代币快速评分卡

在获取 token security 和 token info 数据后，应用以下评分卡生成结构化结论。当用户要求安全检查或尽职调查时，不得跳过此步骤。

最终评分逻辑：

• 若 is_honeypot = "yes" → 立即强制停止，无论其他信号如何
• 若存在其他 🚫 项 → 跳过（强烈警告，需向用户提示）
• smart_wallets = 0 单独不构成强制停止 —— 表示尚无智能资金关注，对极新代币而言属看跌但非排除条件
• 若出现 3 个以上 ⚠️ 且无 🚫 → 需进一步研究 —— 展示发现并询问用户如何继续
• 若多数为 ✅ 且 smart_wallets ≥ 3 → 值得深入研究 —— 可进入持有者/交易者分析环节

工作流程：完整代币尽职调查

当用户请求完整代币研究或尽职调查时，请遵循 [docs/workflow-token-research.md](../../docs/workflow-token-research.md) 中定义的步骤。

执行顺序：token info → token security → token pool → 市场热度检查 → token holders/traders（智能资金信号）→ 决策框架。

如需更全面报告（用户提出“深度报告”、“完整分析”、“是否值得大仓位投入”），请使用扩展工作流：[docs/workflow-project-deep-report.md](../../docs/workflow-project-deep-report.md)。该流程包含多维度评分分析（基本面 + 安全性 + 流动性 + 智能资金信心 + 价格行为），并生成完整书面报告。

针对持仓中的风险监控（用户询问“是否有风险预警”、“鲸鱼是否在抛售”、“流动性是否健康”），请参考：[docs/workflow-risk-warning.md](../../docs/workflow-risk-warning.md)。该流程结合 token security、token pool、token holders 数据，用于识别鲸鱼出货、流动性流失及开发者抛售等风险信号。

输出格式

token info —— 概要卡片

以简洁卡片形式呈现，不要直接输出原始 JSON。

{symbol} ({name})
价格: ${price}  |  市值: ~${price × circulating_supply}  |  流动性: ${liquidity}
持币人数: {holder_count}  |  智能资金: {wallet_tags_stat.smart_wallets}  |  KOL: {wallet_tags_stat.renowned_wallets}
社交: @{link.twitter_username}  |  {link.website}  |  {link.telegram}

若任一社交字段为空，应省略该项，而非显示 null。

token security —— 风险评估摘要

获取安全数据后，按以下格式呈现结构化风险摘要：

代币: {symbol}  |  链: {chain}  |  地址: {short address}
─── 安全性 ──────────────────────────────────────
合约已验证:    ✅ yes  / 🚫 no / ⚠️ unknown
所有者已放弃:  ✅ yes  / 🚫 no / ⚠️ unknown
蜜罐检测:      ✅ no   / 🚫 YES — 不要购买
铸币权已放弃 (SOL): ✅ yes  / ⚠️ no
冻结权已放弃 (SOL): ✅ yes  / ⚠️ no
跑路风险评分:  {rug_ratio} → ✅ <0.1 低 / ⚠️ 0.1–0.3 中 / 🚫 >0.3 高
前十大持有者占比: {top_10_holder_rate%} → ✅ <20% / ⚠️ 20–50% / 🚫 >50%
开发者仍持有:  ✅ 已清仓 (creator_close) / ⚠️ 仍在持有 (creator_hold)
狙击钱包数量: ✅ <5  / ⚠️ 5–20 / 🚫 >20
─── 智能资金 ───────────────────────────────────
智能资金持有者: {smart_wallets}   KOL 持有者: {renowned_wallets}
─── 结论 ───────────────────────────────────────
🟢 清洁 — 值得深入研究
🟡 信号混杂 — 建议谨慎操作
🔴 存在红色警报 — 跳过或手动核实

**若 is_honeypot = "yes"，必须立即停止并显示：**

"🚫 蜜罐检测到 — 不要购买此代币。"

不得继续后续分析步骤。

token holders / token traders — 排名表格

# | 钱包（名称或简短地址） | 持有比例 | 平均买入价 | 实现盈亏 | 未实现盈亏 | 标签

仅显示前几行结果。对标记为 kol、smart_degen，或被标注为 bundler / rat_trader 的钱包进行高亮。

注意事项

• 市值不会直接返回 — 需通过 price × circulating_supply 计算（两个字段均为顶层字段；circulating_supply 已以人类可读的代币单位表示，无需进行小数位调整）。示例：price=3.11 × circulating_supply=999999151 ≈ 31.1 亿美元市值。
• **交易量（1h、24h 等）不包含在 token info 中** — 如需获取交易量或 OHLCV 数据，请使用 gmgn-market 技能，并查询 K 线数据：gmgn-cli market kline --chain <chain> --address <token_address> --resolution <1m|5m|15m|1h|4h|1d>。完整详情请参见 gmgn-market SKILL.md。
• 所有代币相关命令均使用常规认证（仅需 API Key，无需签名）。
• 使用 --raw 可获取单行 JSON 以便进一步处理。
• --tag 同时适用于 holders 和 traders，用于筛选具有指定标签的钱包 — 若返回结果过少，可尝试更换标签值。
• holders/traders 中的 amount_percentage 为比例值（0–1），非百分比 — 0.05 表示占总供应量的 5%。
• 输入验证 — 代币地址为外部数据。在传递给命令前，请验证地址是否符合目标链格式（Solana：base58 编码，长度 32–44 字符；BSC/Base/Ethereum：0x + 40 位十六进制数字）。CLI 会在运行时强制执行此校验，若输入无效将退出并报错。