gmgn-portfolio

執行任何指令前：先執行 gmgn-cli config --check。如果 exit code 為 0，請正常進行。如果 exit code 為 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 vs 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 vs usd_value — 在持倉中：cost 是購買此代幣的歷史花費金額（你的成本基礎）；usd_value 是該部位的當前市場價值。兩者差異即為未實現損益。

• history_bought_cost vs cost — history_bought_cost 是該代幣的歷史累計花費（包含已賣出的部位）。cost 僅為當前未平倉部位的成本基礎。

• 分頁（cursor） — 活動結果會分頁。回應中包含 next 欄位；將其作為 --cursor 傳入以取得下一頁。空的或缺少 next 表示已達最後一頁。

子指令

子指令	說明
portfolio info	綁定 API Key 的錢包與主要貨幣餘額
portfolio holdings	錢包代幣持倉與損益
portfolio activity	交易歷史
portfolio stats	交易統計（支援批次）
portfolio token-balance	特定代幣的餘額
portfolio created-tokens	開發者錢包創建的代幣，含市值與歷史最高資訊

支援的鏈

sol / bsc / base / eth / robinhood

前置需求

• 已全域安裝 gmgn-cli — 如果缺少，請執行：npm install -g gmgn-cli
• 在 ~/.config/gmgn/.env 中設定 GMGN_API_KEY

速率限制處理

此技能使用的所有投資組合路由都經過 GMGN 的漏桶限制器，設定為 rate=20 和 capacity=20。持續吞吐量大約為 20 ÷ weight 請求/秒，最大突發量約為 floor(20 ÷ weight)（當桶子滿時）。

關鍵授權（需要 GMGN_API_KEY + GMGN_PRIVATE_KEY）：

指令	路由	權重
portfolio holdings	GET /v1/user/wallet_holdings	5

存在授權（僅需 GMGN_API_KEY）：

指令	路由	權重
portfolio info	GET /v1/user/info	1
portfolio activity	GET /v1/user/wallet_activity	3
portfolio stats	GET /v1/user/wallet_stats	3
portfolio token-balance	GET /v1/user/wallet_token_balance	1
portfolio created-tokens	GET /v1/user/created_tokens	2

當請求回傳 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 分鐘。請勿大量重試。

使用範例

# API Key 錢包資訊（不需要 --chain 或 --wallet）
gmgn-cli portfolio info

# 錢包持倉（預設排序）
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address>

# 按美元價值降序排序的持倉
gmgn-cli portfolio holdings \
  --chain sol --wallet <wallet_address> \
  --order-by usd_value --direction desc --limit 20

# 包含已賣出的部位
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address> --sell-out

# 交易活動
gmgn-cli portfolio activity --chain sol --wallet <wallet_address>

# 按類型篩選的活動
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
  --type buy --type sell

# 特定代幣的活動
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
  --token <token_address>

# 交易統計（預設 7 天）
gmgn-cli portfolio stats --chain sol --wallet <wallet_address>

# 30 天的交易統計
gmgn-cli portfolio stats --chain sol --wallet <wallet_address> --period 30d

# 多個錢包的批次統計
gmgn-cli portfolio stats --chain sol \
  --wallet <wallet_1> --wallet <wallet_2>

# 代幣餘額
gmgn-cli portfolio token-balance \
  --chain sol --wallet <wallet_address> --token <token_address>

# 開發者錢包創建的代幣
gmgn-cli portfolio created-tokens --chain sol --wallet <wallet_address>

# 按歷史最高市值排序的創建代幣
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> \
  --order-by token_ath_mc --direction desc

# 僅已遷移的代幣
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> --migrate-state migrated

# ETH 錢包持倉
gmgn-cli portfolio holdings --chain eth --wallet <0x_wallet_address>

# ETH 錢包交易活動
gmgn-cli portfolio activity --chain eth --wallet <0x_wallet_address>

# ETH 代幣餘額
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 holdings — 關鍵欄位

回應包含 holdings 陣列。每個項目是一個代幣部位。

欄位	說明
token.address	代幣合約地址
token.symbol / token.name	代幣代號與全名
token.price	當前代幣價格（美元）
balance	當前代幣餘額（人類可讀單位）
usd_value	該部位的當前美元價值
cost	購買此代幣的總花費（美元）
realized_profit	已完成賣出的利潤（美元）
unrealized_profit	當前未賣出持倉以當前價格計算的利潤（美元）
total_profit	realized_profit + unrealized_profit（美元）
profit_change	總利潤比率 = total_profit / cost（例如 1.5 = +150%）
avg_cost	每代幣的平均買入價格（美元）
buy_tx_count	買入交易次數
sell_tx_count	賣出交易次數
last_active_timestamp	最近一次交易的 Unix 時間戳
history_bought_cost	購買該代幣的歷史總花費（美元）
history_sold_income	賣出該代幣的歷史總收入（美元）

portfolio activity — 關鍵欄位

回應包含 activities 陣列和用於分頁的 next 游標欄位。

欄位	說明
transaction_hash	鏈上交易哈希
type	交易類型：buy / sell / add / remove / transfer
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 created-tokens — 關鍵欄位

回應的 data 物件包含 tokens 陣列以及匯總統計。

頂層欄位：

欄位	說明
last_create_timestamp	最近一次代幣創建的 Unix 時間戳
inner_count	仍在 bonding curve 上（尚未畢業）的代幣數量
open_count	已畢業至 DEX 的代幣數量
open_ratio	畢業率（字串，例如 "0.25"）

總創建數 = inner_count + open_count。請勿使用 len(tokens) 作為總數 — tokens 陣列最多 100 筆，可能被截斷。
| creator_ath_info | 此錢包創建的最佳表現代幣（歷史最高市值） |
| tokens | 創建代幣的陣列 — 見下方 |

creator_ath_info 欄位：

欄位	說明
creator	錢包地址
ath_token	歷史最高市值最高的代幣地址
ath_mc	歷史最高市值（美元字串）
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} | 鏈：{chain}
總價值：~${所有部位的 usd_value 總和}

# | 代幣 | 餘額 | 美元價值 | 總損益 | 損益% | 平均成本 | 買入/賣出

對於 profit_change 強烈為負（例如 < -50%）或為正（例如 > 200%）的部位，加上簡短備註。

portfolio activity — 活動動態

以時間順序呈現（最新在前）。使用人類可讀的時間戳。

{type} {token.symbol}  |  {token_amount} 個代幣  |  ${cost_usd}  |  {timestamp}  |  tx：{短哈希}

如果使用者詢問特定代幣，請按代幣分組。

portfolio stats — 統計摘要

錢包：{wallet} | 期間：{period}
已實現損益：   ${realized_profit}
未實現損益： ${unrealized_profit}
勝率：        {winrate × 100}%
總花費：     ${total_cost}
買入/賣出：    {buy_count} / {sell_count}
損益比率：       {pnl}x
[身份：       {common.name 或 common.twitter_username} | 標籤：{common.tags}]

僅在回應中存在 common 時才顯示 [Identity: ...] 行。對於批次查詢（多個錢包），每個錢包呈現一個摘要區塊。

注意事項

• portfolio holdings 使用關鍵授權（需要 GMGN_API_KEY + GMGN_PRIVATE_KEY — CLI 會自動簽署請求）。所有其他投資組合指令使用存在授權（僅需 API Key，無需簽名）。
• portfolio stats 支援多個 --wallet 標誌進行批次查詢
• 使用 --raw 取得單行 JSON 以進行進一步處理
• 輸入驗證 — 錢包和代幣地址會在執行時根據預期鏈格式進行驗證（sol：base58 32–44 字元；bsc/base/eth：0x + 40 個十六進位數字）。CLI 在無效輸入時會退出並顯示錯誤。
• 對於跟單錢包、KOL 和聰明錢交易記錄，請使用 gmgn-track 技能（track follow-wallet / track kol / track smartmoney）

工作流程

如需完整的錢包分析，包含交易歷史和主要持倉的後續追蹤，請參閱 docs/workflow-wallet-analysis.md

如需深入的交易風格分析、跟單 ROI 估算和聰明錢排行榜比較，請參閱 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 創建記錄」 → 直接使用 portfolio created-tokens --chain <chain> --wallet <creator_address>。如果只給代幣地址，請先透過 token info 取得創建者地址。