gmgn-track

コマンドを実行する前に必ず、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です。

重要：フィールド名や値を推測しないでください。フィールドの意味が不明な場合は、使用する前に以下のResponse Fieldsセクションで確認してください。

⚠️ 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ツールを使用してください。

基本概念

• follow-wallet と kol と smartmoney — それぞれ異なる 3 つのデータソースです。follow-wallet は、ユーザーが GMGN プラットフォーム上で個人的にフォローしたウォレットの取引を返します（ユーザー固有です。フォローリストは、API Key に紐づけられた GMGN ユーザーアカウントから取得されます）。kol と smartmoney は、プラットフォームがタグ付けした公開ウォレットリストの取引を返します（ユーザー固有ではありません）。これらを互いに置き換えて使わないでください。

• KOL（Key Opinion Leader） — GMGN 上でインフルエンサーや著名なトレーダーとして公開されているウォレットです。プラットフォームのウォレットラベルシステムでは renowned としてタグ付けされています。取引にはソーシャル面やマーケティング面でのシグナルが含まれますが、必ずしもアルファを示すとは限りません。

• スマートマネー（smart_degen） — 統計的に利益を上げてきた実績があると GMGN のアルゴリズムによって特定されたウォレットです。gmgn-token の smart_degen と同じ概念です。これらの取引は、KOL の取引より強いアルファシグナルとなります。

• is_open_or_close — 取引がポジション全体に関わるイベントかどうかを示します。解釈はサブコマンドによって異なります。

  • follow-wallet：1 = ポジション全体の開始または終了、0 = 部分的な追加または縮小です。
  • kol / smartmoney：0 = ポジションの開始／追加、1 = ポジションの終了／縮小です。 両方のサブコマンドに同じ解釈を適用しないでください。

• price_change — 取引が行われてからの価格変動率です。6.66 = トークンの現在価格は、ウォレットが取引した時点の 6.66 倍です（つまり +566％）。0.5 = 取引後に価格が半減しています（-50％）。これを使って、「この取引はその後どれくらい好調だったか」を評価できます。

• base_address と quote_address — 取引ペアにおいて、base_address は売買対象のトークン、quote_address はそのトークンの価格を示す通貨（通常、Solana の SOL ネイティブアドレス）です。注目するトークンを取得するには、必ず base_address を確認してください。

• maker_info.tags — ウォレットに付与されたプラットフォームラベルの配列です（例：["kol", "gmgn"]、["smart_degen", "photon"]）。ウォレットには複数のタグが付く場合があります。tag_rank（follow-wallet のみ）を使うと、各タグカテゴリ内でのウォレットの順位を確認できます。

• クラスターシグナル — 短時間に複数のフォロー中／追跡中のウォレットが同じトークンを同じ方向に取引した場合、単一ウォレットの場合より強い確信度を示すシグナルとなります。結果にこのパターンが現れた場合は、明示してください。

サブコマンドの使い分け：

• track follow-wallet — ユーザーが「フォローしているウォレットは何を取引したか」「フォローリストの取引を見せて」「フォロー中のウォレットの動きを見せて」と尋ねた場合 → GMGN プラットフォーム経由でフォローしたウォレットが必要です
• track kol — ユーザーが「KOL は何を買っているか」「インフルエンサーの取引を見せて」「最近 KOL は何をしているか」と尋ねた場合 → 既知の KOL ウォレットの取引を返します
• track smartmoney — ユーザーが「スマートマネーは何をしているか」「クジラの取引を見せて」「最近スマートマネーは何を買っているか」と尋ねた場合 → スマートマネー／クジラのウォレットの取引を返します

以下の 3 つを混同しないでください：

• follow-wallet = ユーザーが GMGN 上で個人的にフォローしたウォレット
• kol = プラットフォームがタグ付けした KOL／インフルエンサーのウォレット（ユーザー固有ではありません）
• smartmoney = プラットフォームがタグ付けしたスマートマネー／クジラのウォレット（ユーザー固有ではありません）

サブコマンド

サブコマンド	説明
track follow-tokens	ウォレットがフォローしたトークンのリスト — ウォレットが GMGN でブックマークしたトークンと、詳細な市場データを表示します
track follow-token-groups	ウォレットのトークングループ名 — ウォレットがフォロー中のトークンを整理するために使っているグループ名と ID を表示します
track follow-wallet	ユーザーが GMGN 上で個人的にフォローしているウォレットの取引記録
track kol	GMGN がタグ付けした KOL／インフルエンサーウォレットのリアルタイム取引
track smartmoney	GMGN がタグ付けしたスマートマネー／クジラのウォレットのリアルタイム取引

対応チェーン

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

前提条件

• gmgn-cli がグローバルにインストールされていること。インストールされていない場合は、次を実行します：npm install -g gmgn-cli
• GMGN_API_KEY が ~/.config/gmgn/.env に設定されていること。すべてのサブコマンドで必須です
• GMGN_PRIVATE_KEY。track follow-wallet のみで必須です（署名付き認証）。follow-tokens、kol、smartmoney では不要です

レート制限への対応

このスキルで使用するすべてのトラッキングルートには、GMGN のプランベースのリーキーバケットが適用されます：Free 5/5、Plus 20/20、Pro 50/50（レート／容量）。持続可能なスループットはおよそ tier rate ÷ weight リクエスト／秒で、最大バーストはおよそ floor(tier capacity ÷ weight) です。

コマンド	ルート	ウェイト
track follow-tokens	GET /v1/user/follow_tokens	3
track follow-token-groups	GET /v1/user/follow_token_groups	1
track follow-wallet	GET /v1/trade/follow_wallet	10
track kol	GET /v1/user/kol	1
track smartmoney	GET /v1/user/smartmoney	1

リクエストが 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 を抽出します。これは禁止が解除される Unix タイムスタンプです（通常は5分後）。現地時間に変換し、再試行できる正確な時刻をユーザーに伝えます。

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

• 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 が含まれています）。

使用例

# Followed token list for a wallet on SOL
gmgn-cli track follow-tokens --chain sol --wallet <wallet_address>

# Followed token list on BSC, raw JSON output
gmgn-cli track follow-tokens --chain bsc --wallet <wallet_address> --raw

# Follow token group names for a wallet on SOL
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address>

# Follow token group names, raw JSON output
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address> --raw

# Follow-wallet trades (all wallets you follow)
gmgn-cli track follow-wallet --chain sol

# Follow-wallet trades filtered by wallet
gmgn-cli track follow-wallet --chain sol --wallet <wallet_address>

# Follow-wallet filtered by trade direction
gmgn-cli track follow-wallet --chain sol --side buy

# Follow-wallet filtered by USD amount range
gmgn-cli track follow-wallet --chain sol --min-amount-usd 100 --max-amount-usd 10000

# KOL trade records (SOL, default)
gmgn-cli track kol --limit 10 --raw

# KOL trade records on SOL, buy only
gmgn-cli track kol --chain sol --side buy --limit 10 --raw

# Smart Money trade records (SOL, default)
gmgn-cli track smartmoney --limit 10 --raw

# Smart Money trade records, sell only
gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw

track follow-tokens のオプション

オプション	説明
--chain	必須。sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable
--wallet <address>	必須。照会するウォレットアドレス
--group-id <id>	グループで絞り込み：all_group（全グループの全トークン）、default（デフォルトグループ）、またはユーザー定義のグループ ID
--interval <interval>	価格変動統計の時間間隔（例：1m、5m、1h、6h、24h）
--order-by <field>	並べ替えフィールド：created_at / swaps / volume / market_cap / liquidity / price / open_timestamp
--direction <dir>	--order-by を設定する場合に必須。asc / desc
--limit <n>	1ページあたりの件数
--cursor <cursor>	前回の応答から取得したページネーションカーソル
--search <text>	トークン名またはアドレスで検索

track follow-tokens のレスポンスフィールド

トップレベルのフィールド：

フィールド	説明
cursor	次のページを取得するための不透明なカーソル
all_following	フォロー中のトークンの合計数
is_recommend	結果におすすめのトークンが含まれるかどうか
followings	フォロー中のトークンオブジェクトの配列

followings の各項目には、次の内容が含まれます：

フィールド	説明
address	トークンのコントラクトアドレス
symbol	トークンのティッカーシンボル
name	トークン名
chain	トークンが存在するチェーン
price	現在のトークン価格
price_change_percent	価格変動率
volume	取引量
liquidity	プールの流動性
market_cap	時価総額
swaps	スワップの合計数
group_ids	このトークンが属するフォローグループ
open_timestamp	取引開始時のUnixタイムスタンプ

track follow-token-groups のオプション

オプション	説明
--chain	必須。sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable
--wallet <address>	必須。照会するウォレットアドレス

track follow-token-groups のレスポンスフィールド

data は配列です。各項目には、次の内容が含まれます：

フィールド	説明
chain	グループが属するチェーン
group_id	グループ識別子（例：default、またはユーザー定義のID）
group_name	表示用のグループ名
rank	表示順／並べ替え順位

track follow-wallet のオプション

オプション	説明
--chain	必須。sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable
--wallet <address>	ウォレットアドレスで絞り込み
--limit <n>	ページサイズ（1～100、デフォルトは10）
--side <side>	取引方向：buy / sell
--filter <tag...>	繰り返し指定できるフィルター条件
--min-amount-usd <n>	取引額の下限（USD）
--max-amount-usd <n>	取引額の上限（USD）

track kol / track smartmoney のオプション

オプション	説明
--chain <chain>	必須。チェーン：sol / bsc / base / eth
--limit <n>	ページサイズ（1～200、デフォルトは100）
--side <side>	取引方向で絞り込み：buy / sell（クライアント側のフィルター — 結果の取得後にローカルで適用）

track follow-wallet のレスポンスフィールド

トップレベルのフィールド：

フィールド	説明
next_page_token	次の結果ページを取得するための不透明なトークン
list	取引レコードの配列

list の各項目には、次のフィールドが含まれます：

フィールド	説明
id	レコード ID（base64 エンコード済み。カーソルとして使用）
chain	チェーン名（例：sol）
transaction_hash	オンチェーン取引ハッシュ
maker	フォロー対象のウォレットアドレス
side	取引方向：buy または sell
base_address	トークンコントラクトアドレス
quote_address	クォートトークンのアドレス（SOL での売買の場合は SOL のネイティブアドレス）
base_amount	最小単位でのトークン数量
quote_amount	使用または受け取ったクォートトークンの数量（例：SOL）
amount_usd	USD 換算の取引額
cost_usd	amount_usd と同じ値。この取引レッグの USD 換算額
buy_cost_usd	元の購入コストの USD 換算額（このレコードが購入自体を表す場合は 0）
price	取引時点でのクォートトークン建てのトークン価格
price_usd	取引時点での USD 建てのトークン価格
price_now	トークンの現在の USD 建て価格
price_change	取引時点からの価格変動比率（例：6.66 = +666%）
timestamp	取引の Unix タイムスタンプ
is_open_or_close	1 = ポジションの全量を建てる、または決済する場合、0 = 部分的に追加、または縮小する場合
launchpad	ローンチパッドの表示名（例：Pump.fun）
launchpad_platform	ローンチパッドのプラットフォーム識別子（例：Pump.fun、pump_agent）
migrated_pool_exchange	トークンの移行先 DEX（該当する場合。例：pump_amm）。移行していない場合は空
base_token.symbol	トークンのティッカーシンボル
base_token.logo	トークンのロゴ画像 URL
base_token.hot_level	注目度（0 = 通常、値が高いほどトレンド）
base_token.total_supply	トークンの総供給量（文字列）
base_token.token_create_time	トークンが作成された Unix タイムスタンプ
base_token.token_open_time	取引が開始された Unix タイムスタンプ（まだ移行または開始されていない場合は 0）
maker_info.address	フォロー対象のウォレットアドレス
maker_info.name	ウォレットの表示名
maker_info.twitter_username	Twitter / X のユーザー名
maker_info.twitter_name	Twitter / X の表示名
maker_info.tags	ウォレットタグの配列（例：["kol","gmgn"]）
maker_info.tag_rank	タグ → そのカテゴリ内での順位のマップ（例：{"kol": 854}）
balance_info	ウォレットのトークン残高情報。利用できない場合は null

track kol / track smartmoney のレスポンスフィールド

レスポンスは list 配列を持つオブジェクトです。list の各項目には、次のフィールドが含まれます：

フィールド	説明
transaction_hash	オンチェーン取引ハッシュ
maker	トレーダー（KOL / スマートマネー）のウォレットアドレス
side	取引方向：buy または sell
base_address	トークンコントラクトアドレス
base_token.symbol	トークンのティッカーシンボル
base_token.launchpad	ローンチパッドのプラットフォーム（例：pump）
amount_usd	USD 換算の取引額
token_amount	取引されたトークン数量
price_usd	取引時点での USD 建てのトークン価格
buy_cost_usd	元の購入コストの USD 換算額（このレコードが購入の場合は 0）
is_open_or_close	0 = ポジションを建てる／追加する場合、1 = ポジションを決済する／縮小する場合
timestamp	取引の Unix タイムスタンプ
maker_info.twitter_username	KOL の Twitter ユーザー名
maker_info.tags	ウォレットタグ（例：kol、smart_degen、photon）

スマートマネーの動向の解釈

取引データを受け取ったら、結果を提示する前に、以下のフレームワークを使ってシグナルを解釈してください。取引を列挙するだけでなく、その意味を分析してください。

1. シグナルの強度レベル

レベル	条件
弱	KOL が 1 人買い
中	同じ方向に 2～3 人のスマートマネーが買い、または 1 人のスマートマネーがポジションの全量を建てる
強	30 分以内に同じ方向へ動く 3 人以上のスマートマネーウォレット（クラスターシグナル）
非常に強	クラスターシグナルに加え、ポジションの全量を建て、KOL も同じ取引に参加

2. is_open_or_close の読み方 — 確信度シグナル

このフィールドの意味は、サブコマンドによって逆になります。

• follow-wallet：1 = ポジションの全決済または全額での新規建て、0 = 一部の追加または縮小。
• kol / smartmoney：0 = ポジションの新規建て／追加、1 = ポジションの決済／縮小。

ポジション全体に関わる取引（全額での新規建てまたは全決済）は、一部の追加よりもはるかに強い確信を示します。ウォレットがポジション全体を新たに建てた場合は、高い確信を示しています。ウォレットがポジションを全決済した場合は、完全に撤退しようとしていることを示すため、そのトークンの潜在的な売却シグナルとして扱ってください。

3. price_change を使った実績の評価

price_change は、現在価格と取引時の価格の比率です。

• price_change > 2 → このウォレットの取引はうまくいっています（購入時からトークン価格が現在2倍以上）— 強い確信度シグナル
• price_change 1–2 → 緩やかな利益が出ており、取引は含み益です
• price_change < 1 → 取引は含み損です（現在価格がエントリー価格を下回っています）

現在の取引に基づいて行動する前に、ウォレットの過去の実績についてのイメージを把握するために活用してください。

4. クラスターシグナルの検出

短時間に複数の取引が同じ base_address に集中した場合、これは収束シグナルであり、単一の取引よりも強いシグナルです。特定するには、次の手順に従ってください。

• 結果を base_address ごとにグループ化します
• 同じ方向に取引している、異なる maker アドレスの数を数えます
• 約30分以内に3つ以上の異なるウォレットが同じトークンを購入している場合 → クラスターシグナルとして強調します

smartmoney によるクラスターシグナルは、kol だけによるものより強いシグナルです。

5. スマートマネーのデータにおける警戒シグナル

• スマートマネーによる売却（side = sell + is_open_or_close = 全決済）→ 売却シグナル — ポジションを決済または縮小するか検討してください
• KOL の買いのみで、smart_degen がゼロ → ファンダメンタルズの裏付けがないソーシャル上の盛り上がりであり、リスクが高まります
• 有名ウォレットの買いとスマートマネーの売りが同時に発生 → ダイバージェンスシグナル — インサイダーが個人投資家／KOL の需要に売りをぶつけている可能性があり、リスクが高い状況です
• 非常に大規模な買いが1件のみで、その後の動きがない → 単発の取引かもしれません。他のウォレットによる確認を待ってください

出力形式

track follow-wallet / track kol / track smartmoney — 取引フィード

時系列を逆順にした取引フィードとして表示してください。生の JSON をそのまま出力しないでください。

{timestamp}  {side}  {base_token.symbol}  ${amount_usd}  by {maker_info.name or short address}
             [{tags}]  Price: ${price_usd}  |  Price now: ${price_now}  ({price_change}x since trade)

複数の取引が同じトークンに集中している場合は、トークンごとにグループ化してください。短時間に複数のフォロー対象ウォレットが同じ方向に取引したトークン（クラスターシグナル）を強調してください。

follow-wallet の場合は、is_open_or_close も表示してください。ポジション全体の新規建て／全決済と、一部の追加／縮小を明確に区別してください。

クラスターシグナルの概要

取引フィードを表示した後、収束シグナルがないか確認してください。異なる2つ以上のウォレットが同じトークンを同じ方向に取引している場合は、概要ブロックを表示してください。

⚡ Convergence Signals
──────────────────────────────────────────
TOKEN_X ({short_address})
  5 smart money wallets — all BUY — $42,300 total — within 15 min
  Signal strength: STRONG

TOKEN_Y ({short_address})
  2 KOL wallets — BUY (full open) — $8,100 total
  Signal strength: MEDIUM

STRONG シグナルの場合：行動する前に、トークンの詳細な調査を行ってください — docs/workflow-token-research.md を参照してください。 MEDIUM シグナルの場合：行動する前に、より多くのウォレットによる確認を待ちながら監視してください。

収束シグナルが検出されなかった場合は、「この結果セットではクラスターシグナルは検出されませんでした。」と出力してください。

スマートマネーの活動で見つかったトークンを調査するには、docs/workflow-token-research.md に従ってください。

スマートマネーのリーダーボード／ウォレットのプロファイリング： ユーザーが「フォローするのに最適なスマートマネーのウォレットはどれか」「勝率順にウォレットを並べて」「ウォレットのパフォーマンスを比較したい」と尋ねた場合は、track smartmoney を使ってアクティブなウォレットアドレスを収集し、gmgn-portfolio stats でそれらの統計を一括取得してください。ワークフローの全容は、docs/workflow-smart-money-profile.md を参照してください。

デイリーブリーフ： ユーザーが市場の概要（「今日の市場はどんな感じか」「今日、スマートマネーは何を買っているか」「デイリーブリーフを作成して」）を求めた場合は、track smartmoney と track kol を gmgn-market trending と組み合わせてください。ワークフローの全容は、docs/workflow-daily-brief.md を参照してください。

安全上の制約

• follow-wallet はフォローリストを公開します — 結果から、GMGN でフォローしているウォレットがわかります。生の出力を公開チャンネルで共有しないでください。
• track kol / track smartmoney から個人データが公開されることはありません — これらは API Key 認証のみを使用し、プラットフォームのタグが付いた公開ウォレットのアクティビティを返します。生の出力を共有しても安全です。

注意事項

• track follow-tokens は exist 認証（API Key のみ）を使用します。--wallet は必須です
• track follow-wallet は署名認証（API Key ＋秘密鍵の署名）を使用します。track kol と track smartmoney は exist 認証（API Key のみ）を使用します
• track follow-wallet は GMGN プラットフォームでフォローしているウォレットの取引を返します。フォローリストは、API Key に紐付けられた GMGN ユーザーアカウントから自動的に取得されます — --wallet は省略可能です
• さらに処理するために、--raw を使用すると1行の JSON を取得できます
• track kol / track smartmoney の --side はクライアント側のフィルターです — CLI はすべての結果を取得してからローカルでフィルタリングします。API には送信されません