用 gmgn-cli 查询加密钱包持仓、盈亏…

当需要分析一个或多个加密钱包（Solana/BSC/Base/ETH 等链）的持仓、已实现/未实现盈亏、胜率、交易历史、某代币余额或某开发者钱包创建过的代币时使用。

适用场景

解决思路

1. 运行任何命令前先执行 `gmgn-cli config --check`：退出码为 0 则正常继续；为 1 则先运行 `gmgn-cli config` 并把输出展示给用户，拿到 API Key 后运行 `gmgn-cli config --apply <KEY>` 完成配置与验证并展示输出；若 `--check` 报未知选项或命令不存在，提示用户运行 `npm install -g gmgn-cli` 升级后重试。
2. 始终使用 `gmgn-cli` 命令获取数据，不要用网页搜索、WebFetch、curl 或访问 gmgn.ai（网站需登录且不返回结构化数据）。
3. 若出现 401/403 且凭据正确，立即排查 IPv6：运行 `ifconfig | grep inet6`（macOS）或 `ip addr show | grep inet6`（Linux）列出网卡 IPv6 地址，并向 `https://ipv6.icanhazip.com` 发测试请求；若返回 IPv6 地址则告知用户关闭网卡 IPv6，因为 gmgn-cli 仅支持 IPv4。
4. 按需求选择子命令：`portfolio info`（API Key 绑定的钱包与主币余额）、`portfolio holdings`（持仓与盈亏）、`portfolio activity`（交易历史）、`portfolio stats`（交易统计，支持批量）、`portfolio profits`（1–100 个钱包批量盈亏）、`portfolio token-balance`（指定代币余额）、`portfolio created-tokens`（开发者钱包创建的代币及市值/ATH 信息）。
5. 正确理解字段语义：`realized_profit` 是已完成卖出的已实现利润，`unrealized_profit` 是持仓浮盈，二者独立，除非回答“含未平仓的总盈亏”否则不要相加；`profit_change` 是倍数比率（1.5 = +150%，0 = 持平，-0.5 = -50%），面向用户输出时转换为百分比；`pnl` = `realized_profit / total_cost`，同为倍数格式；`winrate` 为 0–1 的盈利交易占比，不反映盈亏幅度；持仓中 `cost` 是当前持仓成本基础，`usd_value` 是当前市值；`history_bought_cost` 是该代币历史累计买入花费（含已卖出部分），`cost` 仅指当前未平仓成本。
6. 分页处理：activity 结果带 `next` 字段，将其作为 `--cursor` 传入获取下一页；`next` 为空或缺失表示已是最后一页。
7. 常用示例：`gmgn-cli portfolio info`；`gmgn-cli portfolio holdings --chain sol --wallet <wallet_address>`；按 USD 价值降序 `--order-by usd_value --direction desc --limit 20`；`gmgn-cli portfolio activity --chain sol --wallet <wallet_address>`，可按 `--type buy --type sell` 或 `--token <token_address>` 过滤；`gmgn-cli portfolio stats --chain sol --wallet <wallet_address> --period 30d`；批量 `gmgn-cli portfolio stats --chain sol --wallet <w1> --wallet <w2>`；`gmgn-cli portfolio profits --chain sol --wallet <w1> --wallet <w2> --period all`；`gmgn-cli portfolio token-balance --chain sol --wallet <wallet_address> --token <token_address>`；`gmgn-cli portfolio created-tokens --chain sol --wallet <wallet_address> --order-by token_ath_mc --direction desc`；`--migrate-state migrated` 只看已迁移代币；ETH 链把 `--chain` 换成 `eth` 并使用 `0x` 地址。
8. `portfolio created-tokens` 选项：`--order-by market_cap|token_ath_mc`、`--direction asc|desc`（默认 desc）、`--migrate-state migrated|non_migrated`。
9. `portfolio holdings` 选项：`--limit <n>`（默认 20，最大 50）、`--cursor <cursor>`、`--order-by usd_value|last_active_timestamp|realized_profit|unrealized_profit|total_profit|history_bought_cost|history_sold_income`（默认 usd_value）、`--direction asc|desc`（默认 desc）、`--hide-abnormal <bool>`（默认 false）、`--hide-airdrop <bool>`（默认 true）、`--hide-closed <bool>`（默认 true）、`--hide-open`。
10. `portfolio activity` 选项：`--token <address>`、`--limit <n>`、`--cursor <cursor>`（传上一响应的 `next`）、可重复的 `--type buy|sell|transferIn|transferOut|add|remove`。
11. `portfolio stats` 选项：`--period 7d|30d`（默认 7d）。`portfolio profits` 选项：`--wallet <address...>`（必填，最多 100 个）、`--period 1d|7d|30d|all`（默认 7d）。
12. 注意各路由响应外层结构不同：`portfolio stats` 为裸对象（批量时为数组）；`portfolio profits` 为 `{"list":[{…}]}`，行在 `list[0]`；`portfolio activity` 行在 `activities`（不是 `list`）；`portfolio holdings` 行在 `list`（不是 `holdings`）；`portfolio created-tokens` 为裸对象，行在 `tokens`，聚合计数在顶层；部分部署还会整体包一层 `{"data": …}`。
13. `portfolio holdings` 关键字段：`token.token_address`（不是 `token.address`）、`token.symbol`/`token.name`、`token.price`、`token.is_honeypot`（内联返回，无需再调 `gmgn-token security`；若同一行 `history_total_sells > 0` 则 `true` 存疑，蜜罐无法卖出，受转让限制的 RWA/代币化股票合约会误触发模拟器）、`token.launchpad_platform`/`token.launchpad`、`token.liquidity`/`max_supply`/`total_supply`/`creation_timestamp`、`balance`、`usd_value`、`accu_cost`（不是 `cost`）、`history_bought_cost`/`history_sold_income`、`realized_profit`、`unrealized_profit`、`total_profit`、`total_profit_pnl`（不是 `profit_change`，另有 `realized_profit_pnl`/`unrealized_profit_pnl`）、`history_total_buys`/`history_total_sells`（不是 `buy_tx_count`/`sell_tx_count`）、`history_total_transfer_ins`/`_outs`、`start_holding_at`/`end_holding_at`/`last_active_timestamp`、`wallet_token_tags`；无 `--sell-out` 标志（1.5.8 会拒绝），不返回 `avg_cost`，用 `accu_cost / balance` 推导。
14. `portfolio activity` 关键字段：`tx_hash`（不是 `transaction_hash`）、`event_type`（部分链返回 `type`，读 `event_type ?? type`；transfer 行是空投与内部转账而非交易，任何比率计算都要排除）、`buy_cost_usd`（在 sell 行上是被卖部分的成本基础，`cost_usd - buy_cost_usd` 即该笔退出的已实现盈亏）、`gas_usd`/`priority_fee`/`tip_fee`（摩擦成本，应与单笔净收益对比）、`launchpad_platform`、`token.address`、`token.symbol`、`token_amount`、`cost_usd`、`price`（以交易对计价币计）、`price_usd`、`timestamp`、`next`。
15. `portfolio stats` 关键字段：`realized_profit`、`unrealized_profit`、`winrate`、`total_cost`、`buy_count`、`sell_count`、`pnl`；可用时含 `common` 对象（上游身份服务不可用时缺失）：`common.avatar`、`name`、`ens`（仅 EVM 链）、`tag`、`tags`（如 `["smart_money"]`）、`twitter_username`、`twitter_name`、`followers_count`、`is_blue_verified`、`follow_count`、`remark_count`、`created_token_count`、`created_at`（钱包创建时间，Unix 秒，以首笔入金交易为准，作为钱包年龄指标）、`fund_from`、`fund_from_address`、`fund_amount`；构建钱包画像时使用 `common.tags` 与 `common.twitter_username`，若 `common` 缺失则静默省略身份字段，不要报错。
16. `portfolio profits` 关键字段：`wallet_address`、`realized_profit`、`realized_profit_cost`、`buy`/`sell`、`unrealized_profit`、`total_realized_profit`、`total_realized_profit_cost`、`total_profit`、`total_cost`；金额为十进制字符串，需要精确计算时用十进制运算而非二进制浮点。
17. `portfolio created-tokens` 顶层字段：`last_create_timestamp`、`inner_count`（仍在联合曲线未毕业）、`open_count`（已毕业到 DEX）、`open_ratio`（毕业率字符串，如 `"0.25"`）、`creator_ath_info`（该钱包最佳代币的 ATH 市值信息）、`tokens` 数组；总创建数 = `inner_count + open_count`，不要用 `len(tokens)`（数组上限 100 条可能被截断）。`creator_ath_info` 字段：`creator`、`ath_token`、`ath_mc`、`token_symbol`/`token_name`、`token_logo`。每代币字段：`token_address`、`symbol`、`chain`、`create_timestamp`、`is_open`、`market_cap`、`token_ath_mc`、`pool_liquidity`、`holders`、`swap_1h`、`volume_1h`、`launchpad_platform`、`is_pump`、`bundler_rate`、`cto_flag`。不要猜测未列出的字段名；若响应中出现未列字段，先读原始输出再解释。
18. 限频处理：所有 portfolio 路由使用 GMGN 按套餐的漏桶（Free 5/5、Plus 20/20、Pro 50/50），持续吞吐约 `tier rate ÷ weight` 请求/秒，最大突发约 `floor(tier capacity ÷ weight)`。关键鉴权路由（需 `GMGN_API_KEY` + `GMGN_PRIVATE_KEY`）：`portfolio holdings` → `GET /v1/user/wallet_holdings`，权重 2。仅需 API Key 的路由：`portfolio info` → `GET /v1/user/info`（权重 2）、`portfolio activity` → `GET /v1/user/wallet_activity`（权重 3）、`portfolio stats` → `GET /v1/user/wallet_stats`（权重 3）、`portfolio profits` → `POST /v1/user/wallet_profits`（权重 3）、`portfolio token-balance` → `GET /v1/user/wallet_token_balance`（权重 2）、`portfolio created-tokens` → `GET /v1/user/created_tokens`（权重 2）。
19. 收到 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}`）则提取该 Unix 时间戳（通常 5 分钟），转换为本地时间并明确告知用户何时可重试；CLI 在剩余冷却较短时可能自动等待并重试一次，若仍失败则停止并告知确切重试时间，不要继续发请求；冷却期内重复请求每次会延长封禁 5 秒、最多 5 分钟，不要刷重试。
20. 输出格式：不要直接倾倒原始 JSON，始终解析并按结构化格式呈现；仅在管道给 `jq` 或进一步处理时用 `--raw`。持仓表按 `usd_value` 降序，顶部显示总组合价值，列为 `# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells`，对 `profit_change` 强烈为负（如 < -50%）或为正（如 > 200%）的持仓加简短标注。活动流按时间倒序，格式 `{type} {token.symbol} | {token_amount} tokens | ${cost_usd} | {timestamp} | tx: {short hash}`，用户问特定代币时按代币分组。统计摘要格式：`Wallet: {wallet} | Period: {period}`、`Realized P&L: ${realized_profit}`、`Unrealized P&L: ${unrealized_profit}`、`Win Rate: {winrate × 100}%`、`Total Spent: ${total_cost}`、`Buys / Sells: {buy_count} / {sell_count}`、`PnL Ratio: {pnl}x`，仅当响应含 `common` 时显示 `[Identity: {common.name or common.twitter_username} | Tags: {common.tags}]`；批量查询时每个钱包一个摘要块。
21. 输入校验：钱包与代币地址在运行时按链格式校验（sol：base58 32–44 字符；bsc/base/eth：`0x` + 40 位十六进制），非法输入 CLI 会报错退出。
22. 用户问“这个钱包值不值得跟”时参考 `docs/workflow-wallet-analysis.md`；问“交易风格/何时止盈/smart money 画像/跟单回报”或按胜率/PnL 对比多个 smart money 钱包时参考 `docs/workflow-smart-money-profile.md`（对比用其 Step 5 排行榜）；问“这个 dev 发过哪些币/查一下这个 dev 的代币/dev 创建记录”时直接用 `portfolio created-tokens --chain <chain> --wallet <creator_address>`，若只给了代币地址先用 `token info` 拿到创建者地址。
23. 关注钱包、KOL、Smart Money 的交易记录请改用 `gmgn-track` 技能（`track follow-wallet` / `track kol` / `track smartmoney`）。

适用边界 · 注意事项

• 未安装 gmgn-cli 或未配置 GMGN_API_KEY（及 holdings 所需的 GMGN_PRIVATE_KEY）时无法使用。
• 网络仅支持 IPv6 时不可用，gmgn-cli 只支持 IPv4。
• 需要关注钱包、KOL、Smart Money 的交易记录时应改用 gmgn-track 技能，而非本技能。