Gmgn Market

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

| Sub-command | Description | |-------------|-------------| | market kline | Token candlestick / OHLCV data and trading volume over a time range | | market trending | Trending tokens ranked by swap activity — use --interval to specify the time window (e.g. 1m for 1-minute hottest, 1h for 1-hour trending) | | market trenches | Newly launched launchpad platform tokens — use this when the user asks for "new tokens", "just launched tokens", "latest tokens on pump.fun/letsbonk". Three categories: new_creation (just created), near_completion (bonding curve almost full), completed (graduated to open market / DEX) | | market signal | Real-time token signal feed — price spikes, smart money buys, large buys, Dex ads, CTO events, and more. Results sorted by trigger_at descending. sol / bsc only. Max 50 results per group. | | market hot-searches | Hot-search ranking — the most-searched tokens, ranked by visiting_count (search heat). Use this when the user asks "what tokens are people searching for", "most searched tokens", "hot search list", "热搜榜". Supports multiple chains in a single request. |

Supported Chains

sol / bsc / base / eth (kline / trending / trenches; signal: sol / bsc only; hot-searches: sol / bsc / base / eth / monad / megaeth / hyperevm / tron)

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 market 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 | |---------|-------|--------| | market kline | GET /v1/market/token_kline | 2 | | market trending | GET /v1/market/rank | 1 | | market trenches | POST /v1/trenches | 3 | | market signal | POST /v1/market/token_signal | 3 | | market hot-searches | POST /v1/market/hot_searches | 3 |

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

1. Wait for the user's API key, then save it with gmgn-cli config (creates ~/.config/gmgn/.env and sets chmod 600 automatically — do not hand-edit the file):

``bash gmgn-cli config set-key ``

market kline Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --chain | Yes | sol / bsc / base / eth | | --address | Yes | Token contract address | | --resolution | Yes | Candlestick resolution: 30s / 1m / 5m / 15m / 1h / 4h / 1d | | --from | No | Start time (Unix seconds) | | --to | No | End time (Unix seconds) |

market kline Response Fields

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

| Field | Type | Description | |-------|------|-------------| | time | number | Candle open time — Unix timestamp in milliseconds (divide by 1000 for seconds) | | open | string | Opening price in USD at the start of the period | | close | string | Closing price in USD at the end of the period | | high | string | Highest price in USD during the period | | low | string | Lowest price in USD during the period | | volume | string | Trading volume in USD (dollar value of all trades in this period) | | amount | string | Trading volume in base token units (number of tokens traded) |

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

• volume = USD dollar value (e.g. 1214 means ~$1,214 traded) — use this for "how much was traded in USD"
• amount = token count (e.g. 5379110 means ~5.38M tokens changed hands) — use this for "how many tokens were traded"
• For tokens not priced at $1, volume and amount will differ by orders of magnitude (e.g. a $0.0002 token: $1,214 volume = 5,379,110 tokens)
• To get total USD volume over a time range, sum volume 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:

| User says | --interval | |-----------|-------------| | "1m trending" / "hottest right now" | 1m | | "5m" / "5 minute" | 5m | | "1h" / "1 hour" / no time specified (default) | 1h | | "6h" / "6 hour" | 6h | | "24h" / "today" / "daily" | 24h |

| Option | Description | |--------|-------------| | --chain | Required. sol / bsc / base / eth | | --interval | Required. 1m / 5m / 1h / 6h / 24h (default 1h) | | --limit | Number of results (default 100, max 100) | | --order-by | Sort field: default / swaps / marketcap / history_highest_market_cap / liquidity / volume / holder_count / smart_degen_count / renowned_count / gas_fee / price / change1m / change5m / change1h / creation_timestamp | | --direction | Sort direction (default desc) | | --filter | Repeatable filter tags (chain-specific). ⚠️ SOL defaults: renounced frozen; BSC/Base/ETH defaults: not_honeypot verified renounced. Omitting --filter is NOT "no filter" — chain defaults always apply. sol tags: renounced / frozen / burn / token_burnt / has_social / not_social_dup / not_image_dup / dexscr_update_link / not_wash_trading / is_internal_market / is_out_market. evm tags: not_honeypot / verified / renounced / locked / token_burnt / has_social / not_social_dup / not_image_dup / dexscr_update_link / is_internal_market / is_out_market | | --platform | Repeatable platform filter (chain-specific). sol: Pump.fun / pump_mayhem / pump_mayhem_agent / pump_agent / letsbonk / bonkers / bags / memoo / liquid / bankr / zora / surge / anoncoin / moonshot_app / wendotdev / heaven / sugar / token_mill / believe / trendsfun / trends_fun / jup_studio / Moonshot / boop / xstocks / ray_launchpad / meteora_virtual_curve / pool_ray / pool_meteora / pool_pump_amm / pool_orca. bsc: fourmeme / fourmeme_agent / bn_fourmeme / four_xmode_agent / cubepeg / likwid / goplus_creator / goplus_skills / openfour / flap / flap_stocks / flap_aioracle / clanker / lunafun / pool_uniswap / pool_pancake. base: clanker / bankr / flaunch / zora / zora_creator / baseapp / basememe / virtuals_v2 / klik. eth: trench / clanker / klik / livo / stroid / pool_uniswap_v2 / pool_uniswap_v3 / printr |

market trending Range Filters

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

| Option | Description | |--------|-------------| | --min-volume / --max-volume | Trading volume (USD) | | --min-liquidity / --max-liquidity | Liquidity (USD) | | --min-marketcap / --max-marketcap | Market cap (USD) | | --min-history-highest-marketcap / --max-history-highest-marketcap | Historical highest market cap (USD) | | --min-swaps / --max-swaps | Swap count | | --min-holder-count / --max-holder-count | Holder count | | --min-gas-fee / --max-gas-fee | Gas fee | | --min-renowned-count / --max-renowned-count | KOL / renowned wallet count | | --min-smart-degen-count / --max-smart-degen-count | Smart-money holder count | | --min-bot-degen-count / --max-bot-degen-count | Bot-degen wallet count | | --min-visiting-count / --max-visiting-count | Visitor count | | --min-price-change-percent / --max-price-change-percent | Price change ratio over the interval | | --min-insider-rate / --max-insider-rate | Insider trading ratio (0–1); tokens lacking this field are excluded | | --min-bundler-rate / --max-bundler-rate | Bundle-bot trading ratio (0–1); tokens lacking this field are excluded | | --min-entrapment-ratio / --max-entrapment-ratio | Entrapment trading ratio (0–1); tokens lacking this field are excluded | | --min-top10-holder-rate / --max-top10-holder-rate | Top-10 holder concentration (0–1) | | --min-top70-sniper-hold-rate / --max-top70-sniper-hold-rate | Top-70 sniper holding ratio (0–1) | | --min-dev-team-hold-rate / --max-dev-team-hold-rate | Dev-team holding ratio (0–1); --min-dev-team-hold-rate also excludes creator-close tokens | | --min-created / --max-created | Token age window, duration string with a m (minutes) / h (hours) / d (days) suffix, e.g. 30m / 6h / 7d. --min-created is a minimum age (excludes younger tokens); --max-created a maximum age (excludes older tokens). Note: the raw upstream rank interface accepts minutes only; the openapi-service does not forward this field — it evaluates the age window itself (cutoff = now − duration, computed natively for m/h/d), so 6h / 7d work here. Always include a unit suffix — a bare number is not accepted. |

Usage Examples

Kline

# Last 1 hour of 1-minute candles
# macOS:
gmgn-cli market kline \
  --chain sol \
  --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  \
  --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  \
  --resolution 5m --from  --to  --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

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GMGNAI](https://github.com/GMGNAI)
- **Source:** [GMGNAI/gmgn-skills](https://github.com/GMGNAI/gmgn-skills)
- **License:** MIT
- **Homepage:** https://gmgn.ai/ai

Install and usage instructions live in the source repository linked above.