feat(track): add follow-token-groups subcommand

Adds `track follow-token-groups` command that calls
GET /v1/user/follow_token_groups to retrieve a wallet's token follow
group names (id, name, rank) for a given chain.

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

docs/cli-usage.md

@@ -379,6 +379,24 @@ gmgn-cli track follow-tokens \
 
 ---
 
+## track follow-token-groups
+
+Query the follow token group names for a wallet. Returns the groups a wallet uses to organise its followed tokens on GMGN. API Key auth only.
+
+```bash
+gmgn-cli track follow-token-groups \
+  --chain <chain> \
+  --wallet <wallet_address> \
+  [--raw]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` / `base` / `eth` |
+| `--wallet` | Yes | Wallet address |
+
+---
+
 ## 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. Signed auth (API Key + private key signature).

skills/gmgn-track/SKILL.md

@@ -49,7 +49,8 @@ Use the `gmgn-cli` tool to query on-chain tracking data based on the user's requ
 
 | Sub-command | Description |
 |-------------|-------------|
-| `track follow-tokens` | Followed token map for a wallet — which tokens a wallet has bookmarked on GMGN |
+| `track follow-tokens` | Followed token list for a wallet — which tokens a wallet has bookmarked on GMGN, with full market data |
+| `track follow-token-groups` | Follow token group names for a wallet — the group names and IDs the wallet uses to organise followed tokens |
 | `track follow-wallet` | Trade records from wallets the user personally follows on GMGN |
 | `track kol` | Real-time trades from KOL / influencer wallets tagged by GMGN |
 | `track smartmoney` | Real-time trades from smart money / whale wallets tagged by GMGN |
@@ -71,6 +72,7 @@ All tracking routes used by this skill go through GMGN's leaky-bucket limiter wi
 | Command | Route | Weight |
 |---------|-------|--------|
 | `track follow-tokens` | `GET /v1/user/follow_tokens` | 3 |
+| `track follow-token-groups` | `GET /v1/user/follow_token_groups` | 1 |
 | `track follow-wallet` | `GET /v1/trade/follow_wallet` | 3 |
 | `track kol` | `GET /v1/user/kol` | 1 |
 | `track smartmoney` | `GET /v1/user/smartmoney` | 1 |
@@ -103,12 +105,18 @@ When a request returns `429`:
 ## Usage Examples
 
 ```bash
-# Followed token map for a wallet on SOL
+# Followed token list for a wallet on SOL
 gmgn-cli track follow-tokens --chain sol --wallet <wallet_address>
 
-# Followed token map on BSC, raw JSON output
+# Followed token list on BSC, raw JSON output
 gmgn-cli track follow-tokens --chain bsc --wallet <wallet_address> --raw
 
+# Follow token group names for a wallet on SOL
+gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address>
+
+# Follow token group names, raw JSON output
+gmgn-cli track follow-token-groups --chain sol --wallet <wallet_address> --raw
+
 # Follow-wallet trades (all wallets you follow)
 gmgn-cli track follow-wallet --chain sol
 
@@ -176,6 +184,24 @@ Each item in `followings` contains:
 | `group_ids` | Follow groups this token belongs to |
 | `open_timestamp` | Unix timestamp when trading opened |
 
+## `track follow-token-groups` Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required. `sol` / `bsc` / `base` / `eth` |
+| `--wallet <address>` | Required. Wallet address to query |
+
+## `track follow-token-groups` Response Fields
+
+`data` is an array. Each item contains:
+
+| Field | Description |
+|-------|-------------|
+| `chain` | Chain the group is on |
+| `group_id` | Group identifier (e.g. `default`, or a user-defined ID) |
+| `group_name` | Human-readable group name |
+| `rank` | Display order / sort rank |
+
 ## `track follow-wallet` Options
 
 | Option | Description |

src/client/OpenApiClient.ts

@@ -440,6 +440,10 @@ export class OpenApiClient {
     return this.authExistRequest("GET", "/v1/user/follow_tokens", { chain, wallet_address: walletAddress, ...extra });
   }
 
+  async getFollowGroupNames(chain: string, walletAddress: string): Promise<unknown> {
+    return this.authExistRequest("GET", "/v1/user/follow_token_groups", { chain, wallet_address: walletAddress });
+  }
+
   async getKol(chain?: string, limit?: number): Promise<unknown> {
     const query: Record<string, string | number> = {};
     if (chain) query["chain"] = chain;

src/commands/track.ts

@@ -35,6 +35,19 @@ export function registerTrackCommands(program: Command): void {
       printResult(data, opts.raw);
     });
 
+  track
+    .command("follow-token-groups")
+    .description("Get the follow token group names for a wallet on a given chain")
+    .requiredOption("--chain <chain>", "Chain: sol / bsc / base / eth")
+    .requiredOption("--wallet <address>", "Wallet address")
+    .option("--raw", "Output raw JSON")
+    .action(async (opts) => {
+      validateChain(opts.chain);
+      const client = new OpenApiClient(getConfig());
+      const data = await client.getFollowGroupNames(opts.chain, opts.wallet).catch(exitOnError);
+      printResult(data, opts.raw);
+    });
+
   track
     .command("follow-wallet")
     .description("Get follow-wallet trade records")