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: If you get a 401 or 403 error and credentials look correct, check for IPv6 immediately: (1) list all network interfaces and their IPv6 addresses — run ifconfig | grep inet6 (macOS) or ip addr show | grep inet6 (Linux); (2) send a test request to https://ipv6.icanhazip.com — if the response is an IPv6 address, outbound traffic is going via IPv6. Tell the user immediately: "Please disable IPv6 on your network interface — gmgn-cli commands only work 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

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

track kol / track smartmoney Options

track follow-wallet Response Fields

Top-level fields:

Each item in list contains:

track kol / track smartmoney Response Fields

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

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

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