Gmgn Token

1---2name: gmgn-token3description: Research any crypto or meme token by address — real-time price, market cap, liquidity, holder list, trader list, top Smart Money and KOL positions, security audit (honeypot, rug pull risk, dev wallet, renounced status), social links (Twitter/X, website) via GMGN API on Solana, BSC, or Base. Use when user asks about a token's price, safety, holders, traders, smart money exposure, or wants due diligence before buying.4argument-hint: "<sub-command> --chain <sol|bsc|base> --address <token_address>"5metadata:6  cliHelp: "gmgn-cli token --help"7---8 9**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.**10 11**⚠️ 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."**12 13**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.**14 15Use the `gmgn-cli` tool to query token information based on the user's request.16 17## Core Concepts18 19- **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).20- **Chain** — The blockchain network: `sol` = Solana, `bsc` = BNB Smart Chain, `base` = Base (Coinbase L2).21- **Market cap** — Not returned directly by `token info`. Calculate as `price × circulating_supply` (both are top-level fields in the response, already in human-readable units).22- **Liquidity** — USD value of token reserves in the main trading pool. Low liquidity (< $10k) means high price impact / slippage when buying or selling.23- **Holder** — A wallet that currently holds the token. `token holders` returns wallets ranked by current balance.24- **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.25- **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.26- **KOL (`renowned`)** — Known influencer, fund, or public figure wallets, tagged by GMGN. Their positions are publicly tracked.27- **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.28- **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.29- **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.30- **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.31- **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.32 33## Sub-commands34 35| Sub-command | Description |36|-------------|-------------|37| `token info` | Basic info + realtime price, liquidity, market cap, total supply, holder count, social links (market cap = price × circulating_supply) |38| `token security` | Security metrics (honeypot, taxes, holder concentration, contract risks) |39| `token pool` | Liquidity pool info (DEX, reserves, liquidity depth) |40| `token holders` | Top token holders list with profit/loss breakdown |41| `token traders` | Top token traders list with profit/loss breakdown |42 43## Supported Chains44 45`sol` / `bsc` / `base`46 47## Prerequisites48 49- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`50- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`51 52## Rate Limit Handling53 54All token routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.55 56| Command | Route | Weight |57|---------|-------|--------|58| `token info` | `GET /v1/token/info` | 1 |59| `token security` | `GET /v1/token/security` | 1 |60| `token pool` | `GET /v1/token/pool_info` | 1 |61| `token holders` | `GET /v1/market/token_top_holders` | 5 |62| `token traders` | `GET /v1/market/token_top_traders` | 5 |63 64When a request returns `429`:65 66- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.67- 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.68- 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.69- 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.70 71**First-time setup** (if `GMGN_API_KEY` is not configured):72 731. Generate key pair and show the public key to the user:74   ```bash75   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \76     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null77   ```78   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."*79 802. Wait for the user's API key, then configure:81   ```bash82   mkdir -p ~/.config/gmgn83   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env84   chmod 600 ~/.config/gmgn/.env85   ```86 87## Parameters — `token info` / `token security` / `token pool`88 89| Parameter | Required | Description |90|-----------|----------|-------------|91| `--chain` | Yes | `sol` / `bsc` / `base` |92| `--address` | Yes | Token contract address |93| `--raw` | No | Output raw single-line JSON (for piping or further processing) |94 95## Parameters — `token holders` / `token traders`96 97| Parameter | Required | Default | Description |98|-----------|----------|---------|-------------|99| `--chain` | Yes | — | `sol` / `bsc` / `base` |100| `--address` | Yes | — | Token contract address |101| `--limit` | No | `20` | Number of results, max `100` |102| `--order-by` | No | `amount_percentage` | Sort field — see table below |103| `--direction` | No | `desc` | Sort direction: `asc` / `desc` |104| `--tag` | No | — | Wallet filter: `renowned` (KOL wallets) / `smart_degen` (smart money). Omit to return all wallets. |105| `--raw` | No | — | Output raw single-line JSON |106 107### `--order-by` Values108 109| Value | Description |110|-------|-------------|111| `amount_percentage` | Sort by percentage of total supply held (default) |112| `profit` | Sort by realized profit in USD |113| `unrealized_profit` | Sort by unrealized profit in USD |114| `buy_volume_cur` | Sort by buy volume |115| `sell_volume_cur` | Sort by sell volume |116 117### `--tag` Values118 119| Value | Description |120|-------|-------------|121| `renowned` | KOL / well-known wallets (influencers, funds, public figures) |122| `smart_degen` | Smart money wallets (historically high-performing traders) |123 124### `--tag` + `--order-by` Combination Guide125 126`--tag` and `--order-by` are independent — all `--order-by` values are valid with or without `--tag`. Omitting `--tag` returns all wallets (no filter).127 128Recommended combinations for common use cases:129 130| Goal | `--tag` | `--order-by` |131|------|---------|--------------|132| Largest smart money holders by supply | `smart_degen` | `amount_percentage` |133| Smart money with highest realized profit | `smart_degen` | `profit` |134| Smart money sitting on unrealized gains | `smart_degen` | `unrealized_profit` |135| Smart money aggressively accumulating | `smart_degen` | `buy_volume_cur` |136| Smart money distributing (exit signal) | `smart_degen` | `sell_volume_cur` |137| KOLs who already took profit | `renowned` | `profit` |138| KOLs still holding with paper gains | `renowned` | `unrealized_profit` |139| Largest holders overall (no filter) | *(omit)* | `amount_percentage` |140 141## Response Field Reference142 143### `token info` — Key Fields144 145The 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`).146 147**Top-level Fields**148 149| Field | Description |150|-------|-------------|151| `address` | Token contract address |152| `symbol` / `name` | Token ticker and full name |153| `decimals` | Token decimal places |154| `total_supply` | Total token supply (same as `circulating_supply` for most tokens) |155| `circulating_supply` | Circulating supply |156| `max_supply` | Maximum supply |157| `price` | Current price in USD |158| `liquidity` | Total liquidity in USD (from biggest pool) |159| `holder_count` | Number of unique token holders |160| `logo` | Token logo image URL |161| `creation_timestamp` | Token creation time (Unix seconds) |162| `open_timestamp` | Time the token opened for trading (Unix seconds) |163| `biggest_pool_address` | Address of the main liquidity pool |164| `og` | Whether the token is flagged as an OG token (`true` / `false`) |165| `launchpad` | Launchpad identifier (e.g. `pump`, `moonshot`) |166| `launchpad_status` | Launchpad state: `0` = not opened, `1` = live, `2` = migrated |167| `launchpad_progress` | Launchpad bonding-curve progress (0–1) |168| `launchpad_platform` | Launchpad platform name |169| `migrated_pool` | Pool address after migration |170| `migration_market_cap` | Market cap at migration time (USD, float) |171| `migration_market_cap_quote` | Quote currency for `migration_market_cap` |172| `ath_price` | All-time-high price (USD, float) |173| `locked_ratio` | Ratio of supply locked (0–1, float) |174 175**`pool` Object** — Main liquidity pool details176 177| Field | Description |178|-------|-------------|179| `pool.pool_address` | Pool contract address |180| `pool.quote_address` | Quote token address (e.g. USDC, SOL, WETH) |181| `pool.quote_symbol` | Quote token symbol (e.g. `USDC`, `SOL`) |182| `pool.exchange` | DEX name (e.g. `meteora_dlmm`, `raydium`, `pump_amm`, `uniswap_v3`) |183| `pool.liquidity` | Pool liquidity in USD |184| `pool.base_reserve` | Base token reserve amount |185| `pool.quote_reserve` | Quote token reserve amount |186| `pool.base_reserve_value` | Base reserve USD value |187| `pool.quote_reserve_value` | Quote reserve USD value |188| `pool.fee_ratio` | Pool trading fee ratio (e.g. `0.1` = 0.1%) |189| `pool.creation_timestamp` | Pool creation time (Unix seconds) |190 191**`dev` Object** — Token creator / developer info192 193| Field | Description |194|-------|-------------|195| `dev.creator_address` | Creator wallet address |196| `dev.creator_token_balance` | Creator's current token balance |197| `dev.creator_token_status` | Creator holding status: `hold` (still holding) / `sell` (sold/exited) |198| `dev.top_10_holder_rate` | Ratio of supply held by top 10 wallets (0–1) |199| `dev.twitter_name_change_history` | Array of past Twitter username changes (each entry has `twitter_username`, `rename_timestamp`) |200| `dev.dexscr_ad` | Creator bought a DEXScreener ad: `1` = yes, `0` = no |201| `dev.dexscr_update_link` | Creator updated DEXScreener socials/links: `1` = yes, `0` = no |202| `dev.dexscr_boost_fee` | Creator used DEXScreener Boost: `1` = yes, `0` = no |203| `dev.dexscr_trending_bar` | Token appeared in DEXScreener trending bar: `1` = yes, `0` = no |204| `dev.dexscr_ad_ts` | Timestamp of DEXScreener ad purchase (Unix seconds) |205| `dev.dexscr_update_link_ts` | Timestamp of DEXScreener link update (Unix seconds) |206| `dev.dexscr_boost_ts` | Timestamp of DEXScreener Boost (Unix seconds) |207| `dev.dexscr_trending_bar_ts` | Timestamp of DEXScreener trending bar appearance (Unix seconds) |208| `dev.cto_flag` | Token has been Community Takeover'd (original dev abandoned): `1` = yes, `0` = no |209| `dev.fund_from` | Address that funded the creator wallet |210| `dev.fund_from_ts` | Timestamp of that funding event (Unix seconds) |211| `dev.creator_open_count` | Number of tokens this creator has previously launched |212| `dev.twitter_del_post_token_count` | Number of posts the creator deleted from Twitter |213| `dev.twitter_create_token_count` | Number of tokens the creator has promoted on Twitter |214| `dev.offchain` | Whether the token is an offchain token |215| `dev.ath_token_info` | Creator's all-time-high token info object (optional); see sub-fields below |216| `dev.ath_token_info.ath_token` | Contract address of the creator's best-performing token ever |217| `dev.ath_token_info.ath_mc` | All-time-high market cap of that token (USD, string) |218| `dev.ath_token_info.avatar` | Token logo URL |219| `dev.ath_token_info.symbol` | Token symbol |220| `dev.ath_token_info.name` | Token name |221| `dev.ath_token_info.creation_timestamp` | Token creation time (Unix seconds) |222 223**`link` Object** — Social and explorer links224 225| Field | Description |226|-------|-------------|227| `link.twitter_username` | Twitter / X username (not full URL) |228| `link.website` | Project website URL |229| `link.telegram` | Telegram URL |230| `link.discord` | Discord URL |231| `link.instagram` | Instagram URL |232| `link.tiktok` | TikTok URL |233| `link.youtube` | YouTube URL |234| `link.description` | Token description text |235| `link.gmgn` | GMGN token page URL |236| `link.geckoterminal` | GeckoTerminal page URL |237| `link.verify_status` | Social verification status (integer) |238 239**`stat` Object** — On-chain statistics240 241| Field | Description |242|-------|-------------|243| `stat.holder_count` | Number of holders (same as top-level `holder_count`) |244| `stat.bluechip_owner_count` | Number of bluechip wallet holders |245| `stat.bluechip_owner_percentage` | Ratio of holders that are bluechip wallets (0–1) |246| `stat.top_10_holder_rate` | Ratio of supply held by top 10 wallets (0–1) |247| `stat.dev_team_hold_rate` | Ratio held by dev team wallets |248| `stat.creator_hold_rate` | Ratio held by creator wallet |249| `stat.creator_token_balance` | Raw creator token balance |250| `stat.top_rat_trader_percentage` | Ratio of volume from rat/insider traders |251| `stat.top_bundler_trader_percentage` | Ratio of volume from bundler bots |252| `stat.top_entrapment_trader_percentage` | Ratio of volume from entrapment traders |253| `stat.bot_degen_count` | Number of bot degen wallets |254| `stat.bot_degen_rate` | Ratio of bot degen wallets |255| `stat.fresh_wallet_rate` | Ratio of fresh/new wallets among holders |256| `stat.private_vault_hold_rate` | Ratio held by private vault (vanish) addresses — displayed as "vanish" in GMGN UI (0–1) |257 258**`wallet_tags_stat` Object** — Wallet type breakdown259 260| Field | Description |261|-------|-------------|262| `wallet_tags_stat.smart_wallets` | Number of smart money wallets holding the token |263| `wallet_tags_stat.renowned_wallets` | Number of renowned / KOL wallets holding the token |264| `wallet_tags_stat.sniper_wallets` | Number of sniper wallets |265| `wallet_tags_stat.rat_trader_wallets` | Number of rat trader wallets |266| `wallet_tags_stat.bundler_wallets` | Number of bundler bot wallets |267| `wallet_tags_stat.whale_wallets` | Number of whale wallets |268| `wallet_tags_stat.fresh_wallets` | Number of fresh wallets |269| `wallet_tags_stat.top_wallets` | Number of top-ranked wallets |270 271---272 273### `token security` — Key Fields274 275**Contract Safety**276 277| Field | Chains | Description |278|-------|--------|-------------|279| `is_honeypot` | BSC / Base | Whether token is a honeypot (`"yes"` / `"no"`); empty string on SOL |280| `open_source` | all | Contract source code verified: `"yes"` / `"no"` / `"unknown"` |281| `owner_renounced` | all | Contract ownership renounced: `"yes"` / `"no"` / `"unknown"` |282| `renounced_mint` | SOL | Mint authority renounced (SOL-specific; always `false` on EVM) |283| `renounced_freeze_account` | SOL | Freeze authority renounced (SOL-specific; always `false` on EVM) |284| `buy_tax` / `sell_tax` | all | Tax ratio — e.g. `0.03` = 3%; `0` = no tax |285 286**Holder Concentration & Risk**287 288| Field | Description |289|-------|-------------|290| `top_10_holder_rate` | Ratio of supply held by top 10 wallets (0–1); higher = more concentrated |291| `dev_team_hold_rate` | Ratio held by dev team wallets |292| `creator_balance_rate` | Ratio held by the token creator wallet |293| `creator_token_status` | Dev holding status: `creator_hold` (still holding) / `creator_close` (sold/closed) |294| `suspected_insider_hold_rate` | Ratio held by suspected insider wallets |295 296**Trading Risk**297 298| Field | Description |299|-------|-------------|300| `rug_ratio` | Rug pull risk score (0–1); higher = more risky |301| `is_wash_trading` | Whether wash trading activity is detected (`true` / `false`) |302| `rat_trader_amount_rate` | Ratio of volume from sneak/insider trading |303| `bundler_trader_amount_rate` | Ratio of volume from bundle trading (bot-driven) |304| `sniper_count` | Number of sniper wallets that bought at launch |305| `burn_status` | Liquidity pool burn status (e.g. `"burn"` = burned, `""` = not burned) |306 307---308 309### `token pool` — Key Fields310 311| Field | Description |312|-------|-------------|313| `address` | Pool contract address |314| `base_address` | Base token address (the queried token) |315| `quote_address` | Quote token address (e.g. SOL, USDC, WETH) |316| `exchange` | DEX name (e.g. `raydium`, `pump_amm`, `uniswap_v3`, `pancakeswap`) |317| `liquidity` | Pool liquidity in USD |318| `base_reserve` | Base token reserve amount |319| `quote_reserve` | Quote token reserve amount |320| `price` | Current price in USD derived from pool reserves |321| `creation_timestamp` | Pool creation time (Unix seconds) |322 323---324 325### `token holders` / `token traders` — Response Fields326 327The response is an object with a `list` array. Each item in `list` represents one wallet.328 329**Identity & Holdings**330 331| Field | Description |332|-------|-------------|333| `address` | Wallet address |334| `account_address` | Token account address (the on-chain account holding the token, distinct from the wallet address) |335| `addr_type` | Address type: `0` = regular wallet, `2` = exchange / liquidity pool |336| `exchange` | Exchange or pool name if `addr_type` is `2` (e.g. `pump_amm`, `raydium`) |337| `wallet_tag_v2` | Rank label in this list (e.g. `TOP1`, `TOP2`, ...) |338| `native_balance` | Native token balance in smallest unit (lamports for SOL) |339| `balance` | Current token balance (human-readable units) |340| `amount_cur` | Same as `balance` — current token amount held |341| `usd_value` | USD value of current holdings at current price |342| `amount_percentage` | Ratio of total supply held (0–1); e.g. `0.05` = 5% |343| `is_on_curve` | `true` = still on bonding curve (pump.fun pre-graduation); `false` = open market |344| `is_new` | Whether this is a newly created wallet |345| `is_suspicious` | Whether this wallet is flagged as suspicious |346| `transfer_in` | Whether the current holding was received via transfer (not bought) |347 348**Trading Summary**349 350| Field | Description |351|-------|-------------|352| `buy_volume_cur` | Total buy volume in USD |353| `sell_volume_cur` | Total sell volume in USD |354| `buy_amount_cur` | Total tokens bought |355| `sell_amount_cur` | Total tokens sold |356| `sell_amount_percentage` | Ratio of bought tokens that have been sold (0–1); `1.0` = fully exited |357| `buy_tx_count_cur` | Number of buy transactions |358| `sell_tx_count_cur` | Number of sell transactions |359| `netflow_usd` | Net USD flow = sell income − buy cost (negative = net spent) |360| `netflow_amount` | Net token flow = bought − sold (positive = still holding net position) |361 362**Cost & P&L**363 364| Field | Description |365|-------|-------------|366| `avg_cost` | Average buy price in USD per token |367| `avg_sold` | Average sell price in USD per token |368| `history_bought_cost` | Total USD spent buying |369| `history_bought_fee` | Total fees paid on buys in USD |370| `history_sold_income` | Total USD received from selling |371| `history_sold_fee` | Total fees paid on sells in USD |372| `total_cost` | Total cost basis including fees |373| `profit` | Total profit in USD (realized + unrealized) |374| `profit_change` | Total profit ratio = profit / total_cost |375| `realized_profit` | Realized profit in USD from completed sells |376| `realized_pnl` | Realized profit ratio = realized_profit / buy_cost |377| `unrealized_profit` | Unrealized profit in USD on current holdings at current price |378| `unrealized_pnl` | Unrealized profit ratio; `null` if no current holdings |379 380**Transfer History**381 382| Field | Description |383|-------|-------------|384| `current_transfer_in_amount` | Tokens received via transfer (not bought) in current period |385| `current_transfer_out_amount` | Tokens sent out via transfer (not sold) in current period |386| `history_transfer_in_amount` | Historical total tokens received via transfer |387| `history_transfer_in_cost` | Estimated cost basis of transferred-in tokens |388| `history_transfer_out_amount` | Historical total tokens sent out via transfer |389| `history_transfer_out_income` | Estimated income from transferred-out tokens |390| `history_transfer_out_fee` | Fees paid on transfer-outs |391| `transfer_in_count` | Number of inbound transfers |392| `transfer_out_count` | Number of outbound transfers |393 394**Timing**395 396| Field | Description |397|-------|-------------|398| `start_holding_at` | Unix timestamp when wallet first acquired this token |399| `end_holding_at` | Unix timestamp when wallet fully exited; `null` if still holding |400| `last_active_timestamp` | Unix timestamp of most recent on-chain activity for this token |401| `last_block` | Block number of last activity |402 403**Wallet Identity**404 405| Field | Description |406|-------|-------------|407| `name` | Wallet display name (if known) |408| `twitter_username` | Twitter / X username |409| `twitter_name` | Twitter / X display name |410| `avatar` | Avatar image URL |411| `tags` | Platform-level wallet tags (e.g. `["kol"]`, `["smart_degen"]`, `["axiom"]`) |412| `maker_token_tags` | Token-specific behavior tags for this wallet (e.g. `["bundler"]`, `["paper_hands"]`, `["top_holder"]`) |413| `created_at` | Wallet creation timestamp (Unix seconds); `0` if unknown |414 415**Last Transaction Records**416 417Each of the following is an object with `name`, `address`, `timestamp`, `tx_hash`, `type`:418 419| Field | Description |420|-------|-------------|421| `native_transfer` | Most recent native token (SOL/BNB/ETH) transfer associated with this wallet |422| `token_transfer` | Most recent token transfer (buy or sell) |423| `token_transfer_in` | Most recent inbound token transfer |424| `token_transfer_out` | Most recent outbound token transfer |425 426---427 428## Usage Examples429 430### `token info` — Fetch Basic Info and Price431 432```bash433# Get current price and market cap for a SOL token434gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v435 436# Get basic info for a BSC token437gmgn-cli token info --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8438 439# Get basic info for a Base token440gmgn-cli token info --chain base --address 0x4200000000000000000000000000000000000006441 442# Raw JSON output for downstream processing443gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --raw444```445 446### `token security` — Check Safety Before Buying447 448```bash449# Check if a SOL token has renounced mint + freeze authority450gmgn-cli token security --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v451 452# Check if a BSC token is honeypot and whether contract is verified453gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8454 455# Check a Base token for tax, rug ratio, and insider concentration456gmgn-cli token security --chain base --address 0x4200000000000000000000000000000000000006457 458# Raw output for parsing key fields (e.g. is_honeypot, buy_tax, rug_ratio)459gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 --raw460```461 462### `token pool` — Check Liquidity Depth463 464```bash465# Get pool info for a SOL token (liquidity, reserves, DEX)466gmgn-cli token pool --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v467 468# Get pool info for a BSC token469gmgn-cli token pool --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8470```471 472### `token holders` — Analyze Holder Distribution473 474```bash475# Top 20 holders by supply percentage (default)476gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v477 478# Top 50 holders sorted by percentage held479gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \480  --limit 50 --order-by amount_percentage --direction desc481 482# Top 50 smart money holders (highest conviction wallets)483gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \484  --limit 50 --tag smart_degen --order-by amount_percentage485 486# Top KOL wallets ranked by realized profit (who has already taken profit)487gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \488  --tag renowned --order-by profit --direction desc --limit 20489 490# Smart money with most unrealized profit (who is sitting on biggest gains)491gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \492  --tag smart_degen --order-by unrealized_profit --direction desc --limit 20493 494# Holders who have been buying the most recently (buy momentum signal)495gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \496  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20497 498# Holders who are selling the most (exit signal / distribution warning)499gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \500  --tag renowned --order-by sell_volume_cur --direction desc --limit 20501 502# BSC token holders — KOL wallets by profit503gmgn-cli token holders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \504  --tag renowned --order-by profit --direction desc --limit 50505 506# Raw output for downstream analysis507gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \508  --limit 100 --raw509```510 511### `token traders` — `--tag` + `--order-by` Combination Guide512 513Use this table to pick the right combination for common `token traders` use cases:514 515| Use case | `--tag` | `--order-by` |516|----------|---------|-------------|517| Smart money with highest buy volume | `smart_degen` | `buy_volume_cur` |518| Smart money with highest sell volume (exit signal) | `smart_degen` | `sell_volume_cur` |519| KOLs recently active | `renowned` | `last_active_timestamp` |520| Smart money most profitable traders | `smart_degen` | `profit` |521| Snipers still holding | `sniper` | `amount_percentage` |522| Smart money sitting on biggest unrealized gains | `smart_degen` | `unrealized_profit` |523| KOLs who already took profit | `renowned` | `profit` |524 525### `token traders` — Find Active Traders526 527```bash528# Top 20 active traders by supply held (default)529gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v530 531# Smart money traders ranked by realized profit532gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \533  --tag smart_degen --order-by profit --direction desc --limit 50534 535# KOL traders ranked by unrealized profit (still holding with paper gains)536gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \537  --tag renowned --order-by unrealized_profit --direction desc --limit 20538 539# Smart money traders with highest buy volume (aggressive accumulation)540gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \541  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20542 543# Smart money traders ranked by sell volume (who is distributing)544gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \545  --tag smart_degen --order-by sell_volume_cur --direction desc --limit 20546 547# Worst performing KOL traders (who lost the most — contrarian signal)548gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \549  --tag renowned --order-by profit --direction asc --limit 20550 551# BSC token traders by profit552gmgn-cli token traders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \553  --tag smart_degen --order-by profit --direction desc --limit 50554```555 556---557 558## Token Quick Scoring Card559 560After 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.561 562| Field | ✅ Safe | ⚠️ Warning | 🚫 Danger (Hard Stop) |563|-------|---------|-----------|----------------------|564| `is_honeypot` | `"no"` | — | `"yes"` → **stop immediately** |565| `open_source` | `"yes"` | `"unknown"` | `"no"` |566| `owner_renounced` | `"yes"` | `"unknown"` | `"no"` |567| `renounced_mint` (SOL) | `true` | — | `false` |568| `renounced_freeze_account` (SOL) | `true` | — | `false` |569| `rug_ratio` | `< 0.10` | `0.10–0.30` | `> 0.30` |570| `top_10_holder_rate` | `< 0.20` | `0.20–0.50` | `> 0.50` |571| `creator_token_status` | `creator_close` | — | `creator_hold` |572| `buy_tax` / `sell_tax` | `0` | `0.01–0.05` | `> 0.10` |573| `sniper_count` | `< 5` | `5–20` | `> 20` |574| `smart_wallets` (from `wallet_tags_stat`) | `≥ 3` | `1–2` | `0` (bearish, not a hard stop) |575| `renowned_wallets` (from `wallet_tags_stat`) | `≥ 1` | — | `0` (neutral, not a hard stop) |576 577**Final scoring logic:**578- If `is_honeypot = "yes"` → **hard stop immediately**, do not proceed regardless of other signals579- If other 🚫 fields present → **skip** (strong warning — present to user)580- `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 tokens581- If 3+ ⚠️ with no 🚫 → **needs more research** — present findings and ask user how to proceed582- If mostly ✅ with `smart_wallets ≥ 3` → **worth researching** — proceed to holders/traders analysis583 584## Workflow: Full Token Due Diligence585 586When the user asks for a full token research / due diligence, follow the steps in [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md).587 588Steps: `token info` → `token security` → `token pool` → market heat check → `token holders/traders` (smart money signals) → Decision Framework.589 590**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`](../../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.591 592**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`](../../docs/workflow-risk-warning.md). Uses `token security` + `token pool` + `token holders` to flag whale exits, liquidity drain, and developer dumps.593 594---595 596## Output Format597 598### `token info` — Summary Card599 600Present as a concise card. Do not dump raw JSON.601 602```603{symbol} ({name})604Price: ${price}  |  Market Cap: ~${price × circulating_supply}  |  Liquidity: ${liquidity}605Holders: {holder_count}  |  Smart Money: {wallet_tags_stat.smart_wallets}  |  KOLs: {wallet_tags_stat.renowned_wallets}606Social: @{link.twitter_username}  |  {link.website}  |  {link.telegram}607```608 609If any social fields are empty, omit them rather than showing `null`.610 611### `token security` — Risk Assessment Summary612 613After fetching security data, present a structured risk summary using this format:614 615```616Token: {symbol}  |  Chain: {chain}  |  Address: {short address}617─── Security ──────────────────────────────────────618Contract verified:    ✅ yes  / 🚫 no / ⚠️ unknown619Owner renounced:      ✅ yes  / 🚫 no / ⚠️ unknown620Honeypot:             ✅ no   / 🚫 YES — DO NOT BUY621Mint renounced (SOL): ✅ yes  / ⚠️ no622Freeze renounced(SOL):✅ yes  / ⚠️ no623Rug risk score:       {rug_ratio} → ✅ <0.1 Low / ⚠️ 0.1–0.3 Med / 🚫 >0.3 High624Top-10 holder %:      {top_10_holder_rate%} → ✅ <20% / ⚠️ 20–50% / 🚫 >50%625Dev still holding:    ✅ sold (creator_close) / ⚠️ holding (creator_hold)626Sniper wallets:       ✅ <5  / ⚠️ 5–20 / 🚫 >20627─── Smart Money ───────────────────────────────────628SM holders: {smart_wallets}   KOL holders: {renowned_wallets}629─── Verdict ───────────────────────────────────────630🟢 Clean — worth researching631🟡 Mixed signals — proceed with caution632🔴 Red flags present — skip or verify manually633```634 635**If `is_honeypot = "yes"`, stop immediately and display: "🚫 HONEYPOT DETECTED — Do not buy this token." Do NOT proceed to further analysis steps.**636 637### `token holders` / `token traders` — Ranked Table638 639```640# | Wallet (name or short addr) | Hold% | Avg Buy | Realized P&L | Unrealized P&L | Tags641```642 643Show top rows only. Highlight wallets tagged `kol`, `smart_degen`, or flagged `bundler` / `rat_trader` in `maker_token_tags`.644 645## Notes646 647- **Market cap is not returned directly** — calculate it as `price × circulating_supply` (both fields are top-level; `circulating_supply` is already in human-readable token units, no decimal adjustment needed). Example: `price=3.11` × `circulating_supply=999999151` ≈ $3.11B market cap.648- **Trading volume (1h, 24h, etc.) is not included in `token info`** — to get volume or OHLCV data, use the `gmgn-market` skill and query K-line data: `gmgn-cli market kline --chain <chain> --address <token_address> --resolution <1m|5m|15m|1h|4h|1d>`. See the `gmgn-market` SKILL.md for full details.649- All token commands use normal auth (API Key only, no signature required)650- Use `--raw` to get single-line JSON for further processing651- `--tag` applies to both `holders` and `traders` and filters to only wallets with that tag — if few results are returned, try the other tag value652- `amount_percentage` in holders/traders is a ratio (0–1), not a percentage — `0.05` means 5% of supply653- **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.