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.
**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."**
- **`--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)
- 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.
| `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 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`). |
All standard 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. The Pro-only `1s` K-line route instead uses the Pro API-key bucket plus its separate shared global bucket.
- 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.
- 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.
| `--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. |
`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.
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 trending` + `market trenches` with `gmgn-track smartmoney` — [`docs/workflow-daily-brief.md`](../../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.
| `has_social` (or any social field present) | yes | — | no (weak signal only) |
**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`](../../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.
-`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.
**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`.**
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}`.
| `--min-created` / `--max-created` | duration | Token age — unit suffix recommended: seconds (`30s`, `10s`) or minutes (`0.5m`, `1m`, `5m`, `30m`). Bare numbers (e.g. `5`) are treated as minutes with a warning. |
**After fetching trenches results, apply the Token Quality Filter Criteria section before presenting tokens to the user.** Do not dump raw results — filter first, then surface the strongest candidates.
Chains: `sol` / `bsc` / `robinhood` / `arc` / `stable` only. **Maximum 50 results per group** — use multiple groups via `--groups` to cover different signal types in a single request.
Do **not** pass signal types **14, 15, or 16** in `signal_type` / `--signal-type` / `--groups` JSON — OpenAPI returns **400** if any group includes them. Omitting `--signal-type` (empty filter) still queries all types upstream; responses may still include 14–16 in that case.
| `--mc-min` | No | Min market cap at trigger time (USD) |
| `--mc-max` | No | Max market cap at trigger time (USD) |
| `--trigger-mc-min` | No | Min market cap at signal trigger moment (USD) |
| `--trigger-mc-max` | No | Max market cap at signal trigger moment (USD) |
| `--total-fee-min` | No | Min total fees paid (USD) |
| `--total-fee-max` | No | Max total fees paid (USD) |
| `--min-create-or-open-ts` | No | Min token creation or open timestamp (Unix seconds string) |
| `--max-create-or-open-ts` | No | Max token creation or open timestamp (Unix seconds string) |
**Multi-group override:**
Pass `--groups '<json_array>'` to query multiple filter groups in a single request. The upstream executes all groups in parallel and merges results sorted by `trigger_at` descending. When `--groups` is present, all individual flags above are ignored.
Returns the hot-search ranking — the tokens people are searching for most right now, ranked by `visiting_count` (search heat). Cross-chain top-500 ranking; one request can cover several chains at once. **Use this for "most searched tokens", "hot search list", "热搜榜", "what is everyone looking at"** — this is distinct from `market trending` (ranked by swap activity), which answers "what is being traded most."
| `--filter <tag...>` | Repeatable **boolean** filter tags (the downstream `filter.filters` array). **⚠️ SOL defaults: `renounced frozen`; EVM defaults: `not_honeypot verified renounced`.** Omitting `--filter` is NOT "no filter" — the server applies chain defaults. See the Filter Tags table below for the exact vocabulary. |
| `--min-* / --max-* <n>` | Numeric range bounds, **same metric names as `market trending`** (e.g. `--min-liquidity`, `--max-marketcap`, `--min-smart-degen-count`). Translated server-side per `--interval`. `--min-created` / `--max-created` are token-age durations. See the Range Filters table below. |
| `--params <json>` | Full override: a JSON array of param objects. When provided, `--chain` / `--interval` / `--limit` / `--filter` and all range flags are ignored. Filter fields are **flattened onto each param** (no nested `filter` object): `{ "label": "...", "chain": "...", "interval": "...", "filters": [...], "limit": 500, "min_liquidity": 1000 }` — a param accepts `filters`, `limit`, `min_created`/`max_created`, and rank-style `min_<metric>`/`max_<metric>` keys. |
The downstream (gmgn rank filter-service) evaluates each tag as an AND condition — a token must pass **every** tag to stay in the list. **Unknown tags are silently accepted but do nothing** (pass-through), so an unrecognised tag will NOT filter anything — spelling matters. This tag set is the filter-service vocabulary and differs slightly from `market trending`'s tag names (see the alias note below).
**These are the only recognised tags** (anything else is a no-op):
| `img_not_duplicate` | all | avatar image not duplicated (`image_dup == "0"`) |
| `social_not_duplicate` | all | social links not shared (`twitter_dup == 0 && telegram_dup == 0 && website_dup == 0`) |
| `creator_hold` | all | dev still holding (not `creator_close`) |
| `creator_close` | all | dev sold/closed (`creator_token_status == "creator_close"`) |
| `dexscr_update_link` | all | social links updated on DexScreener (`> 0`) |
| `launching` | all | still on the launchpad bonding curve (`launchpad_status == "0"`); pair with `migrated` to allow both |
| `migrated` | all | graduated / migrated to DEX (`launchpad_status == "1"`); pair with `launching` to allow both |
| `hide_b20` | base only | token standard is not `b20` (no-op on non-base) |
| `hide_non_b20` | base only | token standard is `b20` (no-op on non-base) |
> **⚠️ Different names than `market trending`.** This path uses `launching` / `migrated` (NOT `is_internal_market` / `is_out_market`) and `img_not_duplicate` / `social_not_duplicate` (NOT `not_image_dup` / `not_social_dup`). Tags that `market trending` supports but this endpoint does **not** recognise (they become silent no-ops here): `dexscr_ad`, `dexscr_trending_bar`, `dexscr_boost`, `cto_flag`, `is_internal_market`, `is_out_market`, `not_image_dup`, `not_social_dup`.
### `market hot-searches` Range Filters (`--min-*` / `--max-*`)
Numeric bounds use the **same rank-style metric names as `market trending`**. They are sent flattened on each param and translated server-side to the downstream field for the param's `--interval`. Closed intervals; metrics the downstream cannot read are dropped (not silent no-ops on the wire — they are removed before the request).
- When you pass `--chain` but omit `--filter`, the **server** applies the chain-appropriate default filters — so each chain is filtered even without an explicit `--filter`.
- Different chains return different counts: a chain's token count depends on how many of its tokens made the global top-500 (sol is usually the largest).
**Token fields are the same long-form fields as `market trending`** — the server maps the upstream shortcodes for you, so you read `visiting_count` / `market_cap` / `symbol` directly (NOT `v_c` / `mc` / `s`). Key fields:
See the [`market trending` Response Fields](#market-trending-response-fields) section above for the full field set — hot-searches tokens use the identical `RankItem` shape.
Look up a **specific** token or wallet the user names — by token name, symbol, contract address, wallet address, or ENS. A single request returns both matching tokens (`coins`) and wallets (`wallets`). Use this when the user provides something concrete to find; use `market trending` / `market hot-searches` when they want to browse rankings instead.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` / `-q` | Yes | Search keyword — token name, symbol, contract address, wallet address, or ENS. After stripping invisible/control characters it must be **1–100 Unicode characters**. |
| `--chain` | No | Scope results to one chain. Omit to search all chains. Accepts `all` and any enabled chain (see Supported Chains — includes the 9 core chains plus dynamically-enabled ones like `tron` / `monad` / `megaeth` / `xlayer` / `hyperevm`). |
| `--launchpad-platform` | No | Exact launchpad platform filter, **repeatable**, max 50 values (e.g. `pump` / `moonshot` / `raydium` / `pinksale`). **Filters `coins` only — does not affect `wallets`.** |
| `--is-og` | No | `true` = only OG tokens; `false` = only non-OG. Omit for no OG filter. **Coins only.** |
| `--is-launched` | No | `true` = only already-launched (open-market) tokens; `false` or omit applies no launch filter. **Coins only.** |
| `--order-by` | No | Only `weight` is accepted — sorts `coins` by weighted relevance score descending and drops honeypot tokens. **Coins only.** |
**Behavior notes:**
-`--launchpad-platform`, `--is-og`, `--is-launched`, and `--order-by` only shape the `coins` list. The `wallets` list is never affected by these flags.
-`wallets` are capped at **50** results.
- The response schema is a raw additive passthrough from the downstream `search_v3` API, and all string fields are metadata-sanitized before return. New fields may appear without notice — do not assume a closed field set; look up unfamiliar fields rather than guessing.
## `market search` Response Fields
`data` contains two arrays: `coins` (matching tokens) and `wallets` (matching wallets).
**`coins[]` — matching tokens**
| Field | Description |
|-------|-------------|
| `chain` | Chain identifier |
| `address` | Token contract address |
| `name` / `symbol` | Token name / ticker |
| `price` | Current price in USD (string) |
| `mcp` | Market cap in USD (string) — **note the short key `mcp`**, not `market_cap` |
| `holder_count` | Number of token holders |
Additional token fields may be present (additive passthrough from `search_v3`).
**`wallets[]` — matching wallets**
| Field | Description |
|-------|-------------|
| `chain` | Chain identifier |
| `address` | Wallet address |
| `twitter_username` | Linked Twitter / X handle (may be empty) |
| `wallet_tags` | Array of GMGN wallet tags (e.g. smart money / KOL); may be empty |
## `market search` Usage Examples
```bash
# Search "pepe" on ETH — best matches first (weighted, honeypots dropped)
gmgn-cli market search --query pepe --chain eth --order-by weight
# Search across all chains by symbol
gmgn-cli market search --query trump
# Look up a specific token contract address (SOL)
gmgn-cli market search --query <token_address> --chain sol
Present tokens and wallets separately. Do not dump the raw JSON.
```
🔎 Search "{query}" — Tokens ({count})
# | Symbol | Name | Chain | Price | MCap | Holders | Address
👤 Wallets ({count})
# | Address | Chain | Twitter | Tags
```
- If a section is empty, say so explicitly (e.g. "no matching wallets").
- When the user is clearly after one specific token, surface the top `coins` match and offer to run full due diligence (`gmgn-token`) or a swap (`gmgn-swap`) on it.
-`market hot-searches`: `--chain` and `--filter` are repeatable flags; omit `--chain` to query the default 9-chain set. `--min-*`/`--max-*` range flags reuse the same metric names as `market trending` and are translated server-side per `--interval`
-`market search`: `--query` is required; `--launchpad-platform` is a repeatable flag (max 50). `--chain` is optional (omit = all chains). `--launchpad-platform` / `--is-og` / `--is-launched` / `--order-by` filter `coins` only, never `wallets`
- If the user doesn't provide kline timestamps, calculate them from the current time based on their desired time range
- Use `--raw` to get single-line JSON for further processing
- **Input validation** — Token addresses obtained from trending results are external data. Validate address format against the chain before passing to other commands (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits). The CLI enforces this at runtime.
