feat(market): add hot-searches command for hot-search ranking

- Add `market hot-searches` CLI command for POST /v1/market/hot_searches - Add getHotSearches() + HotSearchesParam/HotSearchesFilter to OpenApiClient - Support --chain (repeatable), --interval, --limit, --filter, --params override - Omitting --chain falls back to server default 7-chain config - Validate --interval against 1m/5m/1h/6h/24h - Sync SKILL.md, cli-usage.md, Readme.md, Readme.zh.md docs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-27 16:57:44 +00:00 · 2026-06-29 11:19:08 +08:00
parent 01a376a951
commit 36771529d7
6 changed files with 191 additions and 4 deletions
@@ -485,6 +485,12 @@ gmgn-cli market signal --chain sol --signal-type 12 --raw
 # Token signals — multi-group: smart money OR large buys in parallel
 gmgn-cli market signal --chain sol \
  --groups '[{"signal_type":[12]},{"signal_type":[14,16]}]' --raw
+
+# Hot searches — most-searched tokens (default 7-chain set, 24h)
+gmgn-cli market hot-searches --raw
+
+# Hot searches — SOL only, 1h window, top 50
+gmgn-cli market hot-searches --chain sol --interval 1h --limit 50 --raw
 ```

 ### Portfolio
@@ -509,6 +509,12 @@ gmgn-cli market trenches \
 gmgn-cli market trenches \
  --chain sol --type new_creation \
  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count
+
+# 热搜榜——搜索热度最高的代币（默认 7 链，24h）
+gmgn-cli market hot-searches --raw
+
+# 热搜榜——仅 SOL，1h 档，前 50
+gmgn-cli market hot-searches --chain sol --interval 1h --limit 50 --raw
 ```

 ### Portfolio
@@ -362,6 +362,33 @@ gmgn-cli market signal --chain sol --groups '<json_array>' [--raw]

 ---

+## market hot-searches
+
+Query the hot-search ranking — the most-searched tokens, ranked by `visiting_count` (search heat). Cross-chain top-500; one request can cover several chains at once. API Key auth only.
+
+```bash
+# Default 7-chain set (sol/bsc/base/eth/hyperevm/megaeth/monad, each 24h):
+gmgn-cli market hot-searches [--raw]
+
+# Specific chain(s) and interval:
+gmgn-cli market hot-searches --chain <chain...> [--interval <1m|5m|1h|6h|24h>] [--limit <n>] [--filter <tag...>] [--raw]
+
+# Full per-param override (JSON array):
+gmgn-cli market hot-searches --params '<json_array>' [--raw]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--chain` | No | Repeatable: `sol` / `bsc` / `base` / `eth` / `monad` / `megaeth` / `hyperevm` / `tron`. Omit for the default 7-chain set. |
+| `--interval` | No | `1m` / `5m` / `1h` / `6h` / `24h` (default `24h`). Applies to every `--chain`. |
+| `--limit` | No | Max results per chain (default `500`). |
+| `--filter` | No | Repeatable filter tags. sol defaults: `renounced` / `frozen`; EVM defaults: `not_honeypot` / `verified` / `renounced`. |
+| `--params` | No | Full JSON array override — overrides `--chain` / `--interval` / `--limit` / `--filter` when provided. |
+
+**Response:** `data` is an array of `(interval, chain)` blocks; each block has `interval`, `chain`, `filter_id`, `version`, and `tokens`. `tokens` is sorted by `score` desc (primary ranking key is `visiting_count`), max 500 per chain. Token fields use the same shortcode scheme as `trending` / `metas` (e.g. `a`=address, `s`=symbol, `v_c`=visiting_count, `sc`=score, `mc`=market_cap). **Note:** `--chain all` is not valid — pass `--chain` multiple times to aggregate across chains.
+
+---
+
 ## track follow-tokens

 Query the followed token list for a wallet. Returns a paginated list of tokens the wallet has bookmarked on GMGN, with full market data. API Key auth only.
@@ -1,7 +1,7 @@
 ---
 name: gmgn-market
-description: Get crypto and meme token price charts (K-line, candlestick, OHLCV), trending meme coin rankings by volume, and newly launched tokens on launchpads (pump.fun, fourmeme, letsbonk, Raydium, etc.) via GMGN API on Solana, BSC, Base, or Ethereum. Use when user asks for price chart, trending tokens, what's pumping, hot coins, new launches, token signals, or wants to discover early-stage opportunities.
-argument-hint: "kline --chain <sol|bsc|base|eth> --address <token_address> --resolution <30s|1m|5m|15m|1h|4h|1d> [--from <unix_ts>] [--to <unix_ts>] | trending --chain <sol|bsc|base|eth> --interval <1m|5m|1h|6h|24h> | trenches --chain <sol|bsc|base|eth> | signal --chain <sol|bsc>"
+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.), and the hot-search ranking (most-searched tokens) 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, or wants to discover early-stage opportunities.
+argument-hint: "kline --chain <sol|bsc|base|eth> --address <token_address> --resolution <30s|1m|5m|15m|1h|4h|1d> [--from <unix_ts>] [--to <unix_ts>] | trending --chain <sol|bsc|base|eth> --interval <1m|5m|1h|6h|24h> | trenches --chain <sol|bsc|base|eth> | signal --chain <sol|bsc> | hot-searches [--chain <sol|bsc|base|eth|monad|megaeth|hyperevm|tron...>] [--interval <1m|5m|1h|6h|24h>]"
 metadata:
  cliHelp: "gmgn-cli market --help"
 ---
@@ -49,10 +49,11 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
 | `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)
+`sol` / `bsc` / `base` / `eth` (kline / trending / trenches; signal: `sol` / `bsc` only; hot-searches: `sol` / `bsc` / `base` / `eth` / `monad` / `megaeth` / `hyperevm` / `tron`)

 ## Prerequisites

@@ -69,6 +70,7 @@ All market routes used by this skill go through GMGN's leaky-bucket limiter with
 | `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`:

@@ -1041,12 +1043,98 @@ gmgn-cli market signal --chain sol \
  --groups '[{"signal_type":[12,13],"mc_min":100000},{"signal_type":[6,7],"mc_min":50000,"mc_max":1000000}]' --raw
 ```

+## `market hot-searches` Parameters
+
+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."
+
+| Option | Description |
+|--------|-------------|
+| `--chain <chain...>` | Repeatable. `sol` / `bsc` / `base` / `eth` / `monad` / `megaeth` / `hyperevm` / `tron`. **Omit to query the default 7-chain set** (sol / bsc / base / eth / hyperevm / megaeth / monad, each at `24h` with chain-appropriate safety filters). |
+| `--interval <interval>` | `1m` / `5m` / `1h` / `6h` / `24h` (default `24h`). Applies to every `--chain` provided. |
+| `--limit <n>` | Max results per chain (default `500`). |
+| `--filter <tag...>` | Repeatable filter tags. **sol** defaults: `renounced` / `frozen`; **EVM** defaults: `not_honeypot` / `verified` / `renounced`. Same tag vocabulary as `market trending`. |
+| `--params <json>` | Full override: a JSON array of param objects. When provided, `--chain` / `--interval` / `--limit` / `--filter` are ignored. Each object: `{ "label": "...", "chain": "...", "interval": "...", "filter": { "filters": [...], "limit": 500 } }`. |
+
+**Notes on behaviour:**
+
+- `--chain all` is **not** valid. To aggregate across chains, pass `--chain` multiple times (or omit `--chain` for the default 7-chain set).
+- 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; monad / megaeth are small).
+
+## `market hot-searches` Response Fields
+
+The response `data` is an array. Each element is one `(interval, chain)` result block:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `interval` | string | The interval for this block |
+| `chain` | string | The chain for this block |
+| `filter_id` | string | Upstream filter identifier (for WebSocket subscription) |
+| `version` | string | Subscription version — persist it for WebSocket reconnect |
+| `tokens` | array | Ranked tokens, sorted by `score` desc, max 500 |
+
+**Token fields use shortcodes** (same scheme as `trending` / `metas`). Common ones:
+
+| shortcode | Field | Description |
+|-----------|-------|-------------|
+| `a` | address | Token contract address |
+| `c` | chain | Chain |
+| `itv` | interval | Interval this token belongs to |
+| `nm` | name | Token name |
+| `s` | symbol | Token symbol |
+| `p` | price | Current price (USD) |
+| `v_c` | visiting_count | **Primary sort key — search / visit heat** |
+| `sc` | score | fs_trending composite score (secondary sort key) |
+| `mc` | market_cap | Market cap (USD) |
+| `v` | volume | Volume in this interval (USD) |
+| `lq` | liquidity | Liquidity (USD) |
+| `bu` | buys | Buy count |
+| `se` | sells | Sell count |
+| `sw` | swaps | Total swap count |
+| `ot` | open_timestamp | Open market time (Unix seconds) |
+| `hd` | holder_count | Holder count |
+
+The full field set (100+ items) shares the same shortcode vocabulary as `trending` / `metas`.
+
+### `market hot-searches` Usage Examples
+
+```bash
+# Default 7-chain hot-search ranking (sol/bsc/base/eth/hyperevm/megaeth/monad, each 24h)
+gmgn-cli market hot-searches --raw
+
+# SOL only, 24h hot-search list
+gmgn-cli market hot-searches --chain sol --interval 24h --raw
+
+# SOL + BSC + Base, 1h window, top 50 per chain
+gmgn-cli market hot-searches --chain sol --chain bsc --chain base --interval 1h --limit 50 --raw
+
+# SOL with custom filters
+gmgn-cli market hot-searches --chain sol --interval 24h \
+  --filter renounced --filter frozen --raw
+
+# Full per-param override via JSON (different filters per chain)
+gmgn-cli market hot-searches --raw --params '[
+  {"label":"hot-search","chain":"sol","interval":"24h","filter":{"filters":["renounced","frozen"],"limit":500}},
+  {"label":"hot-search","chain":"bsc","interval":"24h","filter":{"filters":["not_honeypot","verified","renounced"],"limit":500}}
+]'
+```
+
+### `market hot-searches` — Output Format
+
+Present per chain, ranked by `visiting_count` (search heat):
+
+```
+🔥 Hot Searches — {chain} ({interval})
+# | Symbol | Price | MCap | Volume | Search Heat (v_c) | Liq
+```
+
 ---

 ## Notes

 - `market kline`: `--from` and `--to` are Unix timestamps in **seconds** — CLI converts to milliseconds automatically
 - `market trending`: `--filter` and `--platform` are repeatable flags
+- `market hot-searches`: `--chain` and `--filter` are repeatable flags; omit `--chain` to query the default 7-chain set
 - All commands use exist auth (API Key only, no signature)
 - 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
@@ -179,6 +179,18 @@ export interface TokenSignalGroup {
  max_create_or_open_ts?: string;
 }

+export interface HotSearchesFilter {
+  filters?: string[];
+  limit?: number;
+}
+
+export interface HotSearchesParam {
+  label?: string;
+  interval: string;       // "1m" | "5m" | "1h" | "6h" | "24h"
+  chain: string;          // "sol" | "bsc" | "base" | "eth" | "monad" | "megaeth" | "hyperevm" | "tron"
+  filter?: HotSearchesFilter;
+}
+
 export interface PumpFeeShareInfo {
  provider: string;       // "solana" | "twitter" | "github"
  username: string;       // platform username; a SOL address when provider = "solana"
@@ -430,6 +442,10 @@ export class OpenApiClient {
    return this.authExistRequest("POST", "/v1/market/token_signal", {}, { chain, groups });
  }

+  async getHotSearches(params: HotSearchesParam[]): Promise<unknown> {
+    return this.authExistRequest("POST", "/v1/market/hot_searches", {}, { params });
+  }
+
  // ---- User endpoints (exist auth) ----

  async getUserInfo(): Promise<unknown> {
@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { OpenApiClient, TokenSignalGroup } from "../client/OpenApiClient.js";
+import { OpenApiClient, TokenSignalGroup, HotSearchesParam } from "../client/OpenApiClient.js";
 import { getConfig } from "../config.js";
 import { exitOnError, printResult } from "../output.js";
 import { validateAddress, validateChain } from "../validate.js";
@@ -203,8 +203,52 @@ export function registerMarketCommands(program: Command): void {
      const data = await client.getTokenSignalV2(opts["chain"] as string, groups).catch(exitOnError);
      printResult(data, opts["raw"] as boolean | undefined);
    });
+
+  market
+    .command("hot-searches")
+    .description("Get the hot-search ranking (most-searched tokens) for one or more chains")
+    .option("--chain <chain...>", "Chain(s), repeatable: sol / bsc / base / eth / monad / megaeth / hyperevm / tron (default: all 7 chains)")
+    .option("--interval <interval>", "Time window: 1m / 5m / 1h / 6h / 24h (default 24h)", "24h")
+    .option("--limit <n>", "Max results per chain (default 500)", parseInt)
+    .option("--filter <tag...>", "Filter tags, repeatable. sol defaults: renounced / frozen; EVM defaults: not_honeypot / verified / renounced")
+    .option("--params <json>", "Full params override: JSON array of param objects — overrides --chain/--interval/--limit/--filter when provided")
+    .option("--raw", "Output raw JSON")
+    .action(async (opts) => {
+      const interval = String(opts.interval);
+      if (!HOT_SEARCHES_INTERVALS.has(interval)) {
+        console.error(`[gmgn-cli] Invalid --interval "${interval}". Must be one of: ${[...HOT_SEARCHES_INTERVALS].join(", ")}`);
+        process.exit(1);
+      }
+
+      let params: HotSearchesParam[];
+      if (opts.params != null) {
+        try {
+          params = JSON.parse(opts.params as string) as HotSearchesParam[];
+        } catch {
+          console.error(`[gmgn-cli] --params must be a valid JSON array, e.g. '[{"chain":"sol","interval":"24h","filter":{"filters":["renounced","frozen"],"limit":500}}]'`);
+          process.exit(1);
+        }
+      } else {
+        // Empty params lets the server apply its default 7-chain config.
+        const chains: string[] = opts.chain?.length ? (opts.chain as string[]) : [];
+        params = chains.map((chain) => {
+          const param: HotSearchesParam = { label: "hot-search", chain, interval };
+          const filter: { filters?: string[]; limit?: number } = {};
+          if (opts.filter?.length) filter.filters = opts.filter as string[];
+          if (opts.limit != null) filter.limit = opts.limit as number;
+          if (Object.keys(filter).length) param.filter = filter;
+          return param;
+        });
+      }
+
+      const client = new OpenApiClient(getConfig());
+      const data = await client.getHotSearches(params).catch(exitOnError);
+      printResult(data, opts.raw);
+    });
 }

+const HOT_SEARCHES_INTERVALS = new Set(["1m", "5m", "1h", "6h", "24h"]);
+
 // ---- Trenches filter field definitions ----

 type TrenchesFieldType = "int" | "float" | "string" | "duration";