gmgn-market — Claude Code skill: what it does, how to install

---
name: gmgn-market
description: Get crypto and meme token price charts (K-line, candlestick, OHLCV), trending meme coin rankings by volume, newly launched tokens on launchpads (pump.fun, fourmeme, letsbonk, Raydium, etc.), the hot-search ranking (most-searched tokens), and search for a specific token or wallet by name, symbol, contract address, wallet address, or ENS via GMGN API on Solana, BSC, Base, or Ethereum. Use when user asks for price chart, trending tokens, what's pumping, hot coins, most searched tokens, new launches, token signals, wants to look up / find / search a specific token or wallet by name or address, or wants to discover early-stage opportunities.
metadata:
  argument-hint: "kline --chain <sol|bsc|base|eth|arbitrum|hyperevm|robinhood|arc|stable> --address <token_address> --resolution <1s|30s|1m|5m|15m|1h|4h|1d> [--from <unix_ts>] [--to <unix_ts>] | trending --chain <sol|bsc|base|eth|arbitrum|hyperevm|robinhood|arc|stable> --interval <1m|5m|1h|6h|24h> | trenches --chain <sol|bsc|base|eth|arbitrum|hyperevm|robinhood|arc|stable> | signal --chain <sol|bsc|robinhood> | hot-searches [--chain <sol|bsc|base|eth|robinhood...>] [--interval <1m|5m|1h|6h|24h>] | search --query <name|symbol|address|ens> [--chain <chain>] [--launchpad-platform <p>...] [--is-og <true|false>] [--is-launched <true|false>] [--order-by weight]"
  cliHelp: "gmgn-cli market --help"
---

**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

| 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 / robinhood / arc / stable 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. |
| `market search` | Look up a **specific** token or wallet by name, symbol, contract address, wallet address, or ENS. Returns both matching tokens (`coins`) and wallets (`wallets`). **Use this when the user names a token/wallet and wants to find it — "search for PEPE", "look up this address", "find vitalik.eth", "查一下这个代币/钱包"** — as opposed to browsing rankings (`trending` / `hot-searches`). |

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

| Command | Route | Weight |
|---------|-------|--------|
| `market kline` (standard resolutions) | `GET /v1/market/token_kline` | 2 |
| `market kline --resolution 1s` (**Pro only**) | `GET /v1/market/token_kline` | 3 against the Pro API-key bucket; shared global limit: 500 req/s |
| `market trending` | `GET /v1/market/rank` | 3 |
| `market trenches` | `POST /v1/trenches` | 2 |
| `market signal` | `POST /v1/market/token_signal` | 1 |
| `market hot-searches` | `POST /v1/market/hot_searches` | 3 |
| `market search` | `GET /v1/market/search` | 1 |

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

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--chain` | Yes | `sol` / `bsc` / `base` / `eth` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable` |
| `--address` | Yes | Token contract address |
| `--resolution` | Yes | Candlestick resolution: `1s` (**Pro only; at most 500 candles per request**) / `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 **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 **base token units** (number of tokens traded) |
| `amount` | string | Trading volume in **USD** (dollar value of all trades in this period) |

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

| 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` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable` |
| `--interval` | Required. `1m` / `5m` / `1h` / `6h` / `24h` (default `1h`) |
| `--limit <n>` | Number of results (default 100, max 100) |
| `--order-by <field>` | 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 <asc\|desc>` | Sort direction (default `desc`) |
| `--filter <tag...>` | 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 <name...>` | 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

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

```bash
# 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

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**

| Field | Description |
|-------|-------------|
| `address` | Token contract address |
| `symbol` / `name` | Token ticker and full name |
| `logo` | Token logo image URL |
| `chain` | Chain identifier |
| `total_supply` | Total token supply |
| `creator` | Creator wallet address |
| `launchpad_platform` | Launch/pool platform (e.g. `Pump.fun`, `letsbonk`, `pool_meteora`, `fourmeme`) |
| `exchange` | Current DEX (e.g. `meteora_damm_v2`, `raydium`, `pump_amm`) |
| `open_timestamp` | Open market listing time (Unix seconds) |
| `creation_timestamp` | Token creation time (Unix seconds) |
| `rank` | Position in this trending list (lower = hotter) |
| `hot_level` | Trending intensity level (higher = hotter) |

**Price & Market**

| Field | Description |
|-------|-------------|
| `price` | Current price in USD |
| `market_cap` | Market cap in USD (directly available — no calculation needed) |
| `liquidity` | Current liquidity in USD |
| `volume` | Trading volume in USD for the queried interval |
| `history_highest_market_cap` | All-time highest market cap in USD |
| `initial_liquidity` | Initial liquidity at token launch |
| `price_change_percent` | Price change % for the queried interval |
| `price_change_percent1m` | Price change % in last 1 minute |
| `price_change_percent5m` | Price change % in last 5 minutes |
| `price_change_percent1h` | Price change % in last 1 hour |

**Trading Activity**

| Field | Description |
|-------|-------------|
| `swaps` | Total swap count in the queried interval |
| `buys` / `sells` | Buy / sell count in the interval |
| `holder_count` | Number of unique token holders |
| `gas_fee` | Average gas fee per transaction |

**Security & Risk**

| Field | Chains | Description |
|-------|--------|-------------|
| `renounced_mint` | SOL | Mint authority renounced (`1` = yes, `0` = no) |
| `renounced_freeze_account` | SOL | Freeze authority renounced (`1` = yes, `0` = no) |
| `is_honeypot` | BSC / Base | Honeypot flag (`1` = yes, `0` = no) |
| `is_open_source` | all | Contract verified (`1` = yes, `0` = no) |
| `is_renounced` | all | Ownership renounced (`1` = yes, `0` = no) |
| `buy_tax` / `sell_tax` | all | Tax rate — empty string means `0` (no tax) |
| `burn_status` | all | Liquidity burn status (e.g. `"none"`, `"burn"`) |
| `top_10_holder_rate` | all | Top 10 wallets concentration (0–1) |
| `rug_ratio` | all | Rug pull risk score (0–1) |
| `is_wash_trading` | all | Wash trading detected (`true` / `false`) |
| `rat_trader_amount_rate` | all | Ratio of insider/sneak trading volume |
| `bundler_rate` | all | Ratio of bundle bot trading volume |
| `entrapment_ratio` | all | Entrapment trading ratio |
| `sniper_count` | all | Number of sniper wallets at launch |
| `bot_degen_count` / `bot_degen_rate` | all | Bot degen wallet count / ratio |
| `dev_team_hold_rate` | all | Dev team holding ratio |
| `top70_sniper_hold_rate` | all | Top 70 sniper current holding ratio |
| `lock_percent` | all | Liquidity lock percentage |

**Dev Status**

| Field | Description |
|-------|-------------|
| `creator_token_status` | Dev holding status: `creator_hold` (still holding) / `creator_close` (sold/closed) |
| `creator_close` | Boolean shorthand for `creator_token_status == creator_close` |
| `dev_token_burn_ratio` | Ratio of dev's tokens that have been burned |

**Smart Money**

| Field | Description |
|-------|-------------|
| `smart_degen_count` | Number of smart money wallets holding the token |
| `renowned_count` | Number of renowned / KOL wallets holding the token |
| `bluechip_owner_percentage` | Ratio of holders that are bluechip wallets (0–1) |

**Social**

| Field | Description |
|-------|-------------|
| `twitter_username` | Twitter / X username (not a full URL — prepend `https://x.com/` to get the link) |
| `website` | Project website URL |
| `telegram` | Telegram URL |
| `cto_flag` | Community takeover flag (`1` = CTO has occurred) |

**Dexscreener Marketing**

| Field | Description |
|-------|-------------|
| `dexscr_ad` | Dexscreener ad placed (`1` = yes) |
| `dexscr_update_link` | Social links updated on Dexscreener (`1` = yes) |
| `dexscr_trending_bar` | Paid for Dexscreener trending bar (`1` = yes) |
| `dexscr_boost_fee` | Dexscreener boost amount paid (0 = none) |

---

## Workflow: Discover Trading Opportunities via Trending

Full workflow for discovering market opportunities: [`docs/workflow-market-opportunities.md`](../../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`](../../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`](../../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...