feat(market): add market signal command for token signal feed

- Add POST /v1/market/token_signal client method and TokenSignalGroup interface
- Add market signal sub-command with individual flags for single-group queries
- Support --groups <json> override for multi-group parallel queries
- Document max 50 results per group limit
- Update SKILL.md, cli-usage.md, and README with signal types, response fields, and examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Readme.md

@@ -471,6 +471,13 @@ 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
+
+# Token signals — smart money buys on SOL (single group)
+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
 ```
 
 ### Portfolio

docs/cli-usage.md

@@ -298,6 +298,57 @@ npx gmgn-cli market trenches --chain <chain> [--type <type...>] [--launchpad-pla
 
 ---
 
+## market signal
+
+Query token signals — price spikes, smart money buys, large buys, Dex ads, CTO events, and more. Returns a list of `TokenSignalItem` sorted by `trigger_at` descending (most recent first). **Maximum 50 results per group.**
+
+```bash
+# Single group (individual flags):
+gmgn-cli market signal --chain sol [--signal-type <n>...] [--mc-min <usd>] [--mc-max <usd>] [--raw]
+
+# Multi-group override (JSON array):
+gmgn-cli market signal --chain sol --groups '<json_array>' [--raw]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` |
+| `--signal-type` | No | Signal type(s), repeatable (1–18, default: all). See Signal Types below. |
+| `--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) |
+| `--groups` | No | Multi-group JSON array — overrides all individual flags when provided |
+
+**Signal Types:**
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 1 | SignalType1 | General signal (K-line price spike) |
+| 2 | SignalTypeDexAd | Dex ad placement |
+| 3 | SignalTypeDexUpdateLink | Dex social link updated |
+| 4 | SignalTypeDexTrendingBar | Dex trending bar |
+| 5 | SignalTypeDexBoost | Dex Boost |
+| 6 | SignalTypePriceUp | Price spike |
+| 7 | SignalTypePriceATH | All-time high price |
+| 8 | SignalTypeMcpKeyLevel | Market cap key level |
+| 9 | SignalTypeLive | Live stream |
+| 10 | SignalTypeBundlerSell | Bundler sell |
+| 11 | SignalTypeCto | Community takeover (CTO) |
+| 12 | SignalTypeSmartDegenBuy | Smart money buy |
+| 13 | SignalTypePlatformCall | Platform call |
+| 14 | SignalTypeLargeAmountBuy | Large amount buy |
+| 15 | SignalTypeMultiBuy | Multiple buys |
+| 16 | SignalTypeMultiLargeBuy | Multiple large buys |
+| 17 | SignalTypeBagsClaims | Bags Claim |
+| 18 | SignalTypePumpClaims | Pump Claim |
+
+---
+
 ## portfolio follow-wallet
 
 Query follow-wallet trade records. Returns trades from wallets you personally follow on the GMGN platform. The follow list is resolved automatically from the GMGN user account bound to the API Key — `--wallet` is optional. Normal auth (API Key only, no private key needed).

skills/gmgn-market/SKILL.md

@@ -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, or Base. Use when user asks for price chart, trending tokens, what's pumping, hot coins, new launches, or wants to discover early-stage opportunities.
+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, or Base. 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> --address <token_address> --resolution <1m|5m|15m|1h|4h|1d> [--from <unix_ts>] [--to <unix_ts>] | trending --chain <sol|bsc|base> --interval <1m|5m|1h|6h|24h> | trenches --chain <sol|bsc|base>"
+argument-hint: "kline --chain <sol|bsc|base> --address <token_address> --resolution <1m|5m|15m|1h|4h|1d> [--from <unix_ts>] [--to <unix_ts>] | trending --chain <sol|bsc|base> --interval <1m|5m|1h|6h|24h> | trenches --chain <sol|bsc|base> | signal --chain <sol|bsc>""
 metadata:
   cliHelp: "gmgn-cli market --help"
 ---
@@ -48,10 +48,11 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
 | `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.** |
 
 ## Supported Chains
 
-`sol` / `bsc` / `base`
+`sol` / `bsc` / `base` (signal: `sol` / `bsc` only)
 
 ## Prerequisites
 
@@ -67,6 +68,7 @@ All market routes used by this skill go through GMGN's leaky-bucket limiter with
 | `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 |
 
 When a request returns `429`:
 
@@ -809,6 +811,112 @@ Present each category separately with a header:
 # | Symbol | Market Cap | Volume (1h) | Smart Degens | Social
 ```
 
+## `market signal` Parameters
+
+Chains: `sol` / `bsc` only. **Maximum 50 results per group** — use multiple groups via `--groups` to cover different signal types in a single request.
+
+**Single-group (individual flags):**
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` |
+| `--signal-type` | No | Signal type(s), repeatable (1–18, default: all). See Signal Types below. |
+| `--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.
+
+```bash
+gmgn-cli market signal --chain sol \
+  --groups '[{"signal_type":[12,14]},{"signal_type":[6,7],"mc_min":50000}]'
+```
+
+### Signal Types
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 1 | SignalType1 | General signal (K-line price spike) |
+| 2 | SignalTypeDexAd | Dex ad placement |
+| 3 | SignalTypeDexUpdateLink | Dex social link updated |
+| 4 | SignalTypeDexTrendingBar | Dex trending bar |
+| 5 | SignalTypeDexBoost | Dex Boost |
+| 6 | SignalTypePriceUp | Price spike |
+| 7 | SignalTypePriceATH | All-time high price |
+| 8 | SignalTypeMcpKeyLevel | Market cap key level |
+| 9 | SignalTypeLive | Live stream |
+| 10 | SignalTypeBundlerSell | Bundler sell |
+| 11 | SignalTypeCto | Community takeover (CTO) |
+| 12 | SignalTypeSmartDegenBuy | Smart money buy |
+| 13 | SignalTypePlatformCall | Platform call |
+| 14 | SignalTypeLargeAmountBuy | Large amount buy |
+| 15 | SignalTypeMultiBuy | Multiple buys |
+| 16 | SignalTypeMultiLargeBuy | Multiple large buys |
+| 17 | SignalTypeBagsClaims | Bags Claim |
+| 18 | SignalTypePumpClaims | Pump Claim |
+
+### `market signal` Response Fields
+
+Each item in the response array is one signal event:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Signal event ID |
+| `token_address` | string | Token contract address |
+| `signal_type` | number | Signal type (1–18, see Signal Types above) |
+| `trigger_at` | number | Unix timestamp (seconds) when the signal was triggered |
+| `trigger_mc` | number | Market cap at signal trigger time (USD) |
+| `first_trigger_mc` | number | Market cap at the very first trigger for this token (USD) |
+| `market_cap` | number | Current market cap (USD) |
+| `ath` | number | All-time high market cap (USD) |
+| `signal_times` | number | Total number of times this signal has triggered for this token |
+| `signal_times_by_type` | object | Signal trigger count broken down by type |
+| `cur_data` | object | Real-time token stats at query time (see below) |
+| `data` | object | Full upstream snapshot at trigger time (chain-specific, raw passthrough) |
+
+**`cur_data` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `top_10_holder_rate` | number | Top 10 holder concentration ratio (0–1) |
+| `holder_count` | number | Current holder count |
+| `liquidity` | number | Current liquidity (USD) |
+
+### Usage Examples
+
+```bash
+# All signals on SOL (default: all types)
+gmgn-cli market signal --chain sol --raw
+
+# Smart money buys only (type 12)
+gmgn-cli market signal --chain sol --signal-type 12 --raw
+
+# Price spikes + ATH (types 6 and 7) with market cap filter
+gmgn-cli market signal --chain sol \
+  --signal-type 6 --signal-type 7 \
+  --mc-min 50000 --mc-max 5000000 --raw
+
+# Smart money buys on BSC
+gmgn-cli market signal --chain bsc --signal-type 12 --raw
+
+# Multi-group: smart money buys OR large amount buys, in parallel
+gmgn-cli market signal --chain sol \
+  --groups '[{"signal_type":[12]},{"signal_type":[14,16]}]' --raw
+
+# Multi-group: combine signal type filter with market cap range per group
+gmgn-cli market signal --chain sol \
+  --groups '[{"signal_type":[12,14],"mc_min":100000},{"signal_type":[6,7],"mc_min":50000,"mc_max":1000000}]' --raw
+```
+
+---
+
 ## Notes
 
 - `market kline`: `--from` and `--to` are Unix timestamps in **seconds** — CLI converts to milliseconds automatically

src/client/OpenApiClient.ts

@@ -156,6 +156,18 @@ export interface StrategyCancelParams {
   close_sell_model?: string;
 }
 
+export interface TokenSignalGroup {
+  signal_type?: number[];
+  mc_min?: number;
+  mc_max?: number;
+  trigger_mc_min?: number;
+  trigger_mc_max?: number;
+  total_fee_min?: number;
+  total_fee_max?: number;
+  min_create_or_open_ts?: string;
+  max_create_or_open_ts?: string;
+}
+
 export interface CreateTokenParams {
   chain: string;
   dex: string;
@@ -284,6 +296,10 @@ export class OpenApiClient {
     return this.normalRequest("GET", "/v1/market/rank", { chain, interval, ...extra });
   }
 
+  async getTokenSignalV2(chain: string, groups: TokenSignalGroup[]): Promise<unknown> {
+    return this.normalRequest("POST", "/v1/market/token_signal", {}, { chain, groups });
+  }
+
   // ---- User endpoints (normal auth) ----
 
   async getUserInfo(): Promise<unknown> {

src/commands/market.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { OpenApiClient } from "../client/OpenApiClient.js";
+import { OpenApiClient, TokenSignalGroup } from "../client/OpenApiClient.js";
 import { getConfig } from "../config.js";
 import { exitOnError, printResult } from "../output.js";
 import { validateAddress, validateChain } from "../validate.js";
@@ -115,6 +115,56 @@ export function registerMarketCommands(program: Command): void {
       : data;
     printResult(result, opts.raw);
   });
+
+  market
+    .command("signal")
+    .description("Query token signals (price spikes, smart money buys, large buys, etc.) — max 50 results per group")
+    .requiredOption("--chain <chain>", "Chain: sol / bsc")
+    .option("--signal-type <n...>", "Signal type(s), repeatable: 1–18 (default: all types)", (v: string, acc: number[]) => { acc.push(parseInt(v, 10)); return acc; }, [] as number[])
+    .option("--mc-min <usd>", "Min market cap at trigger time (USD)", parseFloat)
+    .option("--mc-max <usd>", "Max market cap at trigger time (USD)", parseFloat)
+    .option("--trigger-mc-min <usd>", "Min market cap at signal trigger (USD)", parseFloat)
+    .option("--trigger-mc-max <usd>", "Max market cap at signal trigger (USD)", parseFloat)
+    .option("--total-fee-min <usd>", "Min total fees paid (USD)", parseFloat)
+    .option("--total-fee-max <usd>", "Max total fees paid (USD)", parseFloat)
+    .option("--min-create-or-open-ts <ts>", "Min token creation or open timestamp (Unix seconds string)")
+    .option("--max-create-or-open-ts <ts>", "Max token creation or open timestamp (Unix seconds string)")
+    .option("--groups <json>", "Multi-group override: JSON array of group objects — overrides all individual flags when provided")
+    .option("--raw", "Output raw JSON")
+    .action(async (opts: Record<string, unknown>) => {
+      validateChain(opts["chain"] as string);
+      if (!["sol", "bsc"].includes(opts["chain"] as string)) {
+        console.error(`[gmgn-cli] market signal only supports sol and bsc, got "${opts["chain"]}"`);
+        process.exit(1);
+      }
+
+      let groups: TokenSignalGroup[];
+      if (opts["groups"] != null) {
+        try {
+          groups = JSON.parse(opts["groups"] as string) as TokenSignalGroup[];
+        } catch {
+          console.error(`[gmgn-cli] --groups must be a valid JSON array, e.g. '[{"signal_type":[12,14]},{"signal_type":[6,7],"mc_min":50000}]'`);
+          process.exit(1);
+        }
+      } else {
+        const group: TokenSignalGroup = {};
+        const signalType = opts["signalType"] as number[] | undefined;
+        if (signalType?.length) group.signal_type = signalType;
+        if (opts["mcMin"] != null) group.mc_min = opts["mcMin"] as number;
+        if (opts["mcMax"] != null) group.mc_max = opts["mcMax"] as number;
+        if (opts["triggerMcMin"] != null) group.trigger_mc_min = opts["triggerMcMin"] as number;
+        if (opts["triggerMcMax"] != null) group.trigger_mc_max = opts["triggerMcMax"] as number;
+        if (opts["totalFeeMin"] != null) group.total_fee_min = opts["totalFeeMin"] as number;
+        if (opts["totalFeeMax"] != null) group.total_fee_max = opts["totalFeeMax"] as number;
+        if (opts["minCreateOrOpenTs"] != null) group.min_create_or_open_ts = opts["minCreateOrOpenTs"] as string;
+        if (opts["maxCreateOrOpenTs"] != null) group.max_create_or_open_ts = opts["maxCreateOrOpenTs"] as string;
+        groups = [group];
+      }
+
+      const client = new OpenApiClient(getConfig());
+      const data = await client.getTokenSignalV2(opts["chain"] as string, groups).catch(exitOnError);
+      printResult(data, opts["raw"] as boolean | undefined);
+    });
 }
 
 // ---- Trenches filter field definitions ----