gmgn-token

$27

• 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-command

Description

token info

Basic info + realtime price, liquidity, market cap, total supply, holder count, social links (market cap = price.price × circulating_supply)

token security

Security metrics (honeypot, taxes, holder concentration, contract risks)

token pool

Liquidity pool info (DEX, reserves, liquidity depth)

token holders

Top token holders list with profit/loss breakdown

token traders

Top 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.

Command

Route

Weight

token info

GET /v1/token/info

1

token security

GET /v1/token/security

1

token pool

GET /v1/token/pool_info

1

token holders

GET /v1/market/token_top_holders

5

token traders

GET /v1/market/token_top_traders

5

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

-

Generate key pair and show the public key to the user:

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

-

Wait for the user's API key, then configure:

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

Parameter

Required

Description

--chain

Yes

sol / bsc / base / eth

--address

Yes

Token contract address

--raw

No

Output raw single-line JSON (for piping or further processing)

Parameters — token holders / token traders

Parameter

Required

Default

Description

--chain

Yes

—

sol / bsc / base / eth

--address

Yes

—

Token contract address

--limit

No

20

Number of results, max 100

--order-by

No

amount_percentage

Sort field — see table below

--direction

No

desc

Sort direction: asc / desc

--tag

No

—

Wallet filter: smart_degen / renowned / fresh_wallet / dev / sniper / rat_trader / bundler / transfer_in / dex_bot / bluechip_owner. Omit to return all wallets.

--raw

No

—

Output raw single-line JSON

--order-by Values

Value

Description

amount_percentage

Sort by percentage of total supply held (default)

profit

Sort by realized profit in USD

unrealized_profit

Sort by unrealized profit in USD

buy_volume_cur

Sort by buy volume

sell_volume_cur

Sort by sell volume

--tag Values

Value

Description

smart_degen

Smart money wallets (historically high-performing traders)

renowned

KOL / well-known wallets (influencers, funds, public figures)

fresh_wallet

New wallets with no prior trading history

dev

Token developer / creator wallets

sniper

Wallets that sniped the token at launch

rat_trader

Insider / sneak-trading wallets

bundler

Bot-bundled buy wallets

transfer_in

Wallets with a transfer-in record for this token

dex_bot

DEX bot wallets (Axiom, Photon, BullX, Trojan, GMGN, Drops, PepeBoost, Padre)

bluechip_owner

Wallets 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-by

Largest smart money holders by supply

smart_degen

amount_percentage

Smart money with highest realized profit

smart_degen

profit

Smart money sitting on unrealized gains

smart_degen

unrealized_profit

Smart money aggressively accumulating

smart_degen

buy_volume_cur

Smart money distributing (exit signal)

smart_degen

sell_volume_cur

KOLs who already took profit

renowned

profit

KOLs still holding with paper gains

renowned

unrealized_profit

Largest 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

Field

Description

address

Token contract address

symbol / name

Token ticker and full name

decimals

Token decimal places

total_supply

Total token supply (same as circulating_supply for most tokens)

circulating_supply

Circulating supply

max_supply

Maximum supply

price

Object — price and trading stats (see price Object below). Access current price as price.price.

liquidity

Total liquidity in USD (from biggest pool)

holder_count

Number of unique token holders

logo

Token logo image URL

creation_timestamp

Token creation time (Unix seconds)

open_timestamp

Time the token opened for trading (Unix seconds)

biggest_pool_address

Address of the main liquidity pool

og

Whether the token is flagged as an OG token (true / false)

launchpad

Launchpad identifier (e.g. pump, moonshot)

launchpad_status

Launchpad state: 0 = not opened, 1 = live, 2 = migrated

launchpad_progress

Launchpad bonding-curve progress (0–1)

launchpad_platform

Launchpad platform name

migrated_pool

Pool address after migration

migration_market_cap

Market cap at migration time (USD, float)

migration_market_cap_quote

Quote currency for migration_market_cap

ath_price

All-time-high price (USD, float)

locked_ratio

Ratio of supply locked (0–1, float)

**pool Object** — Main liquidity pool details

Field

Description

pool.pool_address

Pool contract address

pool.quote_address

Quote token address (e.g. USDC, SOL, WETH)

pool.quote_symbol

Quote token symbol (e.g. USDC, SOL)

pool.exchange

DEX name (e.g. meteora_dlmm, raydium, pump_amm, uniswap_v3)

pool.liquidity

Pool liquidity in USD

pool.base_reserve

Base token reserve amount

pool.quote_reserve

Quote token reserve amount

pool.base_reserve_value

Base reserve USD value

pool.quote_reserve_value

Quote reserve USD value

pool.fee_ratio

Pool trading fee ratio (e.g. 0.1 = 0.1%)

pool.creation_timestamp

Pool creation time (Unix seconds)

**dev Object** — Token creator / developer info

Field

Description

dev.creator_address

Creator wallet address

dev.creator_token_balance

Creator's current token balance

dev.creator_token_status

Creator holding status: hold (still holding) / sell (sold/exited)

dev.top_10_holder_rate

Ratio of supply held by top 10 wallets (0–1)

dev.twitter_name_change_history

Array of past Twitter username changes (each entry has twitter_username, rename_timestamp)

dev.dexscr_ad

Creator bought a DEXScreener ad: 1 = yes, 0 = no

dev.dexscr_update_link

Creator updated DEXScreener socials/links: 1 = yes, 0 = no

dev.dexscr_boost_fee

Creator used DEXScreener Boost: 1 = yes, 0 = no

dev.dexscr_trending_bar

Token appeared in DEXScreener trending bar: 1 = yes, 0 = no

dev.dexscr_ad_ts

Timestamp of DEXScreener ad purchase (Unix seconds)

dev.dexscr_update_link_ts

Timestamp of DEXScreener link update (Unix seconds)

dev.dexscr_boost_ts

Timestamp of DEXScreener Boost (Unix seconds)

dev.dexscr_trending_bar_ts

Timestamp of DEXScreener trending bar appearance (Unix seconds)

dev.cto_flag

Token has been Community Takeover'd (original dev abandoned): 1 = yes, 0 = no

dev.fund_from

Address that funded the creator wallet

dev.fund_from_ts

Timestamp of that funding event (Unix seconds)

dev.creator_open_count

Number of tokens this creator has previously launched

dev.twitter_del_post_token_count

Number of posts the creator deleted from Twitter

dev.twitter_create_token_count

Number of tokens the creator has promoted on Twitter

dev.offchain

Whether the token is an offchain token

dev.ath_token_info

Creator's all-time-high token info object (optional); see sub-fields below

dev.ath_token_info.ath_token

Contract address of the creator's best-performing token ever

dev.ath_token_info.ath_mc

All-time-high market cap of that token (USD, string)

dev.ath_token_info.avatar

Token logo URL

dev.ath_token_info.symbol

Token symbol

dev.ath_token_info.name

Token name

dev.ath_token_info.creation_timestamp

Token creation time (Unix seconds)

**link Object** — Social and explorer links

Field

Description

link.twitter_username

Twitter / X username (not full URL)

link.website

Project website URL

link.telegram

Telegram URL

link.discord

Discord URL

link.instagram

Instagram URL

link.tiktok

TikTok URL

link.youtube

YouTube URL

link.description

Token description text

link.gmgn

GMGN token page URL

link.geckoterminal

GeckoTerminal page URL

link.verify_status

Social verification status (integer)

**stat Object** — On-chain statistics

Field

Description

stat.holder_count

Number of holders (same as top-level holder_count)

stat.top_10_holder_rate

Ratio of supply held by top 10 wallets (0–1)

stat.dev_team_hold_rate

Ratio held by dev team wallets

stat.creator_hold_rate

Ratio held by creator wallet

stat.creator_token_balance

Raw creator token balance

stat.top_rat_trader_percentage

Ratio of volume from rat/insider traders

stat.top_bundler_trader_percentage

Ratio of volume from bundler bots

stat.top_entrapment_trader_percentage

Ratio of volume from entrapment traders

stat.bot_degen_count

Number of bot degen wallets

stat.bot_degen_rate

Ratio of bot degen wallets

stat.fresh_wallet_rate

Ratio of fresh/new wallets among holders

stat.private_vault_hold_rate

Ratio held by private vault (vanish) addresses — displayed as "vanish" in GMGN UI (0–1)

**wallet_tags_stat Object** — Wallet type breakdown

Field

Description

wallet_tags_stat.smart_wallets

Number of smart money wallets holding the token

wallet_tags_stat.renowned_wallets

Number of renowned / KOL wallets holding the token

wallet_tags_stat.sniper_wallets

Number of sniper wallets

wallet_tags_stat.rat_trader_wallets

Number of rat trader wallets

wallet_tags_stat.bundler_wallets

Number of bundler bot wallets

wallet_tags_stat.whale_wallets

Number of whale wallets

wallet_tags_stat.fresh_wallets

Number of fresh wallets

wallet_tags_stat.top_wallets

Number of top-ranked wallets

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

Field

Description

price.price

Current 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 window

price.sells_{window}

Sell transaction count in the window

price.volume_{window}

Total trading volume in USD for the window

price.buy_volume_{window}

Buy volume in USD for the window

price.sell_volume_{window}

Sell volume in USD for the window

price.swaps_{window}

Total swap count for the window

price.hot_level

Heat level integer

**fee_distribution Object** — Launchpad fee-sharing config (optional; present for pump / bankr tokens)

Field

Description

fee_distribution.launchpad

Launchpad identifier: "pump", "bankr", or "" (unknown)

fee_distribution.platform_data

Platform-specific fee config; structure varies by launchpad (see below)

When fee_distribution.launchpad = "pump":

Field

Description

platform_data.fee_authority

Fee authority wallet address

platform_data.is_locked

Whether the fee config is locked

platform_data.show

Whether fee distribution is displayed in the UI

platform_data.list

Array of fee-share holders (see FeeShareHolder below)

platform_data.bonus_category

Bonus category list (e.g. creator_reward, cashback)

When fee_distribution.launchpad = "bankr":

Field

Description

platform_data.deployer

Original deployer wallet address

platform_data.fee_recipient

Fee recipient wallet address

platform_data.list

Array of fee-share holders (see FeeShareHolder below)

FeeShareHolder fields (each item in platform_data.list):

Field

Description

wallet

Wallet address

royalty_bps

Royalty share in basis points (10000 = 100%)

is_creator

Whether this is the original creator

has_claimed_fee

Whether fees have been claimed

username

Display name

pfp

Avatar URL

twitter_username

Twitter / X username

token security — Key Fields

Contract Safety

Field

Chains

Description

is_honeypot

BSC / Base

Whether token is a honeypot ("yes" / "no"); empty string on SOL

open_source

all

Contract source code verified: "yes" / "no" / "unknown"

owner_renounced

all

Contract ownership renounced: "yes" / "no" / "unknown"

renounced_mint

SOL

Mint authority renounced (SOL-specific; always false on EVM)

renounced_freeze_account

SOL

Freeze authority renounced (SOL-specific; always false on EVM)

buy_tax / sell_tax

all

Tax ratio — e.g. 0.03 = 3%; 0 = no tax

Holder Concentration &#x26; Risk

Field

Description

top_10_holder_rate

Ratio of supply held by top 10 wallets (0–1); higher = more concentrated

dev_team_hold_rate

Ratio held by dev team wallets

creator_balance_rate

Ratio held by the token creator wallet

creator_token_status

Dev holding status: creator_hold (still holding) / creator_close (sold/closed)

suspected_insider_hold_rate

Ratio held by suspected insider wallets

Trading Risk

Field

Description

rug_ratio

Rug pull risk score (0–1); higher = more risky

is_wash_trading

Whether wash trading activity is detected (true / false)

rat_trader_amount_rate

Ratio of volume from sneak/insider trading

bundler_trader_amount_rate

Ratio of volume from bundle trading (bot-driven)

sniper_count

Number of sniper wallets that bought at launch

burn_status

Liquidity pool burn status (e.g. "burn" = burned, "" = not burned)

token pool — Key Fields

Field

Description

address

Pool contract address

base_address

Base token address (the queried token)

quote_address

Quote token address (e.g. SOL, USDC, WETH)

exchange

DEX name (e.g. raydium, pump_amm, uniswap_v3, pancakeswap)

liquidity

Pool liquidity in USD

base_reserve

Base token reserve amount

quote_reserve

Quote token reserve amount

price

Current price in USD derived from pool reserves

creation_timestamp

Pool 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 &#x26; Holdings

Field

Description

address

Wallet address

account_address

Token account address (the on-chain account holding the token, distinct from the wallet address)

addr_type

Address type: 0 = regular wallet, 2 = exchange / liquidity pool

exchange

Exchange or pool name if addr_type is 2 (e.g. pump_amm, raydium)

wallet_tag_v2

Rank label in this list (e.g. TOP1, TOP2, ...)

native_balance

Native token balance in smallest unit (lamports for SOL)

balance

Current token balance (human-readable units)

amount_cur

Same as balance — current token amount held

usd_value

USD value of current holdings at current price

amount_percentage

Ratio 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 market

is_new

Whether this is a newly created wallet

is_suspicious

Whether this wallet is flagged as suspicious

transfer_in

Whether the current holding was received via transfer (not bought)

Trading Summary

Field

Description

buy_volume_cur

Total buy volume in USD

sell_volume_cur

Total sell volume in USD

buy_amount_cur

Total tokens bought

sell_amount_cur

Total tokens sold

sell_amount_percentage

Ratio of bought tokens that have been sold (0–1); 1.0 = fully exited

buy_tx_count_cur

Number of buy transactions

sell_tx_count_cur

Number of sell transactions

netflow_usd

Net USD flow = sell income − buy cost (negative = net spent)

netflow_amount

Net token flow = bought − sold (positive = still holding net position)

Cost &#x26; P&#x26;L

Field

Description

avg_cost

Average buy price in USD per token

avg_sold

Average sell price in USD per token

history_bought_cost

Total USD spent buying

history_bought_fee

Total fees paid on buys in USD

history_sold_income

Total USD received from selling

history_sold_fee

Total fees paid on sells in USD

total_cost

Total cost basis including fees

profit

Total profit in USD (realized + unrealized)

profit_change

Total profit ratio = profit / total_cost

realized_profit

Realized profit in USD from completed sells

realized_pnl

Realized profit ratio = realized_profit / buy_cost

unrealized_profit

Unrealized profit in USD on current holdings at current price

unrealized_pnl

Unrealized profit ratio; null if no current holdings

Transfer History

Field

Description

current_transfer_in_amount

Tokens received via transfer (not bought) in current period

current_transfer_out_amount

Tokens sent out via transfer (not sold) in current period

history_transfer_in_amount

Historical total tokens received via transfer

history_transfer_in_cost

Estimated cost basis of transferred-in tokens

history_transfer_out_amount

Historical total tokens sent out via transfer

history_transfer_out_income

Estimated income from transferred-out tokens

history_transfer_out_fee

Fees paid on transfer-outs

transfer_in_count

Number of inbound transfers

transfer_out_count

Number of outbound transfers

Timing

Field

Description

start_holding_at

Unix timestamp when wallet first acquired this token

end_holding_at

Unix timestamp when wallet fully exited; null if still holding

last_active_timestamp

Unix timestamp of most recent on-chain activity for this token

last_block

Block number of last activity

Wallet Identity

Field

Description

name

Wallet display name (if known)

twitter_username

Twitter / X username

twitter_name

Twitter / X display name

avatar

Avatar image URL

tags

Platform-level wallet tags (e.g. ["kol"], ["smart_degen"], ["axiom"])

maker_token_tags

Token-specific behavior tags for this wallet (e.g. ["bundler"], ["paper_hands"], ["top_holder"])

created_at

Wallet creation timestamp (Unix seconds); 0 if unknown

Shared Funding

Field

Description

native_transfer

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

Field

Description

token_transfer

Most recent token transfer (buy or sell)

token_transfer_in

Most recent inbound token transfer

token_transfer_out

Most recent outbound token transfer

Usage Examples

token info — Fetch Basic Info and Price

# 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

# 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

# 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

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

Smart money with highest buy volume

smart_degen

buy_volume_cur

Smart money with highest sell volume (exit signal)

smart_degen

sell_volume_cur

KOLs recently active

renowned

last_active_timestamp

Smart money most profitable traders

smart_degen

profit

Snipers still holding

sniper

amount_percentage

Smart money sitting on biggest unrealized gains

smart_degen

unrealized_profit

KOLs who already took profit

renowned

profit

token traders — Find Active Traders

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

open_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.

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

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

# | 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 (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.

• 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.