Gmgn Market

BEFORE RUNNING ANY COMMAND: Run gmgn-cli config --check. If exit code is 0, proceed normally. If exit code is 1, (1) run gmgn-cli config and show the output to the user; (2) once the user sends the API Key, run gmgn-cli config --apply <KEY> to complete configuration and verification, then show the output to the user. If --check returns an error (unknown option or command not found), tell the user to run npm install -g gmgn-cli to update, then retry.

IMPORTANT: Always use gmgn-cli commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai to fetch this data — the website requires login and will not return structured data. The CLI is the only correct method.

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

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

Use the gmgn-cli tool to query K-line data for a token, browse trending tokens, or view Trenches token lists.

Core Concepts

• --filter chain defaults — SOL and EVM chains have different default safety filters that are applied automatically when --filter is omitted. Do not assume the same defaults apply across chains:

  • SOL: defaults to renounced frozen (mint and freeze authority renounced)
  • BSC / Base / ETH (EVM): defaults to not_honeypot verified renounced
  • Omitting --filter is NOT the same as "no filter" — the chain defaults are always applied. To use a custom filter set, explicitly specify all desired filter tags.

• volume vs amount (kline) — Naming is counterintuitive. volume = USD dollar value of trades; amount = token units traded. For a token priced at $0.0002, these differ by 5,000×. Always use volume for "how much USD was traded" and amount for "how many tokens changed hands."

• rug_ratio — A 0–1 score estimating rug pull likelihood. Values above 0.3 are high-risk. Do not treat as binary — combine with top_10_holder_rate, dev_team_hold_rate, and is_honeypot for a full picture.

• smart_degen_count / renowned_count — Number of platform-tagged smart money wallets (smart_degen) and KOL wallets (renowned) holding or trading this token. High values are bullish signals. These are GMGN-tagged wallet lists, not user-defined.

• hot_level — Trending intensity score. Higher = more actively traded right now. Not normalized — compare relative values within the same result set, not across time windows.

• renounced_mint / renounced_freeze_account — SOL-specific. Indicate whether the creator gave up the ability to mint more tokens or freeze wallets. Both being 1 is a safety baseline on Solana. Always false on EVM chains (concept does not apply).

• is_honeypot — EVM-specific (BSC / Base). Indicates whether the token contract prevents selling. Always empty/null on SOL — do not interpret an empty value as "not a honeypot" on Solana.

• creator_token_status — Dev holding status. creator_hold = dev still holds tokens (sell pressure risk). creator_close = dev has sold or burned their allocation (exit signal confirmed).

• cto_flag — Community Takeover flag. 1 = original dev abandoned the project and a community group took over marketing/development. Neutral to positive signal; evaluate in context.

• Trenches categories — Three lifecycle stages of launchpad tokens: new_creation (just created, still on bonding curve), near_completion (bonding curve nearly full, about to graduate), completed (graduated to open market / DEX). In the response, near_completion is always returned under the key data.pump regardless of the input --type.

• wash_trading / rat_trader_amount_rate / bundler_rate — Risk signals for artificial activity. is_wash_trading = coordinated fake volume detected. rat_trader_amount_rate = ratio of insider/sneak trading. bundler_rate = ratio of bot-bundled buys at launch. High values (> 0.3) suggest manipulated price action.

Sub-commands

Supported Chains

sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable (kline / trending / trenches / hot-searches; signal: sol / bsc / robinhood / arc / stable; search: --chain is optional — omit to search all chains; accepts all and any chain the search module has enabled, including dynamically-enabled chains such as tron / monad / megaeth / xlayer)

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 standard market routes used by this skill use GMGN's plan-based leaky bucket: Free 5/5, Plus 20/20, Pro 50/50 (rate/capacity). Sustained throughput is roughly tier rate ÷ weight requests/second, and the max burst is roughly floor(tier capacity ÷ weight). The Pro-only 1s K-line route instead uses the Pro API-key bucket plus its separate shared global bucket.

When a request returns 429:

• On RATE_LIMIT_EXCEEDED, tell the user exactly: 已达到当前套餐的限频上限，点击 https://gmgn.ai/ai?chain=bsc&tab=paid_plans 升级套餐，获得更高速率限制. Show this upgrade guidance at most once per user task. Do not repeat it for subsequent RATE_LIMIT_BANNED responses during the same cooldown.

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

• On RATE_LIMIT_BANNED_MAX, the ban has hit the 5-minute ceiling because requests kept arriving during the cooldown. Stop all GMGN calls for this task (not just the failing one) and tell the user the exact reset time; any request before reset_at resets the ban to 5 minutes again.

• On 403 PLAN_UPGRADE_REQUIRED, the endpoint costs more rate-limit weight than the user's plan capacity, so it can never succeed on this plan — do not retry or wait. Tell the user the endpoint is unavailable on their current plan and show the upgrade_message from the response (it contains the upgrade link https://gmgn.ai/ai?chain=bsc&tab=paid_plans).

market kline Parameters

market kline Response Fields

The response is an object with a list array. Each element in list is one candlestick:

Important distinctions (naming is counterintuitive — do not guess):

• volume = token count (e.g. 5379110 means ~5.38M tokens changed hands)
• amount = USD dollar value (e.g. 1214 means ~$1,214 traded) — use this for "how much was traded in USD"
• For tokens not priced at $1, volume and amount will differ by orders of magnitude (e.g. $1,214 amount = 5,379,110 tokens for a $0.0002 token)
• To get total USD volume over a time range, sum amount across all candles in the range
• To get price trend, read close values in chronological order (time ascending)
• To detect volatility, compare high vs low within each candle
• Candles are returned in chronological order (oldest first)

market trending Options

--interval selection guide — always match to the user's stated time window:

market trending Range Filters

Optional --min-* / --max-* flags apply server-side numeric range filtering (inclusive). Unknown metrics are ignored by the service.

Usage Examples

Kline

1s is available only to Pro API keys. Keep the requested range to 500 seconds or less because a 1-second request returns at most 500 candles. Free and Plus keys receive 403 PRO_PLAN_REQUIRED; do not retry with the same key. If the installed CLI rejects 1s, update it before retrying; do not silently fall back to a coarser resolution.

# Last 500 seconds of 1-second candles (Pro only; macOS)
gmgn-cli market kline \
  --chain sol \
  --address <token_address> \
  --resolution 1s \
  --from $(date -v-500S +%s) \
  --to $(date +%s)

# Last 1 hour of 1-minute candles
# macOS:
gmgn-cli market kline \
  --chain sol \
  --address <token_address> \
  --resolution 1m \
  --from $(date -v-1H +%s) \
  --to $(date +%s)
# Linux: use $(date -d '1 hour ago' +%s) instead of $(date -v-1H +%s)

# Last 24 hours of 1-hour candles
# macOS:
gmgn-cli market kline \
  --chain sol \
  --address <token_address> \
  --resolution 1h \
  --from $(date -v-24H +%s) \
  --to $(date +%s)
# Linux: use $(date -d '24 hours ago' +%s) instead of $(date -v-24H +%s)

# Raw output for further processing
gmgn-cli market kline --chain sol --address <addr> \
  --resolution 5m --from <ts> --to <ts> --raw | jq '.[]'

# ETH token kline — last 24h, 1h candles (macOS)
gmgn-cli market kline \
  --chain eth \
  --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --resolution 1h \
  --from $(date -v-24H +%s) \
  --to $(date +%s)

Trending — General

# Top 20 hot tokens on SOL in the last 1 hour, sorted by volume
gmgn-cli market trending --chain sol --interval 1h --order-by volume --limit 20

# Top 50 tokens on SOL, 5m window, sorted by volume
gmgn-cli market trending --chain sol --interval 5m --order-by volume --limit 50

# Hot tokens with social links only, verified and not honeypot, on BSC over 24h
gmgn-cli market trending \
  --chain bsc --interval 24h \
  --filter has_social --filter not_honeypot --filter verified

Trending — SOL by Launchpad Platform

Use --platform to filter trending results to tokens from specific launchpads only.

# SOL 1m hottest — Pump.fun + letsbonk only (most active launchpads), sorted by volume
gmgn-cli market trending \
  --chain sol --interval 1m \
  --platform Pump.fun --platform letsbonk \
  --order-by volume --limit 50 --raw

# SOL 5m hottest — Pump.fun + letsbonk + Moonshot, sorted by volume
gmgn-cli market trending \
  --chain sol --interval 5m \
  --platform Pump.fun --platform letsbonk --platform moonshot_app \
  --order-by volume --limit 50 --raw

# SOL 1h trending — Pump.fun only, with safety filters
gmgn-cli market trending \
  --chain sol --interval 1h \
  --platform Pump.fun \
  --filter renounced --filter frozen --filter not_wash_trading \
  --order-by volume --limit 20 --raw

# SOL 1h trending — all major launchpads combined
gmgn-cli market trending \
  --chain sol --interval 1h \
  --platform Pump.fun --platform letsbonk --platform moonshot_app \
  --platform pump_mayhem --platform pump_mayhem_agent --platform bonkers \
  --order-by volume --limit 50 --raw

Trending — BSC by Launchpad Platform

# BSC 1m hottest — fourmeme (main BSC launchpad), sorted by volume
gmgn-cli market trending \
  --chain bsc --interval 1m \
  --platform fourmeme --platform four_xmode_agent \
  --order-by volume --limit 50 --raw

# BSC 5m hottest — all BSC launchpads, sorted by volume
gmgn-cli market trending \
  --chain bsc --interval 5m \
  --platform fourmeme --platform fourmeme_agent --platform bn_fourmeme --platform four_xmode_agent \
  --platform cubepeg --platform likwid --platform goplus_creator --platform goplus_skills --platform openfour \
  --platform flap --platform flap_stocks --platform flap_aioracle --platform clanker --platform lunafun \
  --order-by volume --limit 50 --raw

# BSC 1h trending — all BSC launchpads with safety filters
gmgn-cli market trending \
  --chain bsc --interval 1h \
  --platform fourmeme --platform fourmeme_agent --platform bn_fourmeme --platform four_xmode_agent \
  --platform cubepeg --platform likwid --platform goplus_creator --platform goplus_skills --platform openfour \
  --platform flap --platform flap_stocks --platform flap_aioracle --platform clanker --platform lunafun \
  --filter not_honeypot --filter verified \
  --order-by volume --limit 20 --raw

Trending — ETH by Launchpad Platform

# ETH 1h trending — all platforms, sorted by volume
gmgn-cli market trending --chain eth --interval 1h --order-by volume --limit 20

# ETH 1h trending — specific platforms only
gmgn-cli market trending \
  --chain eth --interval 1h \
  --platform trench --platform clanker --platform klik \
  --order-by volume --limit 50 --raw

# ETH 1h trending — all ETH platforms with safety filters
gmgn-cli market trending \
  --chain eth --interval 1h \
  --platform trench --platform clanker --platform klik --platform livo --platform stroid \
  --platform pool_uniswap_v2 --platform pool_uniswap_v3 --platform printr \
  --filter not_honeypot --filter verified \
  --order-by volume --limit 20 --raw

# ETH 24h trending — sorted by smart money count
gmgn-cli market trending \
  --chain eth --interval 24h \
  --filter not_honeypot --filter verified \
  --order-by smart_degen_count --limit 20 --raw

Trending — Numeric Range Filters

# SOL 1h trending — liquidity 10k–1M, market cap above 50k, sorted by volume
gmgn-cli market trending \
  --chain sol --interval 1h \
  --min-liquidity 10000 --max-liquidity 1000000 --min-marketcap 50000 \
  --order-by volume --limit 30 --raw

# SOL 5m hottest — fresh tokens (under 30 min old) with smart money interest
gmgn-cli market trending \
  --chain sol --interval 5m \
  --max-created 30m --min-smart-degen-count 1 \
  --order-by volume --limit 50 --raw

# SOL 1h trending — exclude high-insider / high-bundler tokens
gmgn-cli market trending \
  --chain sol --interval 1h \
  --max-insider-rate 0.3 --max-bundler-rate 0.3 \
  --order-by volume --limit 20 --raw

Trending — Base by Launchpad Platform

# Base 1m hottest — clanker + zora (main Base launchpads), sorted by volume
gmgn-cli market trending \
  --chain base --interval 1m \
  --platform clanker --platform zora --platform zora_creator \
  --order-by volume --limit 50 --raw

# Base 5m hottest — clanker + zora + virtuals_v2 + flaunch, sorted by volume
gmgn-cli market trending \
  --chain base --interval 5m \
  --platform clanker --platform zora --platform zora_creator \
  --platform virtuals_v2 --platform flaunch \
  --order-by volume --limit 50 --raw

# Base 1h trending — all major launchpads with safety filters
gmgn-cli market trending \
  --chain base --interval 1h \
  --platform clanker --platform zora --platform zora_creator \
  --platform virtuals_v2 --platform flaunch --platform baseapp \
  --filter not_honeypot --filter verified \
  --order-by volume --limit 20 --raw

market trending Response Fields

The response is data.rank — an array of rank items. Each item represents one token.

Basic Info

Price & Market

Trading Activity

Security & Risk

Dev Status

Smart Money

Social

Dexscreener Marketing

Workflow: Discover Trading Opportunities via Trending

Full workflow for discovering market opportunities: docs/workflow-market-opportunities.md

Steps: fetch trending (50 results, safe filters) → AI multi-factor analysis (smart money, volume, momentum, liquidity, maturity) → present top 5 table with rationale → offer deep dive or swap.

When results contain interesting tokens, proceed to full token due diligence: docs/workflow-token-research.md

For new / launchpad tokens (market trenches): apply the structured early project screening workflow that includes security check and smart money entry detection — docs/workflow-early-project-screening.md

For a daily market overview (user asks "what's the market like today", "give me a daily brief", "what is smart money buying today"): combine market trending + market trenches with gmgn-track smartmoney — docs/workflow-daily-brief.md

Token Quality Filter Criteria

When evaluating tokens returned from market trending or market trenches, apply these criteria to quickly separate high-quality opportunities from noise. Do not present raw results without filtering.

Pass / Watch / Skip Criteria

Quick disqualification rule: If rug_ratio > 0.3 OR is_wash_trading = true OR is_honeypot = 1 → skip immediately, no further analysis needed.

Strong buy signal combination: smart_degen_count ≥ 3 + rug_ratio < 0.2 + creator_close + is_wash_trading = false + liquidity > $50k → high-quality opportunity, proceed to full token research.

For full due diligence on any token surfaced here: docs/workflow-token-research.md

Token Lifecycle Stage

Use field combinations to determine what stage a token is in. This affects how signals should be interpreted.

Stage 1 — Early (New Born)

Indicators:

• creation_timestamp < 1 hour ago
• hot_level low or just starting to rise
• smart_degen_count = 0, renowned_count = 0

Interpretation: Too early for smart money signals. No on-chain track record. High risk, high potential reward. Wait for Stage 2 confirmation before acting. Only the most risk-tolerant traders enter here.

Stage 2 — Breakout

Indicators:

• smart_degen_count ≥ 3 AND rising
• Volume surging (compare swaps_1h vs swaps_24h / 24 — significantly higher)
• price_change_percent1h > 20%
• creator_token_status = creator_hold is OK at this stage (dev hasn't distributed yet)

Interpretation: Strongest entry signal. Smart money is accumulating. Verify security before acting. This window is often short — act on confirmation, not anticipation.

Stage 3 — Distribution

Indicators:

• creator_token_status = creator_close (dev has sold their allocation)
• renowned_count buying (late social signal — KOLs often enter after smart money)
• smart_degen_count plateauing or declining
• Volume still high but momentum slowing

Interpretation: Late stage entry. Smart money may be exiting into retail/KOL demand. Higher risk for new entries. If already holding from Stage 2, evaluate exit levels.

Stage 4 — Decline

Indicators:

• Volume declining across all windows
• holder_count declining
• rat_trader_amount_rate high (insider/sneak trading dominating)
• smart_degen_count = 0 or clearly declining

Interpretation: Avoid new entries entirely. If still holding, consider exiting. The opportunity has likely passed.

market trenches Parameters

Intent → --type mapping (always specify --type explicitly):

--launchpad-platform values by chain (on sol/bsc/base/eth/robinhood, omitting the flag uses the server default allow-list rather than all platforms):

Filter Presets

Presets are applied server-side: the API filters tokens before returning results.

Preset + explicit flag interaction: Explicit filter flags always override preset values. For example, --filter-preset safe --max-rug-ratio 0.1 applies the safe preset but overrides rug_ratio threshold to 0.1.

All filter flags are sent as part of the API request body (server-side) — the server filters tokens before returning results. Use --limit 80 (the default maximum) to maximise the pool.

Response fields: data.new_creation, data.pump, data.completed — each is an array of RankItem (same fields as market trending rank items). Important: data.pump in the response corresponds to --type near_completion in the request. The API always returns this category under the key pump, not near_completion.

Server-Side Filter Fields

All filter flags are sent as part of the API request body — the server filters tokens before returning results. Flags follow the naming convention --min-{field} / --max-{field}.

Trenches Filter Examples

# Apply the safe preset (server-side)
gmgn-cli market trenches --chain sol --type new_creation --filter-preset safe

# Require at least 1 smart money holder (server-side)
gmgn-cli market trenches --chain sol --type new_creation --min-smart-degen-count 1

# Safe preset + require smart money + sort by smart degen count (server-side filter, client-side sort)
gmgn-cli market trenches --chain sol --type new_creation \
  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count

# Strict preset — safe + smart money + min $1k volume (server-side)
gmgn-cli market trenches --chain sol --type new_creation --type near_completion \
  --filter-preset strict --sort-by smart_degen_count

# Manual range filters (all sent server-side)
gmgn-cli market trenches --chain sol --type new_creation \
  --max-rug-ratio 0.3 --max-bundler-rate 0.3 --max-insider-ratio 0.3 \
  --min-smart-degen-count 1 --min-volume-24h 1000

# Filter by token age: only tokens created within the last 30 minutes
gmgn-cli market trenches --chain sol --type new_creation --max-created 30m

# Filter by market cap range
gmgn-cli market trenches --chain sol --type new_creation \
  --min-marketcap 10000