gmgn-skills/skills/gmgn-track/SKILL.md

name, description, argument-hint, metadata

name	description	argument-hint	metadata
gmgn-track	Query GMGN on-chain tracking data — follow-wallet trade records, KOL trades, and Smart Money trades. Supports sol / bsc / base.	<follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--wallet <wallet_address>]	cliHelp gmgn-cli track --help

IMPORTANT: Always use gmgn-cli commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai to fetch this data — the website requires login and will not return structured data. The CLI is the only correct method.

IMPORTANT: Do NOT guess field names or values. When a field's meaning is unclear, look it up in the Response Fields sections below before using it.

⚠️ IPv6 NOT SUPPORTED: GMGN CLI commands do not support IPv6. If you get a 401 or 403 error and credentials look correct, the outbound connection is likely going via IPv6. Run curl -s https://api64.ipify.org to check — if the result is an IPv6 address, tell the user to ensure their network routes requests over IPv4.

Use the gmgn-cli tool to query on-chain tracking data based on the user's request.

Core Concepts

• follow-wallet vs kol vs smartmoney — Three distinct data sources. follow-wallet returns trades from wallets the user has personally followed on the GMGN platform (user-specific, requires private key). kol and smartmoney return trades from platform-tagged public wallet lists (not user-specific, API Key only). Never substitute one for another.

• KOL (Key Opinion Leader) — Wallets publicly identified as influencers or well-known traders on GMGN. Tagged as renowned in the platform's wallet label system. Their trades carry social/marketing signal, not necessarily alpha.

• Smart Money (smart_degen) — Wallets with a statistically proven record of profitable trading, identified by GMGN's algorithm. Same concept as smart_degen in gmgn-token. Their trades are a stronger alpha signal than KOL trades.

• is_open_or_close — Indicates whether a trade is a full position event. Interpretation differs by sub-command:

  • follow-wallet: 1 = full position open or close; 0 = partial add or reduce.
  • kol / smartmoney: 0 = position opened / added; 1 = position closed / reduced. Do not apply the same interpretation to both sub-commands.

• price_change — Ratio of price change since the trade was made. 6.66 = the token is now 6.66× what it was when the wallet traded (i.e. +566%). 0.5 = price halved since the trade (-50%). Use this to assess "how well did this trade age."

• base_address vs quote_address — In a trading pair, base_address is the token being bought/sold; quote_address is what it was priced in (typically SOL native address on Solana). To get the token of interest, always read base_address.

• maker_info.tags — Array of platform labels on the wallet (e.g. ["kol", "gmgn"], ["smart_degen", "photon"]). A wallet can carry multiple tags. Use tag_rank (follow-wallet only) to see the wallet's rank within each tag category.

• Cluster signal — When multiple followed/tracked wallets trade the same token in the same direction within a short time window, this is a stronger conviction signal than a single wallet. Highlight this pattern when it appears in results.

When to use which sub-command:

• track follow-wallet — user asks "what did the wallets I follow trade?", "show me my follow list trades", "show my followed wallet activity" → requires wallets followed via GMGN platform
• track kol — user asks "what are KOLs buying?", "show me influencer trades", "what are KOLs doing recently" → returns trades from known KOL wallets
• track smartmoney — user asks "what is smart money doing?", "show me whale trades", "what is smart money buying recently" → returns trades from smart money / whale wallets

Do NOT confuse these three:

• follow-wallet = wallets the user has personally followed on GMGN
• kol = platform-tagged KOL / influencer wallets (not user-specific)
• smartmoney = platform-tagged smart money / whale wallets (not user-specific)

Sub-commands

Sub-command	Description
track follow-wallet	Trade records from wallets the user personally follows on GMGN
track kol	Real-time trades from KOL / influencer wallets tagged by GMGN
track smartmoney	Real-time trades from smart money / whale wallets tagged by GMGN

Supported Chains

sol / bsc / base

Prerequisites

• .env file with GMGN_API_KEY set
• GMGN_PRIVATE_KEY required for track follow-wallet (signature auth); not needed for track kol / track smartmoney
• Run from the directory where your .env file is located, or set GMGN_HOST in your environment
• gmgn-cli installed globally: npm install -g gmgn-cli

Usage Examples

# 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-wallet Options

Option	Description
--chain	Required. sol / bsc / base
--wallet <address>	Filter by wallet address
--limit <n>	Page size (1–100, default 10)
--side <side>	Trade direction: buy / sell
--filter <tag...>	Repeatable filter conditions
--min-amount-usd <n>	Minimum trade amount (USD)
--max-amount-usd <n>	Maximum trade amount (USD)

track kol / track smartmoney Options

Option	Description
--chain <chain>	Chain: sol / bsc / base (default sol)
--limit <n>	Page size (1–200, default 100)
--side <side>	Filter by trade direction: buy / sell (client-side filter — applied locally after fetching results)

track follow-wallet Response Fields

Top-level fields:

Field	Description
next_page_token	Opaque token for fetching the next page of results
list	Array of trade records

Each item in list contains:

Field	Description
id	Record ID (base64-encoded, use as cursor)
chain	Chain name (e.g. sol)
transaction_hash	On-chain transaction hash
maker	Wallet address of the followed wallet
side	Trade direction: buy or sell
base_address	Token contract address
quote_address	Quote token address (SOL native address for buys/sells on SOL)
base_amount	Token quantity in smallest unit
quote_amount	Quote token amount spent / received (e.g. SOL)
amount_usd	Trade value in USD
cost_usd	Same as amount_usd — USD value of this transaction leg
buy_cost_usd	Original buy cost in USD (0 if this record is the buy itself)
price	Token price denominated in quote token at time of trade
price_usd	Token price in USD at time of trade
price_now	Token current price in USD
price_change	Price change ratio since trade time (e.g. 6.66 = +666%)
timestamp	Unix timestamp of the trade
is_open_or_close	1 = full position open or close; 0 = partial add or reduce
launchpad	Launchpad display name (e.g. Pump.fun)
launchpad_platform	Launchpad platform identifier (e.g. Pump.fun, pump_agent)
migrated_pool_exchange	DEX the token migrated to, if any (e.g. pump_amm); empty if not migrated
base_token.symbol	Token ticker symbol
base_token.logo	Token logo image URL
base_token.hot_level	Hotness level (0 = normal, higher = trending)
base_token.total_supply	Total token supply (string)
base_token.token_create_time	Unix timestamp when token was created
base_token.token_open_time	Unix timestamp when trading opened (0 if not yet migrated/opened)
maker_info.address	Followed wallet address
maker_info.name	Wallet display name
maker_info.twitter_username	Twitter / X username
maker_info.twitter_name	Twitter / X display name
maker_info.tags	Array of wallet tags (e.g. ["kol","gmgn"])
maker_info.tag_rank	Map of tag → rank within that category (e.g. {"kol": 854})
balance_info	Wallet token balance info; null if not available

track kol / track smartmoney Response Fields

The response is an object with a list array. Each item in list contains:

Field	Description
transaction_hash	On-chain transaction hash
maker	Wallet address of the trader (KOL / Smart Money)
side	Trade direction: buy or sell
base_address	Token contract address
base_token.symbol	Token ticker symbol
base_token.launchpad	Launchpad platform (e.g. pump)
amount_usd	Trade value in USD
token_amount	Token quantity traded
price_usd	Token price in USD at time of trade
buy_cost_usd	Original buy cost in USD (0 if this record is the buy)
is_open_or_close	0 = position opened / added, 1 = position closed / reduced
timestamp	Unix timestamp of the trade
maker_info.twitter_username	KOL's Twitter username
maker_info.tags	Wallet tags (e.g. kol, smart_degen, photon)

Smart Money Behavior Interpretation

After receiving trade data, interpret the signals using these frameworks before presenting results. Do not just list trades — analyze what they mean.

1. Signal Strength Levels

Level	Criteria
Weak	1 KOL buys
Medium	2–3 smart money buys in the same direction, OR 1 smart money full position open
Strong	≥ 3 smart money wallets same direction within 30 min (cluster signal)
Very Strong	Cluster signal + full position opens + KOL joining the same trade

2. Reading is_open_or_close — Conviction Signals

The field has opposite meanings by sub-command:

• follow-wallet: 1 = full position open or close; 0 = partial add or reduce.
• kol / smartmoney: 0 = position opened / added; 1 = position closed / reduced.

Full position events (full open or full close) carry much stronger conviction than partial adds. A wallet opening a full new position signals high confidence. A wallet doing a full close signals they are exiting completely — treat this as a potential exit signal for that token.

3. Using price_change to Evaluate Track Record

price_change is a ratio of current price vs price at trade time:

• price_change > 2 → this wallet's trade aged well (token is now 2x+ since they bought) — strong conviction signal
• price_change 1–2 → modest gain, trade is in profit
• price_change < 1 → trade is underwater (current price below entry)

Use this to build a mental model of a wallet's past performance before acting on their current trades.

4. Cluster Signal Detection

When multiple trades hit the same base_address in a short time window, this is a convergence signal — stronger than any single trade. To identify:

• Group results by base_address
• Count distinct maker addresses trading the same direction
• If ≥ 3 distinct wallets buy the same token within ~30 min → highlight as cluster signal

Cluster signals from smartmoney are stronger than from kol alone.

5. Red Flags in Smart Money Data

• Smart money selling (side = sell + is_open_or_close = full close) → exit signal — evaluate whether to exit or reduce position
• Only KOL buying, zero smart_degen → social hype without fundamental backing; higher risk
• Renowned buying + smart money selling simultaneously → divergence signal — insiders may be distributing into retail/KOL demand; high risk
• Single very large buy, no follow-through → may be one-off; wait for confirmation from other wallets

Output Format

track follow-wallet / track kol / track smartmoney — Trade Feed

Present as a reverse-chronological trade feed. Do not dump raw 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)

Group by token if multiple trades hit the same token. Highlight tokens where several followed wallets traded in the same direction within a short window (cluster signal).

For follow-wallet, also show is_open_or_close: flag full position opens/closes distinctly from partial adds/reduces.

Cluster Signal Summary

After presenting the trade feed, check for convergence signals. If ≥ 2 distinct wallets traded the same token in the same direction, display a summary block:

⚡ 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

For STRONG signals: proceed to full token research before acting — see docs/workflow-token-research.md For MEDIUM signals: monitor and wait for more wallets to confirm before acting.

If no convergence signals are detected: output "No cluster signals detected in this result set."

To research any token surfaced by smart money activity, follow docs/workflow-token-research.md

Smart money leaderboard / wallet profiling: When the user asks "which smart money wallets are best to follow", "rank wallets by win rate", or wants to compare wallet performance — use track smartmoney to collect active wallet addresses, then batch-query their stats via gmgn-portfolio stats. Full workflow: docs/workflow-smart-money-profile.md

Daily brief: When the user asks for a market overview ("what's the market like today", "what is smart money buying today", "give me a daily brief") — combine track smartmoney + track kol with gmgn-market trending. Full workflow: docs/workflow-daily-brief.md

Safety Constraints

• track follow-wallet requires GMGN_PRIVATE_KEY — this signing key is linked to your GMGN account. It is used for authentication only (no on-chain access), but must be protected like any credential. Never expose it in logs or command output.
• follow-wallet reveals your following list — results expose which wallets you have followed on GMGN. Do not share raw output in public channels.
• track kol / track smartmoney expose no personal data — these use API Key auth only and return platform-tagged public wallet activity. Safe to share raw output.

Notes

• track kol / track smartmoney use normal auth (API Key only, no signature required)
• track follow-wallet requires GMGN_PRIVATE_KEY for signature auth — and wallets must be followed via the GMGN platform first
• Use --raw to get single-line JSON for further processing
• track kol / track smartmoney --side is a client-side filter — the CLI fetches all results then filters locally; it is NOT sent to the API