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 アドレスを一覧表示します。macOS では ifconfig | grep inet6、Linux では ip addr show | grep inet6 を実行してください。（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 の場合、その期間中の完了した取引でウォレットの資金が 2 倍になったことを意味します。

• 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	P&L を含むウォレットのトークン保有状況
portfolio activity	取引履歴
portfolio stats	取引統計（バッチ処理に対応）
portfolio profits	1～100 個のウォレットを対象とする一括ウォレット P&L
portfolio token-balance	指定したトークンの残高
portfolio created-tokens	開発者ウォレットが作成したトークンと時価総額および ATH 情報

対応チェーン

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

前提条件

• gmgn-cli がグローバルにインストールされていること。不足している場合は、次を実行してください：npm install -g gmgn-cli
• GMGN_API_KEY が ~/.config/gmgn/.env に設定されていること

レート制限の処理

このスキルで使用するすべてのポートフォリオルートには、GMGN のプランベースのリーキーバケットが適用されます：Free 5/5、Plus 20/20、Pro 50/50（レート／容量）。継続的なスループットはおよそ ティアのレート ÷ 重み リクエスト／秒で、最大バーストはおよそ floor(ティアの容量 ÷ 重み) です。

重要な認証（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 升级套餐，获得更高速率限制. アップグレード案内は、ユーザーのタスクごとに最大 1 回だけ表示してください。同じクールダウン中に後続の RATE_LIMIT_BANNED が返されても、繰り返し表示しないでください。

• レスポンスヘッダーから X-RateLimit-Reset を読み取ってください。これは、制限がリセットされると見込まれる時刻を示す Unix タイムスタンプ（秒）です。

• レスポンスボディに reset_at が含まれている場合（例：{"code":429,"error":"RATE_LIMIT_BANNED","message":"...","reset_at":1775184222}）、reset_at を抽出してください。これは BAN が解除される時刻を示す Unix タイムスタンプです（通常は 5 分後）。現地時間に変換し、再試行できる正確な時刻をユーザーに伝えてください。

• クールダウンの残り時間が短い場合、CLI は自動的に待機して 1 回再試行することがあります。それでも失敗した場合は停止し、追加のリクエストを送信せず、正確な再試行時刻をユーザーに伝えてください。

• RATE_LIMIT_EXCEEDED または RATE_LIMIT_BANNED の場合、クールダウン中にリクエストを繰り返すと、その都度 5 秒ずつ、最大 5 分まで BAN が延長されることがあります。再試行を連続して行わないでください。

• RATE_LIMIT_BANNED_MAX の場合、クールダウン中にリクエストが続いたため、BAN が 5 分の上限に達しています。このタスクでは、失敗したリクエストだけでなく、GMGN へのすべての呼び出しを停止し、正確なリセット時刻をユーザーに伝えてください。reset_at より前にリクエストを行うと、BAN は再び 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（ボンディングカーブ上に残存）

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...>	1 つ以上のウォレットアドレス（必須、最大 100 件）
--period <period>	損益期間：1d / 7d / 30d / all（デフォルトは 7d）

レスポンスフィールドのリファレンス

レスポンスエンベロープ — ルートごとに異なる形式でラップされます

フィールド名を参照する前に、エンベロープを確認してください。誤った階層のフィールドを読み取ると undefined が返り、これが 0 になります。その結果、エラーではなく「このウォレットは何も利益を得ていない」 という実際の回答のように見えてしまいます。

ルート	トップレベルの形式	行の格納場所
portfolio stats	オブジェクトそのもの（バッチの場合は配列）	オブジェクト自体
portfolio profits	{"list": [ {…} ]}	list[0] — 1 行のみですが、配列内に格納されています
portfolio activity	{"activities": [...], "next": …}	activities — list ではありません
portfolio holdings	{"list": [...], "next": …}	list — holdings ではありません
portfolio created-tokens	オブジェクトそのもの	tokens と、トップレベルの集計数

一部のデプロイでは、本文全体が {"data": …} でラップされる場合もあります。

portfolio holdings — 主なフィールド

行は next カーソルとともに list に格納されて返されます。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 を読み取ります。Transfer の行はエアドロップや内部移動であり、取引ではありません。比率の計算からは除外してください
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 オブジェクトも含まれます（上流の ID サービスが利用できない場合は含まれません）。

フィールド	説明
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 がない場合は、ID 情報のフィールドを何も報告せずに省略してください。エラーとして報告しないでください。

portfolio profits — 主なフィールド

レスポンスには、ウォレットごとに 1 項目を含む list 配列があります。金額は小数文字列です。厳密な計算が必要な場合は、2 進浮動小数点ではなく十進演算で解析してください。

フィールド	説明
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	ボンディングカーブ上に残っている（DEX に移行していない）トークンの数
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 時の時価総額（USD の文字列）
token_symbol / token_name	トークンのティッカーと名前
token_logo	ロゴ URL

トークンごとのフィールド（tokens[*]）：

フィールド	説明
token_address	トークンコントラクトのアドレス
symbol	トークンのティッカー
chain	チェーン名
create_timestamp	作成時刻を表す Unix タイムスタンプ
is_open	DEX に移行済みの場合は true
market_cap	現在の時価総額（USD の文字列）
token_ath_mc	過去最高時価総額（USD の文字列）
pool_liquidity	現在の流動性（USD の文字列）
holders	現在の保有者数
swap_1h	過去 1 時間のスワップ数
volume_1h	過去 1 時間の取引量（USD の文字列）
launchpad_platform	ローンチプラットフォーム名（例：Pump.fun）
is_pump	Pump.fun でローンチされた場合は true
bundler_rate	バンドラーの参加率（0～1）
cto_flag	コミュニティによる引き継ぎトークンの場合は true

ここに記載されていないフィールド名を推測しないでください。 レスポンスにフィールドが含まれていても、この表に記載されていない場合は、生の出力を確認するまで解釈しないでください。

出力形式

生の JSON をそのまま出力しないでください。 必ず解析し、以下の構造化形式でデータを提示してください。--raw は jq に渡す場合や、さらに処理する場合にのみ使用してください。

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: ...] の行を表示してください。複数のウォレットを対象とした一括クエリでは、ウォレットごとに概要ブロックを 1 つ提示してください。

注記

• portfolio holdings は重要な認証を使用します（GMGN_API_KEY と GMGN_PRIVATE_KEY が必要です。CLI がリクエストに自動で署名します）。その他すべてのポートフォリオコマンドでは、既存の認証を使用します（API Key のみで、署名は不要です）。
• portfolio stats は、一括クエリ用に複数の --wallet フラグをサポートしています
• --raw を使用すると、さらに処理しやすい 1 行の JSON を取得できます
• 入力の検証 — ウォレットアドレスとトークンアドレスは、実行時に想定されるチェーン形式で検証されます（sol：base58 形式の 32～44 文字。bsc/base/eth：0x + 40 桁の 16 進数）。入力が無効な場合、CLI はエラーで終了します。
• フォローウォレット、KOL、Smart Money の取引記録には、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
• ユーザーが複数のスマートマネーウォレットを勝率／PnL で比較したい場合 → docs/workflow-smart-money-profile.md のステップ 5（リーダーボード）
• ユーザーが「この開発者はどんなトークンを作成しましたか」「dev 发过哪些币」「查一下这个 dev 的代币」「dev 创建记录」と尋ねた場合 → portfolio created-tokens --chain <chain> --wallet <creator_address> を直接使用します。トークンアドレスだけが指定されている場合は、まず token info で作成者のアドレスを取得します。