gmgn-track

執行任何指令前：先執行 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 工具根據使用者請求查詢鏈上追蹤資料。

核心概念

• follow-wallet vs kol vs smartmoney — 三種不同的資料來源。follow-wallet 回傳使用者個人在 GMGN 平台上追蹤的錢包交易（使用者專屬；追蹤清單從綁定 API Key 的 GMGN 使用者帳戶解析）。kol 和 smartmoney 回傳平台標籤的公開錢包清單交易（非使用者專屬）。切勿互相替代。

• KOL（關鍵意見領袖） — 在 GMGN 上被公開標記為影響者或知名交易者的錢包。在平台的錢包標籤系統中被標記為 renowned。他們的交易帶有社交/行銷訊號，不一定是 Alpha。

• 聰明錢（smart_degen） — 經 GMGN 演算法識別，具有統計上可證明的獲利交易記錄的錢包。與 gmgn-token 中的 smart_degen 概念相同。他們的交易是比 KOL 交易更強的 Alpha 訊號。

• is_open_or_close — 表示交易是否為完整倉位事件。不同子指令的解釋不同：

  • follow-wallet：1 = 完整開倉或平倉；0 = 部分加倉或減倉。
  • kol / smartmoney：0 = 開倉 / 加倉；1 = 平倉 / 減倉。
    請勿對兩個子指令套用相同的解釋。

• price_change — 自交易以來的價格變化比率。6.66 表示代幣現在是錢包交易時的 6.66 倍（即 +566%）。0.5 表示價格自交易以來腰斬（-50%）。用此評估「這筆交易表現如何」。

• base_address vs 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 — 使用者問「聰明錢在做什麼？」、「顯示巨鯨交易」、「聰明錢最近在買什麼」→ 回傳聰明錢 / 巨鯨錢包的交易

請勿混淆這三者：

• 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 / robinhood

注意：track kol 和 track smartmoney 不支援 robinhood — 它們僅接受 sol / bsc / base / eth。

前置需求

• 全域安裝 gmgn-cli — 若缺少，請執行：npm install -g gmgn-cli
• 在 ~/.config/gmgn/.env 中設定 GMGN_API_KEY — 所有子指令都需要
• GMGN_PRIVATE_KEY — 僅 track follow-wallet 需要（簽章驗證）；follow-tokens、kol 或 smartmoney 不需要

速率限制處理

此技能使用的所有追蹤路由皆透過 GMGN 的漏桶限制器，參數為 rate=20 和 capacity=20。持續吞吐量約為 20 ÷ weight 請求/秒，最大突發量約為 floor(20 ÷ 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	3
track kol	GET /v1/user/kol	1
track smartmoney	GET /v1/user/smartmoney	1

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

使用範例

# 查詢 SOL 上某錢包的追蹤代幣清單
gmgn-cli track follow-tokens --chain sol --wallet <wallet_address>

# 查詢 BSC 上的追蹤代幣清單，原始 JSON 輸出
gmgn-cli track follow-tokens --chain bsc --wallet <wallet_address> --raw

# 查詢 SOL 上某錢包的追蹤代幣群組名稱
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address>

# 查詢追蹤代幣群組名稱，原始 JSON 輸出
gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address> --raw

# 追蹤錢包交易（所有您追蹤的錢包）
gmgn-cli track follow-wallet --chain sol

# 按錢包篩選的追蹤錢包交易
gmgn-cli track follow-wallet --chain sol --wallet <wallet_address>

# 按交易方向篩選的追蹤錢包交易
gmgn-cli track follow-wallet --chain sol --side buy

# 按 USD 金額範圍篩選的追蹤錢包交易
gmgn-cli track follow-wallet --chain sol --min-amount-usd 100 --max-amount-usd 10000

# KOL 交易記錄（SOL，預設）
gmgn-cli track kol --limit 10 --raw

# SOL 上的 KOL 交易記錄，僅買入
gmgn-cli track kol --chain sol --side buy --limit 10 --raw

# 聰明錢交易記錄（SOL，預設）
gmgn-cli track smartmoney --limit 10 --raw

# 聰明錢交易記錄，僅賣出
gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw

track follow-tokens 選項

選項	說明
--chain	必填。sol / bsc / base / eth / robinhood
--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>	每頁筆數
--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 / robinhood
--wallet <address>	必填。要查詢的錢包地址

track follow-token-groups 回應欄位

data 是一個陣列。每個項目包含：

欄位	說明
chain	群組所在的鏈
group_id	群組識別碼（例如 default 或使用者自訂 ID）
group_name	人類可讀的群組名稱
rank	顯示順序 / 排序排名

track follow-wallet 選項

選項	說明
--chain	必填。sol / bsc / base / eth / robinhood
--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	Launchpad 顯示名稱（例如 Pump.fun）
launchpad_platform	Launchpad 平台識別碼（例如 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	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. 訊號強度等級

等級	條件
弱	1 個 KOL 買入
中	2–3 個聰明錢錢包同方向買入，或 1 個聰明錢完整開倉
強	≥ 3 個聰明錢錢包在 30 分鐘內同方向（叢集訊號）
非常強	叢集訊號 + 完整開倉 + 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 地址數量
• 如果 ≥ 3 個不同錢包在約 30 分鐘內買入相同代幣 → 標註為 叢集訊號

來自 smartmoney 的叢集訊號比僅來自 kol 的更強。

5. 聰明錢資料中的危險訊號

• 聰明錢賣出（side = sell + is_open_or_close = 完整平倉）→ 退出訊號 — 評估是否退出或減倉
• 只有 KOL 買入，零 smart_degen → 社交炒作缺乏基本面支撐；風險較高
• Renowned 買入 + 聰明錢同時賣出 → 分歧訊號 — 內部人士可能正在向散戶/KOL 需求出貨；高風險
• 單筆非常大的買入，無後續跟進 → 可能是一次性行為；等待其他錢包的確認

輸出格式

track follow-wallet / track kol / track smartmoney — 交易動態

以反向時間順序呈現交易動態。不要直接輸出原始 JSON。

{時間戳}  {方向}  {base_token.symbol}  ${amount_usd}  由 {maker_info.name 或短地址}
             [{標籤}]  價格：${price_usd}  |  當前價格：${price_now}  （自交易以來 {price_change}x）

如果多筆交易擊中相同代幣，則按代幣分組。標註多個追蹤錢包在短時間內以相同方向交易的代幣（叢集訊號）。

對於 follow-wallet，同時顯示 is_open_or_close：將完整開倉/平倉與部分加倉/減倉明確區分。

叢集訊號摘要

在呈現交易動態後，檢查收斂訊號。如果 ≥ 2 個不同錢包以相同方向交易相同代幣，則顯示摘要區塊：

⚡ 收斂訊號
──────────────────────────────────────────
TOKEN_X（{短地址}）
  5 個聰明錢錢包 — 全部 BUY — 總計 $42,300 — 15 分鐘內
  訊號強度：強

TOKEN_Y（{短地址}）
  2 個 KOL 錢包 — BUY（完整開倉）— 總計 $8,100
  訊號強度：中

對於強訊號：在採取行動前，先進行完整的代幣研究 — 請參閱 docs/workflow-token-research.md
對於中訊號：監控並等待更多錢包確認後再行動。

如果未偵測到收斂訊號：輸出「此結果集中未發現叢集訊號。」

若要研究聰明錢活動中出現的任何代幣，請遵循 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 使用存在驗證（僅 API Key）；--wallet 為必填
• track follow-wallet 使用簽章驗證（API Key + 私鑰簽名）；track kol 和 track smartmoney 使用存在驗證（僅 API Key）
• track follow-wallet 回傳在 GMGN 平台上追蹤的錢包交易；追蹤清單會自動從綁定 API Key 的 GMGN 使用者帳戶解析 — --wallet 為選填
• 使用 --raw 取得單行 JSON 以便進一步處理
• track kol / track smartmoney 的 --side 是客戶端篩選 — CLI 會先取得所有結果，然後在本地篩選；它不會發送到 API