gmgn-portfolio

运行任何命令之前：先运行 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 工具，根据用户的请求查询钱包投资组合数据。

如需进行完整的钱包分析（持仓 + 统计 + 活动 + 结论），请遵循 docs/workflow-wallet-analysis.md

核心概念

• realized_profit 与 unrealized_profit — realized_profit = 已完成卖出并锁定的利润（已到手的现金）。unrealized_profit = 仍持有的仓位按当前价格计算的账面收益。这是两个独立数值——除非是在回答“包含未平仓仓位的总盈亏”，否则不要将它们相加。

• profit_change — 倍数比率，不是美元金额。1.5 = 回报率 +150%。0 = 盈亏平衡。-0.5 = 亏损 -50%。计算方式为 total_profit / cost。面向用户展示时，不要直接显示原始小数——应转换为百分比。

• pnl — portfolio stats 中的盈亏比率：realized_profit / total_cost。其格式与 profit_change 相同，也是倍数。pnl 为 2.0 表示该钱包在这段时间内通过已完成交易使资金翻了一倍。

• winrate — 这段时间内盈利交易所占的比例（0–1）。0.6 = 60% 的交易盈利。它不反映盈利与亏损的金额大小——即使钱包胜率很高，如果亏损金额较大，净收益仍可能为负。

• cost 与 usd_value — 在持仓中：cost 是购买该代币的历史支出金额（成本基础）；usd_value 是该仓位当前的市场价值。两者之差就是未实现盈亏。

• history_bought_cost 与 cost — history_bought_cost 是该代币的历史累计总支出（包括已卖出仓位）。cost 仅指当前未平仓仓位的成本基础。

• 分页（cursor） — 活动结果采用分页形式。响应中包含 next 字段；将其作为 --cursor 参数传入即可获取下一页。next 为空或不存在，表示已到最后一页。

子命令

子命令	说明
portfolio info	与 API Key 关联的钱包和主要货币余额
portfolio holdings	钱包代币持仓及盈亏
portfolio activity	交易历史
portfolio stats	交易统计（支持批量查询）
portfolio profits	查询 1–100 个钱包的批量盈亏
portfolio token-balance	指定代币的余额
portfolio created-tokens	开发者钱包创建的代币，包含市值和历史最高价（ATH）信息

支持的链

sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable

前提条件

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

速率限制处理

此技能使用的所有投资组合路由均采用 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

现有鉴权（仅需 GMGN_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

当请求返回 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）。

使用示例

# API Key wallet info (no --chain or --wallet needed)
gmgn-cli portfolio info

# Wallet holdings (default sort)
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address>

# Holdings sorted by USD value, descending
gmgn-cli portfolio holdings \
  --chain sol --wallet <wallet_address> \
  --order-by usd_value --direction desc --limit 20

# Include sold-out positions
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address> --sell-out

# Transaction activity
gmgn-cli portfolio activity --chain sol --wallet <wallet_address>

# Activity filtered by type
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
  --type buy --type sell

# Activity for a specific token
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
  --token <token_address>

# Trading stats (default 7d)
gmgn-cli portfolio stats --chain sol --wallet <wallet_address>

# Trading stats for 30 days
gmgn-cli portfolio stats --chain sol --wallet <wallet_address> --period 30d

# Batch stats for multiple wallets
gmgn-cli portfolio stats --chain sol \
  --wallet <wallet_1> --wallet <wallet_2>

# Batch P&L for multiple wallets (default 7d)
gmgn-cli portfolio profits --chain sol \
  --wallet <wallet_1> --wallet <wallet_2>

# All-time P&L for up to 100 wallets
gmgn-cli portfolio profits --chain sol \
  --wallet <wallet_1> --wallet <wallet_2> --period all

# Token balance
gmgn-cli portfolio token-balance \
  --chain sol --wallet <wallet_address> --token <token_address>

# Tokens created by a developer wallet
gmgn-cli portfolio created-tokens --chain sol --wallet <wallet_address>

# Created tokens sorted by all-time high market cap
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> \
  --order-by token_ath_mc --direction desc

# Only migrated tokens
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> --migrate-state migrated

# ETH wallet holdings
gmgn-cli portfolio holdings --chain eth --wallet <0x_wallet_address>

# ETH wallet transaction activity
gmgn-cli portfolio activity --chain eth --wallet <0x_wallet_address>

# ETH token balance
gmgn-cli portfolio token-balance \
  --chain eth --wallet <0x_wallet_address> --token <0x_token_address>

portfolio created-tokens 选项

选项	描述
--order-by <field>	排序字段：market_cap / token_ath_mc
--direction <asc|desc>	排序方向（默认 desc）
--migrate-state <state>	按迁移状态筛选：migrated（已迁移至 DEX）/ non_migrated（仍在 bonding curve 上）

portfolio holdings 选项

选项	描述
--limit <n>	页面大小（默认 20，最大 50）
--cursor <cursor>	分页游标
--order-by <field>	排序字段：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>	隐藏异常持仓：true / false（默认：false）
--hide-airdrop <bool>	隐藏空投持仓：true / false（默认：true）
--hide-closed <bool>	隐藏已平仓持仓：true / false（默认：true）
--hide-open	隐藏未平仓持仓

portfolio activity 选项

选项	描述
--token <address>	按代币筛选
--limit <n>	页面大小
--cursor <cursor>	分页游标（传入上一次响应中的 next 值）
--type <type>	可重复指定：buy / sell / transferIn / transferOut / add / remove

活动响应包含一个 next 字段。将其传给 --cursor 以获取下一页。

portfolio stats 选项

选项	描述
--period <period>	统计周期：7d / 30d（默认值为 7d）

portfolio profits 选项

选项	描述
--wallet <address...>	一个或多个钱包地址（必填，最多 100 个）
--period <period>	盈亏周期：1d / 7d / 30d / all（默认值为 7d）

响应字段参考

响应封装 — 每个路由的封装方式各不相同

读取字段前先检查封装结构。从错误的层级读取字段会返回 undefined，进而变成 0，看起来像是一个真实答案（“这个钱包没有收益”），而 不是报错。

路由	顶层结构	行数据所在位置
portfolio stats	裸对象（批量查询时为数组）	对象本身
portfolio profits	{"list": [ {…} ]}	list[0] — 单行数据，仍位于数组中
portfolio activity	{"activities": [...], "next": …}	activities — 不是 list
portfolio holdings	{"list": [...], "next": …}	list — 不是 holdings
portfolio created-tokens	裸对象	tokens，以及顶层的汇总数量

某些部署还会在整个响应主体外再包一层 {"data": …}。

portfolio holdings — 关键字段

行数据位于 list 下，并附有一个 next 游标。已通过 gmgn-cli 1.5.8 的实时 响应确认——有几个字段名与本文档早期版本中的说法不同，旧名称也不会作为别名接受。

字段	描述
token.token_address	代币合约地址（不是 token.address——该名称属于 activity）
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、token.max_supply、token.total_supply、token.creation_timestamp	也会随响应直接提供
balance	当前代币余额（人类可读单位）
usd_value	此持仓当前的美元价值
accu_cost	仍持有仓位的成本基础（不是 cost）
history_bought_cost / history_sold_income	历史总买入成本 / 卖出收入
realized_profit	已完成卖出的收益（美元）
unrealized_profit	按当前价格计算的未卖出持仓收益（美元）
total_profit	realized_profit + unrealized_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 标志——gmgn-cli 1.5.8 会将其作为未知选项拒绝。响应中不会返回 avg_cost；请用 accu_cost / balance 计算。

portfolio activity — 关键字段

数据行会出现在 activities 中，并附带用于分页的 next 游标。

字段	描述
tx_hash	链上交易哈希（不是 transaction_hash）
event_type	交易类型：buy / sell / transferIn / transferOut。某些链返回的是 type，因此应读取 event_type ?? type。转账行是空投和内部转移，不是交易，在计算任何比率时都应排除
buy_cost_usd	对于 sell 行，这是已售资产的成本基础；cost_usd - buy_cost_usd 是该笔退出的已实现盈亏
gas_usd / priority_fee / tip_fee	交易摩擦成本。应将 gas_usd 与每笔交易的净值比较，而不是与零比较
launchpad_platform	代币的来源平台
token.address	代币合约地址
token.symbol	代币代码
token_amount	本次交易中的代币数量
cost_usd	本次交易的美元价值
price	交易时以交易对报价代币计价的代币价格
price_usd	交易时以美元计价的代币价格
timestamp	交易的 Unix 时间戳
next	分页游标 — 传入 --cursor 以获取下一页

portfolio stats — 关键字段

响应为一个对象（批量查询时为数组）。关键字段：

字段	描述
realized_profit	所选期间的已实现总利润（美元）
unrealized_profit	未平仓头寸的未实现总利润（美元）
winrate	胜率 — 盈利交易所占比例（0–1）
total_cost	所选期间买入所花费的总金额（美元）
buy_count	买入交易次数
sell_count	卖出交易次数
pnl	盈亏比 = realized_profit / total_cost

如果可用，响应还会包含一个 common 对象（如果上游身份服务不可用，则不会包含）：

字段	描述
common.avatar	钱包头像 URL
common.name	显示名称
common.ens	ENS 域名（仅限 EVM 链）
common.tag	钱包主要标签
common.tags	钱包的所有标签（例如 ["smart_money"]）
common.twitter_username	Twitter 用户名
common.twitter_name	Twitter 显示名称
common.followers_count	Twitter 粉丝数
common.is_blue_verified	Twitter 蓝标认证徽章
common.follow_count	关注此钱包的 GMGN 用户数
common.remark_count	备注过此钱包的 GMGN 用户数
common.created_token_count	此钱包创建的代币数
common.created_at	钱包创建时间（Unix 秒）— 记录首笔资金转入的时间；可用作钱包的存续时间指标
common.fund_from	资金来源标签
common.fund_from_address	为此钱包提供资金的地址
common.fund_amount	资金金额

构建钱包简介时，请使用 common.tags 和 common.twitter_username。如果响应中没有 common，则直接省略身份字段，不要将其报告为错误。

portfolio profits — 关键字段

响应包含一个 list 数组，每个钱包对应一项。货币值为十进制字符串；需要精确计算时，应使用十进制算术解析，而不是使用二进制浮点数。

字段	描述
wallet_address	钱包地址
realized_profit	所选期间的已实现利润
realized_profit_cost	所选期间已实现利润对应的成本基础
buy / sell	所选期间的买入和卖出次数
unrealized_profit	当前持仓的未实现利润
total_realized_profit	历史累计已实现利润
total_realized_profit_cost	历史累计已实现利润对应的成本基础
total_profit	总利润
total_cost	总成本基础

portfolio created-tokens — 关键字段

响应的 data 对象包含一个 tokens 数组以及汇总统计数据。

顶层字段：

字段	描述
last_create_timestamp	最近一次创建代币的 Unix 时间戳
inner_count	仍处于联合曲线上的代币数量（尚未毕业）
open_count	已毕业至 DEX 的代币数量
open_ratio	毕业率（字符串，例如 "0.25"）

创建总数 = inner_count + open_count。不要使用 len(tokens) 作为总数——tokens 数组最多包含 100 条记录，可能会被截断。 | creator_ath_info | 此钱包创建的表现最佳代币（按 ATH 市值计算） | | tokens | 已创建代币的数组——见下文 |

creator_ath_info 字段：

字段	描述
creator	钱包地址
ath_token	ATH 市值最高的代币地址
ath_mc	ATH 市值（美元字符串）
token_symbol / token_name	代币代码和名称
token_logo	Logo URL

每个代币的字段（tokens[*]）：

字段	描述
token_address	代币合约地址
symbol	代币代码
chain	链名称
create_timestamp	创建时间的 Unix 时间戳
is_open	如果已毕业至 DEX，则为 true
market_cap	当前市值（美元字符串）
token_ath_mc	历史最高市值（美元字符串）
pool_liquidity	当前流动性（美元字符串）
holders	当前持有者数量
swap_1h	过去一小时的交换次数
volume_1h	过去一小时的交易量（美元字符串）
launchpad_platform	发射平台名称（例如 Pump.fun）
is_pump	如果在 Pump.fun 上发行，则为 true
bundler_rate	打包器参与率（0–1）
cto_flag	如果是社区接管代币，则为 true

不要猜测此处未列出的字段名称。 如果响应中出现的字段不在此表中，先阅读原始输出，再进行解读。

输出格式

不要输出原始 JSON。 始终解析数据，并按照以下结构化格式呈现。仅在将数据传递给 jq 或进行后续处理时使用 --raw。

portfolio holdings — 持仓表

按 usd_value 降序排列并呈现表格。在顶部显示投资组合总价值。

Wallet: {wallet} | Chain: {chain}
Total value: ~${sum of usd_value across all positions}

# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells

对于 profit_change 大幅为负（例如 < -50%）或为正（例如 > 200%）的持仓，添加简短说明。

portfolio activity — 活动动态

按时间倒序（最新在前）以列表形式呈现。使用易读的时间戳。

{type} {token.symbol}  |  {token_amount} tokens  |  ${cost_usd}  |  {timestamp}  |  tx: {short hash}

如果用户询问特定代币，按代币分组。

portfolio stats — 统计摘要

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
[Identity:       {common.name or common.twitter_username} | Tags: {common.tags}]

仅当响应中存在 common 时，才显示 [Identity: ...] 行。对于批量查询（多个钱包），每个钱包分别呈现一个摘要块。

说明

• portfolio holdings 使用关键身份验证（需要 GMGN_API_KEY + GMGN_PRIVATE_KEY——CLI 会自动为请求签名）。所有其他 portfolio 命令使用普通身份验证（仅需 API Key，无需签名）。
• portfolio stats 支持使用多个 --wallet 标志进行批量查询
• 使用 --raw 获取单行 JSON，以便进行后续处理
• 输入验证——运行时会根据预期的链格式验证钱包和代币地址（sol：base58，32–44 个字符；bsc/base/eth：0x + 40 位十六进制数字）。输入无效时，CLI 会报错退出。
• 对于关注钱包、KOL 和 Smart Money 交易记录，请使用 gmgn-track 技能（track follow-wallet / track kol / track smartmoney）

工作流

如需全面分析钱包，包括交易历史和对主要持仓的后续追踪，请参阅 docs/workflow-wallet-analysis.md

如需深入分析交易风格、估算跟单投资回报率并与聪明钱排行榜进行比较，请参阅 docs/workflow-smart-money-profile.md

何时使用哪个文档：

• 用户询问“这个钱包值得跟吗” → docs/workflow-wallet-analysis.md
• 用户询问“这个钱包的交易风格是什么”“他什么时候止盈”“聪明钱画像”“如果我跟单这个钱包，回报会是多少” → docs/workflow-smart-money-profile.md
• 用户想按胜率／盈亏对比多个聪明钱钱包 → docs/workflow-smart-money-profile.md 第 5 步（排行榜）
• 用户询问“这个 dev 创建了哪些代币”“dev 发过哪些币”“查一下这个 dev 的代币”“dev 创建记录” → 直接使用 portfolio created-tokens --chain <chain> --wallet <creator_address>。如果只提供了代币地址，先通过 token info 获取创建者地址。