GMGN Skill Track

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; the follow list is resolved from the GMGN user account bound to the API Key). kol and smartmoney return trades from platform-tagged public wallet lists (not user-specific). 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-commandDescriptiontrack follow-tokensFollowed token list for a wallet — which tokens a wallet has bookmarked on GMGN, with full market datatrack follow-token-groupsFollow token group names for a wallet — the group names and IDs the wallet uses to organise followed tokenstrack follow-walletTrade records from wallets the user personally follows on GMGNtrack kolReal-time trades from KOL / influencer wallets tagged by GMGNtrack smartmoneyReal-time trades from smart money / whale wallets tagged by GMGN

Supported Chains#

sol / bsc / base / eth

Prerequisites#

• gmgn-cli installed globally — if missing, run: npm install -g gmgn-cli
• GMGN_API_KEY configured in ~/.config/gmgn/.env — required for all sub-commands
• GMGN_PRIVATE_KEY — required for track follow-wallet only (signed auth); not needed for follow-tokens, kol, or smartmoney

Rate Limit Handling#

All tracking routes used by this skill go through GMGN's leaky-bucket limiter with rate=20 and capacity=20. Sustained throughput is roughly 20 ÷ weight requests/second, and the max burst is roughly floor(20 ÷ weight) when the bucket is full.

CommandRouteWeighttrack follow-tokens``GET /v1/user/follow_tokens3track follow-token-groups``GET /v1/user/follow_token_groups1track follow-wallet``GET /v1/trade/follow_wallet3track kol``GET /v1/user/kol1track smartmoney``GET /v1/user/smartmoney1

When a request returns 429:

• Read X-RateLimit-Reset from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
• If the response body contains reset_at (e.g., {"code":429,"error":"RATE_LIMIT_BANNED","message":"...","reset_at":1775184222}), extract reset_at — it is the Unix timestamp when the ban lifts (typically 5 minutes). Convert to local time and tell the user exactly when they can retry.
• The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
• For RATE_LIMIT_EXCEEDED or RATE_LIMIT_BANNED, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.

First-time setup (if GMGN_API_KEY is not configured):

1. Generate key pair and show the public key to the user: bash

   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
   
   

   Tell the user: "This is your Ed25519 public key. Go to https://gmgn.ai/ai, paste it into the API key creation form, then send me the API Key value shown on the page."

2. Wait for the user's API key, then configure (saves both API key and private key — private key is required for track follow-wallet): bash

   mkdir -p ~/.config/gmgn
   echo "GMGN_API_KEY=<key_from_user>" > ~/.config/gmgn/.env
   echo "GMGN_PRIVATE_KEY=$(awk '{printf "%s\\n", $0}' /tmp/gmgn_private.pem)" >> ~/.config/gmgn/.env
   chmod 600 ~/.config/gmgn/.env
   rm /tmp/gmgn_private.pem
   
   

Usage Examples#

bash

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

OptionDescription--chainRequired. sol / bsc / base / eth``--wallet <address>Required. Wallet address to query--group-id <id>Filter by group: all_group (all tokens across groups), default (default group), or a user-defined group ID--interval <interval>Time interval for price change stats (e.g. 1m, 5m, 1h, 6h, 24h)--order-by <field>Sort field: created_at / swaps / volume / market_cap / liquidity / price / open_timestamp``--direction <dir>Required when --order-by is set. asc / desc``--limit <n>Page size--cursor <cursor>Pagination cursor from previous response--search <text>Search by token name or address

track follow-tokens Response Fields#

Top-level fields:

FieldDescriptioncursorOpaque cursor for fetching the next pageall_followingTotal number of followed tokensis_recommendWhether results include recommended tokensfollowingsArray of followed token objects

Each item in followings contains:

FieldDescriptionaddressToken contract addresssymbolToken ticker symbolnameToken namechainChain the token is onpriceCurrent token priceprice_change_percentPrice change percentagevolumeTrading volumeliquidityPool liquiditymarket_capMarket capswapsTotal swapsgroup_idsFollow groups this token belongs toopen_timestampUnix timestamp when trading opened

track follow-token-groups Options#

OptionDescription--chainRequired. sol / bsc / base / eth``--wallet <address>Required. Wallet address to query

track follow-token-groups Response Fields#

data is an array. Each item contains:

FieldDescriptionchainChain the group is ongroup_idGroup identifier (e.g. default, or a user-defined ID)group_nameHuman-readable group namerankDisplay order / sort rank

track follow-wallet Options#

OptionDescription--chainRequired. sol / bsc / base / eth``--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#

OptionDescription--chain <chain>Required. Chain: sol / bsc / base / eth``--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:

FieldDescriptionnext_page_tokenOpaque token for fetching the next page of resultslistArray of trade records

Each item in list contains:

FieldDescriptionidRecord ID (base64-encoded, use as cursor)chainChain name (e.g. sol)transaction_hashOn-chain transaction hashmakerWallet address of the followed walletsideTrade direction: buy or sell``base_addressToken contract addressquote_addressQuote token address (SOL native address for buys/sells on SOL)base_amountToken quantity in smallest unitquote_amountQuote token amount spent / received (e.g. SOL)amount_usdTrade value in USDcost_usdSame as amount_usd — USD value of this transaction legbuy_cost_usdOriginal buy cost in USD ( 0 if this record is the buy itself)priceToken price denominated in quote token at time of tradeprice_usdToken price in USD at time of tradeprice_nowToken current price in USDprice_changePrice change ratio since trade time (e.g. 6.66 = +666%)timestampUnix timestamp of the tradeis_open_or_close``1 = full position open or close; 0 = partial add or reducelaunchpadLaunchpad display name (e.g. Pump.fun)launchpad_platformLaunchpad platform identifier (e.g. Pump.fun, pump_agent)migrated_pool_exchangeDEX the token migrated to, if any (e.g. pump_amm); empty if not migratedbase_token.symbolToken ticker symbolbase_token.logoToken logo image URLbase_token.hot_levelHotness level ( 0 = normal, higher = trending)base_token.total_supplyTotal token supply (string)base_token.token_create_timeUnix timestamp when token was createdbase_token.token_open_timeUnix timestamp when trading opened ( 0 if not yet migrated/opened)maker_info.addressFollowed wallet addressmaker_info.nameWallet display namemaker_info.twitter_usernameTwitter / X usernamemaker_info.twitter_nameTwitter / X display namemaker_info.tagsArray of wallet tags (e.g. ["kol","gmgn"])maker_info.tag_rankMap of tag → rank within that category (e.g. {"kol": 854})balance_infoWallet 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:

FieldDescriptiontransaction_hashOn-chain transaction hashmakerWallet address of the trader (KOL / Smart Money)sideTrade direction: buy or sell``base_addressToken contract addressbase_token.symbolToken ticker symbolbase_token.launchpadLaunchpad platform (e.g. pump)amount_usdTrade value in USDtoken_amountToken quantity tradedprice_usdToken price in USD at time of tradebuy_cost_usdOriginal buy cost in USD (0 if this record is the buy)is_open_or_close``0 = position opened / added, 1 = position closed / reducedtimestampUnix timestamp of the trademaker_info.twitter_usernameKOL's Twitter usernamemaker_info.tagsWallet 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#

LevelCriteriaWeak1 KOL buysMedium2–3 smart money buys in the same direction, OR 1 smart money full position openStrong≥ 3 smart money wallets same direction within 30 min (cluster signal)Very StrongCluster 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.

text

{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:

text

⚡ 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#

• 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 follow-tokens uses exist auth (API Key only); --wallet is required
• track follow-wallet uses signed auth (API Key + private key signature); track kol and track smartmoney use exist auth (API Key only)
• track follow-wallet returns trades from wallets followed on the GMGN platform; the follow list is resolved automatically from the GMGN user account bound to the API Key — --wallet is optional
• 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