GMGN Skill Token

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.

⚠️ 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."

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

Use the gmgn-cli tool to query token information based on the user's request.

Core Concepts#

• Token address — The on-chain contract address that uniquely identifies a token on its chain. Required for all token sub-commands. Format: base58 (SOL) or 0x... hex (BSC/Base).
• Chain — The blockchain network: sol = Solana, bsc = BNB Smart Chain, base = Base (Coinbase L2), eth = Ethereum mainnet.
• Market cap — Not returned directly by token info. Calculate as price.price × circulating_supply ( price is a nested object; use price.price for the current USD price string).
• Liquidity — USD value of token reserves in the main trading pool. Low liquidity (< $10k) means high price impact / slippage when buying or selling.
• Holder — A wallet that currently holds the token. token holders returns wallets ranked by current balance.
• Trader — Any wallet that has transacted with the token (bought or sold), regardless of current holdings. token traders covers both current holders and past traders.
• Smart money ( smart_degen) — Wallets with a proven track record of profitable trading, tagged by GMGN's algorithm. High smart_degen_count is a bullish signal.
• KOL ( renowned) — Known influencer, fund, or public figure wallets, tagged by GMGN. Their positions are publicly tracked.
• Honeypot — A token where buy transactions succeed but sell transactions always fail. User funds become permanently trapped. Only detectable on BSC/Base ( is_honeypot); not applicable on SOL.
• Renounced (mint / freeze / ownership) — The developer has permanently given up that authority. On SOL: renounced_mint (cannot create new supply) and renounced_freeze_account (cannot freeze wallets) both true is the safe baseline. On EVM: owner_renounced "yes" means no admin backdoors.
• rug_ratio — A 0–1 risk score estimating the likelihood of a rug pull. Values above 0.3 are high-risk. Do not treat as a binary safe/unsafe flag — use in combination with other signals.
• Bonding curve — Price discovery mechanism used by launchpads (e.g. Pump.fun, letsbonk). Token price rises as more is bought. When the curve fills, the token "graduates" to an open DEX pool. is_on_curve: true means the token has not graduated yet.
• Wallet tags — GMGN-assigned labels on wallets: smart_degen (smart money), renowned (KOL), sniper (launched at token open), bundler (bot-bundled buy), rat_trader (insider/sneak trading). Use --tag to filter token holders / token traders by these labels.

Sub-commands#

Sub-commandDescriptiontoken infoBasic info + realtime price, liquidity, market cap, total supply, holder count, social links (market cap = price.price × circulating_supply)token securitySecurity metrics (honeypot, taxes, holder concentration, contract risks)token poolLiquidity pool info (DEX, reserves, liquidity depth)token holdersTop token holders list with profit/loss breakdowntoken tradersTop token traders list with profit/loss breakdown

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

Rate Limit Handling#

All token 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.

CommandRouteWeighttoken info``GET /v1/token/info1token security``GET /v1/token/security1token pool``GET /v1/token/pool_info1token holders``GET /v1/market/token_top_holders5token traders``GET /v1/market/token_top_traders5

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

   mkdir -p ~/.config/gmgn
   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
   chmod 600 ~/.config/gmgn/.env
   
   

Parameters — token info / token security / token pool#

ParameterRequiredDescription--chainYessol / bsc / base / eth``--addressYesToken contract address--rawNoOutput raw single-line JSON (for piping or further processing)

Parameters — token holders / token traders#

ParameterRequiredDefaultDescription--chainYes—sol / bsc / base / eth``--addressYes—Token contract address--limitNo20Number of results, max 100``--order-byNoamount_percentageSort field — see table below--directionNodescSort direction: asc / desc``--tagNo—Wallet filter: smart_degen / renowned / fresh_wallet / dev / sniper / rat_trader / bundler / transfer_in / dex_bot / bluechip_owner. Omit to return all wallets.--rawNo—Output raw single-line JSON

--order-by Values#

ValueDescriptionamount_percentageSort by percentage of total supply held (default)profitSort by realized profit in USDunrealized_profitSort by unrealized profit in USDbuy_volume_curSort by buy volumesell_volume_curSort by sell volume

--tag Values#

ValueDescriptionsmart_degenSmart money wallets (historically high-performing traders)renownedKOL / well-known wallets (influencers, funds, public figures)fresh_walletNew wallets with no prior trading historydevToken developer / creator walletssniperWallets that sniped the token at launchrat_traderInsider / sneak-trading walletsbundlerBot-bundled buy walletstransfer_inWallets with a transfer-in record for this tokendex_botDEX bot wallets (Axiom, Photon, BullX, Trojan, GMGN, Drops, PepeBoost, Padre)bluechip_ownerWallets holding established bluechip tokens

--tag + --order-by Combination Guide#

--tag and --order-by are independent — all --order-by values are valid with or without --tag. Omitting --tag returns all wallets (no filter).

Recommended combinations for common use cases:

Goal--tag``--order-byLargest smart money holders by supplysmart_degen``amount_percentageSmart money with highest realized profitsmart_degen``profitSmart money sitting on unrealized gainssmart_degen``unrealized_profitSmart money aggressively accumulatingsmart_degen``buy_volume_curSmart money distributing (exit signal)smart_degen``sell_volume_curKOLs who already took profitrenowned``profitKOLs still holding with paper gainsrenowned``unrealized_profitLargest holders overall (no filter)(omit)amount_percentage

Response Field Reference#

token info — Key Fields#

The response has five nested objects: pool, dev, link, stat, wallet_tags_stat. Access fields with dot notation when parsing (e.g. link.website, stat.top_10_holder_rate, dev.creator_address).

Top-level Fields

FieldDescriptionaddressToken contract addresssymbol / nameToken ticker and full namedecimalsToken decimal placestotal_supplyTotal token supply (same as circulating_supply for most tokens)circulating_supplyCirculating supplymax_supplyMaximum supplypriceObject — price and trading stats (see price Object below). Access current price as price.price.liquidityTotal liquidity in USD (from biggest pool)holder_countNumber of unique token holderslogoToken logo image URLcreation_timestampToken creation time (Unix seconds)open_timestampTime the token opened for trading (Unix seconds)biggest_pool_addressAddress of the main liquidity poologWhether the token is flagged as an OG token ( true / false)launchpadLaunchpad identifier (e.g. pump, moonshot)launchpad_statusLaunchpad state: 0 = not opened, 1 = live, 2 = migratedlaunchpad_progressLaunchpad bonding-curve progress (0–1)launchpad_platformLaunchpad platform namemigrated_poolPool address after migrationmigration_market_capMarket cap at migration time (USD, float)migration_market_cap_quoteQuote currency for migration_market_cap``ath_priceAll-time-high price (USD, float)locked_ratioRatio of supply locked (0–1, float)

pool Object — Main liquidity pool details

FieldDescriptionpool.pool_addressPool contract addresspool.quote_addressQuote token address (e.g. USDC, SOL, WETH)pool.quote_symbolQuote token symbol (e.g. USDC, SOL)pool.exchangeDEX name (e.g. meteora_dlmm, raydium, pump_amm, uniswap_v3)pool.liquidityPool liquidity in USDpool.base_reserveBase token reserve amountpool.quote_reserveQuote token reserve amountpool.base_reserve_valueBase reserve USD valuepool.quote_reserve_valueQuote reserve USD valuepool.fee_ratioPool trading fee ratio (e.g. 0.1 = 0.1%)pool.creation_timestampPool creation time (Unix seconds)

dev Object — Token creator / developer info

FieldDescriptiondev.creator_addressCreator wallet addressdev.creator_token_balanceCreator's current token balancedev.creator_token_statusCreator holding status: hold (still holding) / sell (sold/exited)dev.top_10_holder_rateRatio of supply held by top 10 wallets (0–1)dev.twitter_name_change_historyArray of past Twitter username changes (each entry has twitter_username, rename_timestamp)dev.dexscr_adCreator bought a DEXScreener ad: 1 = yes, 0 = nodev.dexscr_update_linkCreator updated DEXScreener socials/links: 1 = yes, 0 = nodev.dexscr_boost_feeCreator used DEXScreener Boost: 1 = yes, 0 = nodev.dexscr_trending_barToken appeared in DEXScreener trending bar: 1 = yes, 0 = nodev.dexscr_ad_tsTimestamp of DEXScreener ad purchase (Unix seconds)dev.dexscr_update_link_tsTimestamp of DEXScreener link update (Unix seconds)dev.dexscr_boost_tsTimestamp of DEXScreener Boost (Unix seconds)dev.dexscr_trending_bar_tsTimestamp of DEXScreener trending bar appearance (Unix seconds)dev.cto_flagToken has been Community Takeover'd (original dev abandoned): 1 = yes, 0 = nodev.fund_fromAddress that funded the creator walletdev.fund_from_tsTimestamp of that funding event (Unix seconds)dev.creator_open_countNumber of tokens this creator has previously launcheddev.twitter_del_post_token_countNumber of posts the creator deleted from Twitterdev.twitter_create_token_countNumber of tokens the creator has promoted on Twitterdev.offchainWhether the token is an offchain tokendev.ath_token_infoCreator's all-time-high token info object (optional); see sub-fields belowdev.ath_token_info.ath_tokenContract address of the creator's best-performing token everdev.ath_token_info.ath_mcAll-time-high market cap of that token (USD, string)dev.ath_token_info.avatarToken logo URLdev.ath_token_info.symbolToken symboldev.ath_token_info.nameToken namedev.ath_token_info.creation_timestampToken creation time (Unix seconds)

link Object — Social and explorer links

FieldDescriptionlink.twitter_usernameTwitter / X username (not full URL)link.websiteProject website URLlink.telegramTelegram URLlink.discordDiscord URLlink.instagramInstagram URLlink.tiktokTikTok URLlink.youtubeYouTube URLlink.descriptionToken description textlink.gmgnGMGN token page URLlink.geckoterminalGeckoTerminal page URLlink.verify_statusSocial verification status (integer)

stat Object — On-chain statistics

FieldDescriptionstat.holder_countNumber of holders (same as top-level holder_count)stat.top_10_holder_rateRatio of supply held by top 10 wallets (0–1)stat.dev_team_hold_rateRatio held by dev team walletsstat.creator_hold_rateRatio held by creator walletstat.creator_token_balanceRaw creator token balancestat.top_rat_trader_percentageRatio of volume from rat/insider tradersstat.top_bundler_trader_percentageRatio of volume from bundler botsstat.top_entrapment_trader_percentageRatio of volume from entrapment tradersstat.bot_degen_countNumber of bot degen walletsstat.bot_degen_rateRatio of bot degen walletsstat.fresh_wallet_rateRatio of fresh/new wallets among holdersstat.private_vault_hold_rateRatio held by private vault (vanish) addresses — displayed as "vanish" in GMGN UI (0–1)

wallet_tags_stat Object — Wallet type breakdown

FieldDescriptionwallet_tags_stat.smart_walletsNumber of smart money wallets holding the tokenwallet_tags_stat.renowned_walletsNumber of renowned / KOL wallets holding the tokenwallet_tags_stat.sniper_walletsNumber of sniper walletswallet_tags_stat.rat_trader_walletsNumber of rat trader walletswallet_tags_stat.bundler_walletsNumber of bundler bot walletswallet_tags_stat.whale_walletsNumber of whale walletswallet_tags_stat.fresh_walletsNumber of fresh walletswallet_tags_stat.top_walletsNumber of top-ranked wallets

price Object — Price and trading statistics (access current price via price.price)

FieldDescriptionprice.priceCurrent price in USD (string)price.price_{window}Price at the start of the window; windows: 1m, 5m, 1h, 6h, 24h``price.buys_{window}Buy transaction count in the windowprice.sells_{window}Sell transaction count in the windowprice.volume_{window}Total trading volume in USD for the windowprice.buy_volume_{window}Buy volume in USD for the windowprice.sell_volume_{window}Sell volume in USD for the windowprice.swaps_{window}Total swap count for the windowprice.hot_levelHeat level integer

fee_distribution Object — Launchpad fee-sharing config (optional; present for pump / bankr tokens). Use token info to check fee distribution, creator reward claim status ( has_claimed_fee), and royalty allocation for pump/bankr tokens.

FieldDescriptionfee_distribution.launchpadLaunchpad identifier: "pump", "bankr", or "" (unknown)fee_distribution.platform_dataPlatform-specific fee config; structure varies by launchpad (see below)

When fee_distribution.launchpad = "pump":

FieldDescriptionplatform_data.fee_authorityFee authority wallet addressplatform_data.is_lockedWhether the fee config is lockedplatform_data.showWhether fee distribution is displayed in the UIplatform_data.listArray of fee-share holders (see FeeShareHolder below)platform_data.bonus_categoryBonus category list (e.g. creator_reward, cashback)

When fee_distribution.launchpad = "bankr":

FieldDescriptionplatform_data.deployerOriginal deployer wallet addressplatform_data.fee_recipientFee recipient wallet addressplatform_data.listArray of fee-share holders (see FeeShareHolder below)

FeeShareHolder fields (each item in platform_data.list):

FieldDescriptionwalletWallet addressroyalty_bpsRoyalty share in basis points (10000 = 100%)is_creatorWhether this is the original creatorhas_claimed_feeWhether fees have been claimedusernameDisplay namepfpAvatar URLtwitter_usernameTwitter / X username

---

token security — Key Fields#

Contract Safety

FieldChainsDescriptionis_honeypotBSC / BaseWhether token is a honeypot ( "yes" / "no"); empty string on SOLopen_sourceallContract source code verified: "yes" / "no" / "unknown"``owner_renouncedallContract ownership renounced: "yes" / "no" / "unknown"``renounced_mintSOLMint authority renounced (SOL-specific; always false on EVM)renounced_freeze_accountSOLFreeze authority renounced (SOL-specific; always false on EVM)buy_tax / sell_taxallTax ratio — e.g. 0.03 = 3%; 0 = no tax

Holder Concentration & Risk

FieldDescriptiontop_10_holder_rateRatio of supply held by top 10 wallets (0–1); higher = more concentrateddev_team_hold_rateRatio held by dev team walletscreator_balance_rateRatio held by the token creator walletcreator_token_statusDev holding status: creator_hold (still holding) / creator_close (sold/closed)suspected_insider_hold_rateRatio held by suspected insider wallets

Trading Risk

FieldDescriptionrug_ratioRug pull risk score (0–1); higher = more riskyis_wash_tradingWhether wash trading activity is detected ( true / false)rat_trader_amount_rateRatio of volume from sneak/insider tradingbundler_trader_amount_rateRatio of volume from bundle trading (bot-driven)sniper_countNumber of sniper wallets that bought at launchburn_statusLiquidity pool burn status (e.g. "burn" = burned, "" = not burned)

---

token pool — Key Fields#

FieldDescriptionaddressPool contract addressbase_addressBase token address (the queried token)quote_addressQuote token address (e.g. SOL, USDC, WETH)exchangeDEX name (e.g. raydium, pump_amm, uniswap_v3, pancakeswap)liquidityPool liquidity in USDbase_reserveBase token reserve amountquote_reserveQuote token reserve amountpriceCurrent price in USD derived from pool reservescreation_timestampPool creation time (Unix seconds)

---

token holders / token traders — Response Fields#

The response is an object with a list array. Each item in list represents one wallet.

Identity & Holdings

FieldDescriptionaddressWallet addressaccount_addressToken account address (the on-chain account holding the token, distinct from the wallet address)addr_typeAddress type: 0 = regular wallet, 2 = exchange / liquidity poolexchangeExchange or pool name if addr_type is 2 (e.g. pump_amm, raydium)wallet_tag_v2Rank label in this list (e.g. TOP1, TOP2, ...)native_balanceNative token balance in smallest unit (lamports for SOL)balanceCurrent token balance (human-readable units)amount_curSame as balance — current token amount heldusd_valueUSD value of current holdings at current priceamount_percentageRatio of total supply held (0–1); e.g. 0.05 = 5%is_on_curve``true = still on bonding curve (pump.fun pre-graduation); false = open marketis_newWhether this is a newly created walletis_suspiciousWhether this wallet is flagged as suspicioustransfer_inWhether the current holding was received via transfer (not bought)

Trading Summary

FieldDescriptionbuy_volume_curTotal buy volume in USDsell_volume_curTotal sell volume in USDbuy_amount_curTotal tokens boughtsell_amount_curTotal tokens soldsell_amount_percentageRatio of bought tokens that have been sold (0–1); 1.0 = fully exitedbuy_tx_count_curNumber of buy transactionssell_tx_count_curNumber of sell transactionsnetflow_usdNet USD flow = sell income − buy cost (negative = net spent)netflow_amountNet token flow = bought − sold (positive = still holding net position)

Cost & P&L

FieldDescriptionavg_costAverage buy price in USD per tokenavg_soldAverage sell price in USD per tokenhistory_bought_costTotal USD spent buyinghistory_bought_feeTotal fees paid on buys in USDhistory_sold_incomeTotal USD received from sellinghistory_sold_feeTotal fees paid on sells in USDtotal_costTotal cost basis including feesprofitTotal profit in USD (realized + unrealized)profit_changeTotal profit ratio = profit / total_costrealized_profitRealized profit in USD from completed sellsrealized_pnlRealized profit ratio = realized_profit / buy_costunrealized_profitUnrealized profit in USD on current holdings at current priceunrealized_pnlUnrealized profit ratio; null if no current holdings

Transfer History

FieldDescriptioncurrent_transfer_in_amountTokens received via transfer (not bought) in current periodcurrent_transfer_out_amountTokens sent out via transfer (not sold) in current periodhistory_transfer_in_amountHistorical total tokens received via transferhistory_transfer_in_costEstimated cost basis of transferred-in tokenshistory_transfer_out_amountHistorical total tokens sent out via transferhistory_transfer_out_incomeEstimated income from transferred-out tokenshistory_transfer_out_feeFees paid on transfer-outstransfer_in_countNumber of inbound transferstransfer_out_countNumber of outbound transfers

Timing

FieldDescriptionstart_holding_atUnix timestamp when wallet first acquired this tokenend_holding_atUnix timestamp when wallet fully exited; null if still holdinglast_active_timestampUnix timestamp of most recent on-chain activity for this tokenlast_blockBlock number of last activity

Wallet Identity

FieldDescriptionnameWallet display name (if known)twitter_usernameTwitter / X usernametwitter_nameTwitter / X display nameavatarAvatar image URLtagsPlatform-level wallet tags (e.g. ["kol"], ["smart_degen"], ["axiom"])maker_token_tagsToken-specific behavior tags for this wallet (e.g. ["bundler"], ["paper_hands"], ["top_holder"])created_atWallet creation timestamp (Unix seconds); 0 if unknown

Shared Funding

FieldDescriptionnative_transferFirst native token (SOL/BNB/ETH) transfer into this wallet — indicates the original funding source; wallets sharing the same native_transfer.address are likely funded from a common origin (coordinated wallets / same operator)

Last Transaction Records

Each of the following is an object with name, address, timestamp, tx_hash, type:

FieldDescriptiontoken_transferMost recent token transfer (buy or sell)token_transfer_inMost recent inbound token transfertoken_transfer_outMost recent outbound token transfer

---

Usage Examples#

token info — Fetch Basic Info and Price#

bash

# Get current price and market cap for a SOL token
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Get basic info for a BSC token
gmgn-cli token info --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# Get basic info for a Base token
gmgn-cli token info --chain base --address 0x4200000000000000000000000000000000000006

# Get basic info for an ETH token
gmgn-cli token info --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

# Raw JSON output for downstream processing
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --raw

token security — Check Safety Before Buying#

bash

# Check if a SOL token has renounced mint + freeze authority
gmgn-cli token security --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Check if a BSC token is honeypot and whether contract is verified
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# Check a Base token for tax, rug ratio, and insider concentration
gmgn-cli token security --chain base --address 0x4200000000000000000000000000000000000006

# Check an ETH token for honeypot and contract risks
gmgn-cli token security --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

# Raw output for parsing key fields (e.g. is_honeypot, buy_tax, rug_ratio)
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 --raw

token pool — Check Liquidity Depth#

bash

# Get pool info for a SOL token (liquidity, reserves, DEX)
gmgn-cli token pool --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Get pool info for a BSC token
gmgn-cli token pool --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8

# Get pool info for an ETH token
gmgn-cli token pool --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

token holders — Analyze Holder Distribution#

bash

# Top 20 holders by supply percentage (default)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Top 50 holders sorted by percentage held
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 50 --order-by amount_percentage --direction desc

# Top 50 smart money holders (highest conviction wallets)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 50 --tag smart_degen --order-by amount_percentage

# Top KOL wallets ranked by realized profit (who has already taken profit)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by profit --direction desc --limit 20

# Smart money with most unrealized profit (who is sitting on biggest gains)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by unrealized_profit --direction desc --limit 20

# Holders who have been buying the most recently (buy momentum signal)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20

# Holders who are selling the most (exit signal / distribution warning)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by sell_volume_cur --direction desc --limit 20

# BSC token holders — KOL wallets by profit
gmgn-cli token holders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
  --tag renowned --order-by profit --direction desc --limit 50

# ETH token holders — smart money by supply percentage
gmgn-cli token holders --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --tag smart_degen --order-by amount_percentage --direction desc --limit 20

# Raw output for downstream analysis
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --limit 100 --raw

token traders — --tag + --order-by Combination Guide#

Use this table to pick the right combination for common token traders use cases:

Use case--tag``--order-bySmart money with highest buy volumesmart_degen``buy_volume_curSmart money with highest sell volume (exit signal)smart_degen``sell_volume_curKOLs recently activerenowned``last_active_timestampSmart money most profitable traderssmart_degen``profitSnipers still holdingsniper``amount_percentageSmart money sitting on biggest unrealized gainssmart_degen``unrealized_profitKOLs who already took profitrenowned``profit

token traders — Find Active Traders#

bash

# Top 20 active traders by supply held (default)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Smart money traders ranked by realized profit
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by profit --direction desc --limit 50

# KOL traders ranked by unrealized profit (still holding with paper gains)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by unrealized_profit --direction desc --limit 20

# Smart money traders with highest buy volume (aggressive accumulation)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20

# Smart money traders ranked by sell volume (who is distributing)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag smart_degen --order-by sell_volume_cur --direction desc --limit 20

# Worst performing KOL traders (who lost the most — contrarian signal)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --tag renowned --order-by profit --direction asc --limit 20

# BSC token traders by profit
gmgn-cli token traders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
  --tag smart_degen --order-by profit --direction desc --limit 50

# ETH token traders by profit
gmgn-cli token traders --chain eth --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --tag smart_degen --order-by profit --direction desc --limit 50

---

Token Quick Scoring Card#

After fetching token security and token info, apply this scoring card to give a structured verdict. Do not skip this step when the user asks for a safety check or due diligence.

Field✅ Safe⚠️ Warning🚫 Danger (Hard Stop)is_honeypot``"no"—"yes" → stop immediatelyopen_source``"yes"``"unknown"``"no"``owner_renounced``"yes"``"unknown"``"no"``renounced_mint (SOL)true—false``renounced_freeze_account (SOL)true—false``rug_ratio``< 0.10``0.10–0.30``> 0.30``top_10_holder_rate``< 0.20``0.20–0.50``> 0.50``creator_token_status``creator_close—creator_hold``buy_tax / sell_tax``0``0.01–0.05``> 0.10``sniper_count``< 5``5–20``> 20``smart_wallets (from wallet_tags_stat)≥ 3``1–2``0 (bearish, not a hard stop)renowned_wallets (from wallet_tags_stat)≥ 1—0 (neutral, not a hard stop)

Final scoring logic:

• If is_honeypot = "yes" → hard stop immediately, do not proceed regardless of other signals
• If other 🚫 fields present → skip (strong warning — present to user)
• smart_wallets = 0 alone is NOT a hard stop — it means no smart money interest yet, which is bearish but not disqualifying for very new tokens
• If 3+ ⚠️ with no 🚫 → needs more research — present findings and ask user how to proceed
• If mostly ✅ with smart_wallets ≥ 3 → worth researching — proceed to holders/traders analysis

Workflow: Full Token Due Diligence#

When the user asks for a full token research / due diligence, follow the steps in docs/workflow-token-research.md.

Steps: token info → token security → token pool → market heat check → token holders/traders (smart money signals) → Decision Framework.

For a more comprehensive report (user asks for a "deep report", "full analysis", "is this worth a large position"), use the extended workflow: docs/workflow-project-deep-report.md. This adds a scored multi-dimension analysis (fundamentals + security + liquidity + smart money conviction + price action) and produces a full written report.

For active risk monitoring on a held position (user asks "any risk warnings", "are whales dumping", "is liquidity still healthy"), follow: docs/workflow-risk-warning.md. Uses token security + token pool + token holders to flag whale exits, liquidity drain, and developer dumps.

---

Output Format#

token info — Summary Card#

Present as a concise card. Do not dump raw JSON.

text

{symbol} ({name})
Price: ${price.price}  |  Market Cap: ~${price.price × circulating_supply}  |  Liquidity: ${liquidity}
Holders: {holder_count}  |  Smart Money: {wallet_tags_stat.smart_wallets}  |  KOLs: {wallet_tags_stat.renowned_wallets}
Social: @{link.twitter_username}  |  {link.website}  |  {link.telegram}

If any social fields are empty, omit them rather than showing null.

token security — Risk Assessment Summary#

After fetching security data, present a structured risk summary using this format:

text

Token: {symbol}  |  Chain: {chain}  |  Address: {short address}
─── Security ──────────────────────────────────────
Contract verified:    ✅ yes  / 🚫 no / ⚠️ unknown
Owner renounced:      ✅ yes  / 🚫 no / ⚠️ unknown
Honeypot:             ✅ no   / 🚫 YES — DO NOT BUY
Mint renounced (SOL): ✅ yes  / ⚠️ no
Freeze renounced(SOL):✅ yes  / ⚠️ no
Rug risk score:       {rug_ratio} → ✅ <0.1 Low / ⚠️ 0.1–0.3 Med / 🚫 >0.3 High
Top-10 holder %:      {top_10_holder_rate%} → ✅ <20% / ⚠️ 20–50% / 🚫 >50%
Dev still holding:    ✅ sold (creator_close) / ⚠️ holding (creator_hold)
Sniper wallets:       ✅ <5  / ⚠️ 5–20 / 🚫 >20
─── Smart Money ───────────────────────────────────
SM holders: {smart_wallets}   KOL holders: {renowned_wallets}
─── Verdict ───────────────────────────────────────
🟢 Clean — worth researching
🟡 Mixed signals — proceed with caution
🔴 Red flags present — skip or verify manually

If is_honeypot = "yes", stop immediately and display: "🚫 HONEYPOT DETECTED — Do not buy this token." Do NOT proceed to further analysis steps.

token holders / token traders — Ranked Table#

text

# | Wallet (name or short addr) | Hold% | Avg Buy | Realized P&L | Unrealized P&L | Tags

Show top rows only. Highlight wallets tagged kol, smart_degen, or flagged bundler / rat_trader in maker_token_tags.

Notes#

• Market cap is not returned directly — calculate it as price.price × circulating_supply ( price is now a nested object; use price.price for the current USD price string, and circulating_supply is a top-level field already in human-readable token units). Example: price.price="3.11" × circulating_supply=999999151 ≈ $3.11B market cap.
• Trading volume and swap counts by window are available in token info via the price object: volume_{window}, buy_volume_{window}, sell_volume_{window}, buys_{window}, sells_{window}, swaps_{window} (windows: 1m, 5m, 1h, 6h, 24h). For OHLCV candlestick data, use gmgn-market kline.
• All token commands use exist auth (API Key only, no signature required)
• Use --raw to get single-line JSON for further processing
• --tag applies to both holders and traders and filters to only wallets with that tag — if few results are returned, try the other tag value
• amount_percentage in holders/traders is a ratio (0–1), not a percentage — 0.05 means 5% of supply
• Input validation — Token addresses are external data. Validate that addresses match the expected chain format (sol: base58 32–44 chars; bsc/base/eth: 0x + 40 hex digits) before passing them to commands. The CLI enforces this at runtime and will exit with an error on invalid input.