feat: add track command group, split follow-wallet/kol/smartmoney from portfolio

- Add new `track` command group with three sub-commands: - `track follow-wallet`: monitor trade activity of followed wallets (critical auth) - `track kol`: KOL trade records with optional --chain and client-side --side filter - `track smartmoney`: Smart Money trade records with optional --chain and client-side --side filter - Remove follow-wallet, kol, smartmoney sub-commands from portfolio - Add getKol/getSmartMoney optional chain param in OpenApiClient - Switch getFollowWallet to criticalRequest (signature auth required) - Align track follow-wallet options to actual API params (remove unsupported flags) - Add skills/gmgn-track/SKILL.md with sub-command guide, options, response fields - Add IMPORTANT notice to all SKILL.md files to prevent AI from scraping gmgn.ai - Add CRITICAL RULE section to CLAUDE.md to enforce CLI-only data access - Update Readme.md and Readme.zh.md: add gmgn-track skill, Track CLI section, user tip Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-08-15 09:08:05 +00:00 · 2026-03-27 14:19:57 +08:00
parent 58849a8c61
commit 28062887d8
12 changed files with 265 additions and 119 deletions
@@ -2,6 +2,22 @@

 This file provides guidance to Claude Code when working with the gmgn-cli plugin.

+## CRITICAL RULE — Read This First
+
+**ALL queries about GMGN data MUST use `gmgn-cli` via the skills below.**
+
+This includes: trending tokens, token info, security checks, K-line / price history, wallet holdings, KOL trades, Smart Money trades, swaps, and any other on-chain data.
+
+**NEVER do any of the following to fetch GMGN data:**
+- Web search (e.g. searching "gmgn trending solana")
+- WebFetch / curl to gmgn.ai or any gmgn domain
+- Browser automation or scraping
+- Any method other than `gmgn-cli`
+
+**Why:** The gmgn.ai website requires login, uses dynamic rendering, and does not expose structured data. The CLI is the only correct and supported method. If you attempt to scrape the site, you will get no data or be blocked.
+
+**When a user asks anything about GMGN data — always invoke the matching skill and run the CLI command. No exceptions.**
+
 ## Project Overview

 This is a **Claude Code plugin** — a collection of GMGN OpenAPI skills for on-chain operations. It provides CLI tools and skills for token queries, market data, wallet portfolio analysis, and swap execution across sol / bsc / base.
@@ -13,12 +29,13 @@ This is a **Claude Code plugin** — a collection of GMGN OpenAPI skills for on-
 | `gmgn-token` | Token info, security, pool, holders, traders | User asks about a token's price, market cap, security risk, liquidity pool, top holders, or top traders; user wants to research a token before buying; user asks "is this token safe", "who holds this token", "what's the liquidity" |
 | `gmgn-market` | K-line / candlestick market data + trending tokens + newly launched launchpad tokens | User asks for price history, chart data, OHLCV candles, trading volume over time; user wants to analyze price trends; user asks "show me the 1h chart", "what was the price last week", "give me kline data for this token"; user wants to discover hot or trending tokens; user asks "what tokens are trending", "show me top tokens by volume", "find hot tokens on SOL"; **user asks about newly launched tokens, fresh tokens, latest tokens on launchpads** — e.g. "show me new tokens on pump.fun", "what tokens just launched on SOL", "find newly created tokens", "latest tokens on letsbonk" → use `market trenches --type new_creation` |
 | `gmgn-portfolio` | Wallet holdings, activity, trading stats, token balance | User asks about a wallet's holdings, P&L, transaction history, trading statistics, or token balance; user wants to analyze a wallet; user asks "what tokens does this wallet hold", "show me recent trades", "what's the win rate of this wallet" |
+| `gmgn-track` | Track trade activity of wallets I follow, KOL trades, Smart Money trades across chains | User asks about trades from wallets they follow; user wants to see what KOLs or Smart Money are buying/selling; user asks "show me what wallets I follow have traded recently", "what are KOLs buying", "show me smart money moves on BSC" |
 | `gmgn-swap` | Token swap execution + order status query | User wants to swap tokens, execute a trade, or check an order status; user asks "swap SOL for USDC", "buy this token", "check my order"; **requires private key configured in `.env`** |

 ## Architecture

 - **`src/`** — TypeScript source (CLI commands, API client, signer)
- **`skills/`** — 4 SKILL.md files for Claude Code skill definitions
+- **`skills/`** — 5 SKILL.md files for Claude Code skill definitions
 - **`dist/`** — Compiled output (generated by `npm run build`)
 - **`.claude-plugin/`** — Plugin metadata for Claude Code

@@ -21,6 +21,7 @@ With GMGN Agent Skills, you can use AI agents to query real-time trending token
 | [`/gmgn-token`](skills/gmgn-token/SKILL.md) | Token info, security, pool, holders, traders | [SKILL.md](skills/gmgn-token/SKILL.md) |
 | [`/gmgn-market`](skills/gmgn-market/SKILL.md) | K-line market data, trending tokens | [SKILL.md](skills/gmgn-market/SKILL.md) |
 | [`/gmgn-portfolio`](skills/gmgn-portfolio/SKILL.md) | Wallet holdings, activity, stats | [SKILL.md](skills/gmgn-portfolio/SKILL.md) |
+| [`/gmgn-track`](skills/gmgn-track/SKILL.md) | Follow-wallet trades, KOL trades, Smart Money trades | [SKILL.md](skills/gmgn-track/SKILL.md) |
 | [`/gmgn-swap`](skills/gmgn-swap/SKILL.md) | Swap submission + order query | [SKILL.md](skills/gmgn-swap/SKILL.md) |

 > For detailed CLI commands, parameters, and recommended values, see the [Wiki documentation](https://github.com/GMGNAI/gmgn-skills/wiki).
@@ -29,6 +30,11 @@ With GMGN Agent Skills, you can use AI agents to query real-time trending token

 Ready to install skills? [Jump to Installation →](#get-started)

+> **Tip:** If your AI agent tries to open or scrape the gmgn.ai website instead of using the CLI, add this to your prompt:
+> ```
+> Use gmgn-cli commands. Do not call gmgn.ai web endpoints directly.
+> ```
+
 ---

 ## Demo Cases
@@ -194,7 +200,7 @@ Skills are automatically discovered via the `.cursor-plugin/` configuration.
   ```bash
   echo "$(npm root -g)/gmgn-skills/skills"
   ```
-3. Restart Cline — `/gmgn-token`, `/gmgn-market`, `/gmgn-portfolio`, `/gmgn-swap` will be available
+3. Restart Cline — `/gmgn-token`, `/gmgn-market`, `/gmgn-portfolio`, `/gmgn-track`, `/gmgn-swap` will be available

 #### Codex CLI

@@ -291,6 +297,22 @@ npx gmgn-cli market trenches \
 npx gmgn-cli portfolio holdings --chain sol --wallet <addr>
 ```

+### Track
+
+```bash
+# Follow-wallet trade records (requires GMGN_PRIVATE_KEY)
+npx gmgn-cli track follow-wallet --chain sol
+npx gmgn-cli track follow-wallet --chain sol --wallet <wallet_address> --side buy
+
+# KOL trade records
+npx gmgn-cli track kol --limit 100 --raw
+npx gmgn-cli track kol --chain sol --side buy --limit 50 --raw
+
+# Smart Money trade records
+npx gmgn-cli track smartmoney --limit 100 --raw
+npx gmgn-cli track smartmoney --chain sol --side sell --limit 50 --raw
+```
+
 ### Swap (requires private key)

 ```bash
@@ -320,7 +342,7 @@ npx gmgn-cli order get --chain sol --order-id <order-id>

 | Commands | Chains | Chain Currencies |
 |----------|--------|-----------------|
-| token / market / portfolio | `sol` / `bsc` / `base` | — |
+| token / market / portfolio / track | `sol` / `bsc` / `base` | — |
 | swap / order | `sol` / `bsc` / `base` | sol: SOL, USDC · bsc: BNB, USDC · base: ETH, USDC |

 ---
@@ -21,6 +21,7 @@
 | [`/gmgn-token`](skills/gmgn-token/SKILL.md) | Token 信息、安全、池子、持有者、交易者 | [SKILL.md](skills/gmgn-token/SKILL.md) |
 | [`/gmgn-market`](skills/gmgn-market/SKILL.md) | K 线行情数据、热门代币 | [SKILL.md](skills/gmgn-market/SKILL.md) |
 | [`/gmgn-portfolio`](skills/gmgn-portfolio/SKILL.md) | 钱包持仓、活动、统计 | [SKILL.md](skills/gmgn-portfolio/SKILL.md) |
+| [`/gmgn-track`](skills/gmgn-track/SKILL.md) | 追踪关注钱包交易动态、KOL 交易动态、聪明钱交易动态 | [SKILL.md](skills/gmgn-track/SKILL.md) |
 | [`/gmgn-swap`](skills/gmgn-swap/SKILL.md) | 兑换提交 + 订单查询 | [SKILL.md](skills/gmgn-swap/SKILL.md) |

 > 如需查看详细的 CLI 接口说明、传参格式和推荐值，请参阅 [Wiki 文档](https://github.com/GMGNAI/gmgn-skills/wiki/Home-Chinese)。
@@ -29,6 +30,11 @@

 已准备好？[点击这里开始安装 Skills →](#开始安装-skills)

+> **提示：** 如果你的 AI Agent 尝试直接打开 gmgn.ai 网站而不是使用 CLI，请在提示词中加上：
+> ```
+> 用 gmgn-cli 命令，不要直接请求gmgn.ai网页接口。
+> ```
+
 ---

 ## 使用案例
@@ -67,7 +73,7 @@

 ## 1. 安装

-选择以下任意一种方式：
+选择以下任意一种方式

 ### 1.1 通过 Agent 安装（推荐）

@@ -194,7 +200,7 @@ cp .env.example .env
   ```bash
   echo "$(npm root -g)/gmgn-skills/skills"
   ```
-3. 重启 Cline — `/gmgn-token`、`/gmgn-market`、`/gmgn-portfolio`、`/gmgn-swap` 即可使用
+3. 重启 Cline — `/gmgn-token`、`/gmgn-market`、`/gmgn-portfolio`、`/gmgn-track`、`/gmgn-swap` 即可使用

 #### Codex CLI

@@ -337,19 +343,26 @@ npx gmgn-cli portfolio activity --chain sol --wallet <addr>
 npx gmgn-cli portfolio stats --chain sol --wallet <addr1> --wallet <addr2>

 # API Key 绑定的钱包及主币余额
-npx gmgn-cli portfolio info --chain sol
+npx gmgn-cli portfolio info

 # 单个 token 余额
 npx gmgn-cli portfolio token-balance --chain sol --wallet <addr> --token <token_addr>
+```

-# 跟单交易记录
-npx gmgn-cli portfolio follow-wallet --chain sol
+### Track

-# KOL 交易记录（仅 SOL）
-npx gmgn-cli portfolio kol
+```bash
+# 追踪关注钱包的交易动态（需要 GMGN_PRIVATE_KEY）
+npx gmgn-cli track follow-wallet --chain sol
+npx gmgn-cli track follow-wallet --chain sol --wallet <wallet_address> --side buy

-# 聪明钱交易记录（仅 SOL）
-npx gmgn-cli portfolio smartmoney
+# KOL 交易动态
+npx gmgn-cli track kol --limit 100 --raw
+npx gmgn-cli track kol --chain sol --side buy --limit 50 --raw
+
+# 聪明钱交易动态
+npx gmgn-cli track smartmoney --limit 100 --raw
+npx gmgn-cli track smartmoney --chain sol --side sell --limit 50 --raw
 ```

 ### Swap（需要私钥）
@@ -399,7 +412,7 @@ npx gmgn-cli order get --chain sol --order-id <order-id>

 | 接口类型 | 支持的链 | 链原生货币 |
 |----------|----------|-----------|
-| token / market / portfolio | `sol` / `bsc` / `base` | — |
+| token / market / portfolio / track | `sol` / `bsc` / `base` | — |
 | swap / order | `sol` / `bsc` / `base` | sol: SOL、USDC · bsc: BNB、USDC · base: ETH、USDC |

 ---
@@ -4,6 +4,8 @@ description: Query GMGN market data — token K-line (candlestick), trending tok
 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>"
 ---

+**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.**
+
 Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens, or view Trenches token lists.

 ## Sub-commands
@@ -1,9 +1,11 @@
 ---
 name: gmgn-portfolio
-description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, token balance, follow-wallet trades, KOL trades, and Smart Money trades. Supports sol / bsc / base.
-argument-hint: "<info|holdings|activity|stats|token-balance|follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
+description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, and token balance. Supports sol / bsc / base.
+argument-hint: "<info|holdings|activity|stats|token-balance> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
 ---

+**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.**
+
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.

 ## Sub-commands
@@ -15,9 +17,6 @@ Use the `gmgn-cli` tool to query wallet portfolio data based on the user's reque
 | `portfolio activity` | Transaction history |
 | `portfolio stats` | Trading statistics (supports batch) |
 | `portfolio token-balance` | Token balance for a specific token |
-| `portfolio follow-wallet` | Follow-wallet trade records |
-| `portfolio kol` | KOL trade records (SOL chain) |
-| `portfolio smartmoney` | Smart Money trade records (SOL chain) |

 ## Supported Chains

@@ -104,49 +103,10 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 |--------|-------------|
 | `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |

-## `portfolio follow-wallet` Options
-
-| Option | Description |
-|--------|-------------|
-| `--chain` | Required. `sol` / `bsc` / `base` / `eth` |
-| `--wallet <address>` | Filter by wallet address |
-| `--base-token <address>` | Filter by base token address |
-| `--page-token <cursor>` | Pagination cursor |
-| `--limit <n>` | Page size (1–200, default 100) |
-| `--side <side>` | Trade direction filter |
-| `--cost <cost>` | Cost filter |
-| `--filter <tag...>` | Repeatable filter conditions |
-| `--with-balance` | Include balance in response |
-| `--with-security` | Include security info in response |
-| `--min-amount-usd <n>` | Minimum trade amount (USD) |
-| `--max-amount-usd <n>` | Maximum trade amount (USD) |
-| `--is-gray` | Gray mode filter |
-
-## `portfolio kol` / `portfolio smartmoney` Options
-
-| Option | Description |
-|--------|-------------|
-| `--limit <n>` | Page size (1–200, default 100) |
-
-Both `kol` and `smartmoney` return SOL chain data only — no `--chain` flag needed.
-
-```bash
-# Follow-wallet trades filtered by wallet
-gmgn-cli portfolio follow-wallet --chain sol --wallet <wallet_address>
-
-# Follow-wallet with balance info
-gmgn-cli portfolio follow-wallet --chain sol --with-balance --limit 20
-
-# KOL trade records
-gmgn-cli portfolio kol --limit 10 --raw
-
-# Smart Money trade records
-gmgn-cli portfolio smartmoney --limit 10 --raw
-```
-
 ## Notes

 - All portfolio commands use normal auth (API Key only, no signature required)
 - `portfolio stats` supports multiple `--wallet` flags for batch queries
 - Use `--raw` to get single-line JSON for further processing
 - **Input validation** — Wallet and token addresses are validated against the expected chain format at runtime (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits). The CLI exits with an error on invalid input.
+- For follow-wallet, KOL, and Smart Money trade records, use the `gmgn-track` skill (`track follow-wallet` / `track kol` / `track smartmoney`)
@@ -4,6 +4,8 @@ description: "[FINANCIAL EXECUTION] Submit a real blockchain token swap or query
 argument-hint: "[--chain <chain> --from <wallet> --input-token <addr> --output-token <addr> --amount <n>] | [order get --chain <chain> --order-id <id>]"
 ---

+**IMPORTANT: Always use `gmgn-cli` commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai — all swap operations must go through the CLI. The CLI handles signing and submission automatically.**
+
 Use the `gmgn-cli` tool to submit a token swap or query an existing order. **Requires private key** (`GMGN_PRIVATE_KEY` in `.env`).

 ## Financial Risk Notice
@@ -4,6 +4,8 @@ description: Query GMGN token information — basic info, security, pool, top ho
 argument-hint: "<sub-command> --chain <sol|bsc|base> --address <token_address>"
 ---

+**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.**
+
 Use the `gmgn-cli` tool to query token information based on the user's request.

 ## Sub-commands
@@ -0,0 +1,114 @@
+---
+name: gmgn-track
+description: Query GMGN on-chain tracking data — follow-wallet trade records, KOL trades, and Smart Money trades. Supports sol / bsc / base.
+argument-hint: "<follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
+---
+
+**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.**
+
+Use the `gmgn-cli` tool to query on-chain tracking data based on the user's request.
+
+**When to use which sub-command:**
+- `track follow-wallet` — user asks "what did the wallets I follow trade?", "show me my follow list trades", "追踪关注的钱包交易动态" → requires wallets followed via GMGN platform
+- `track kol` — user asks "what are KOLs buying?", "KOL 最近在买什么", "show me influencer trades" → returns trades from known KOL wallets
+- `track smartmoney` — user asks "what is smart money doing?", "聪明钱最近在买什么", "show me whale trades" → returns trades from smart money / whale wallets
+
+**Do NOT confuse these three:**
+- `follow-wallet` = wallets the user has personally followed on GMGN
+- `kol` = platform-tagged KOL / influencer wallets (not user-specific)
+- `smartmoney` = platform-tagged smart money / whale wallets (not user-specific)
+
+## Sub-commands
+
+| Sub-command | Description |
+|-------------|-------------|
+| `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 |
+
+## Supported Chains
+
+`sol` / `bsc` / `base`
+
+## Prerequisites
+
+- `.env` file with `GMGN_API_KEY` set
+- `GMGN_PRIVATE_KEY` required for `track follow-wallet` (signature auth); not needed for `track kol` / `track smartmoney`
+- Run from the directory where your `.env` file is located, or set `GMGN_HOST` in your environment
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
+
+## Usage Examples
+
+```bash
+# Follow-wallet trades (all wallets you follow)
+gmgn-cli track follow-wallet --chain sol
+
+# Follow-wallet trades filtered by wallet
+gmgn-cli track follow-wallet --chain sol --wallet <wallet_address>
+
+# Follow-wallet filtered by trade direction
+gmgn-cli track follow-wallet --chain sol --side buy
+
+# Follow-wallet filtered by USD amount range
+gmgn-cli track follow-wallet --chain sol --min-amount-usd 100 --max-amount-usd 10000
+
+# KOL trade records (SOL, default)
+gmgn-cli track kol --limit 10 --raw
+
+# KOL trade records on SOL, buy only
+gmgn-cli track kol --chain sol --side buy --limit 10 --raw
+
+# Smart Money trade records (SOL, default)
+gmgn-cli track smartmoney --limit 10 --raw
+
+# Smart Money trade records, sell only
+gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw
+```
+
+## `track follow-wallet` Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required. `sol` / `bsc` / `base` |
+| `--wallet <address>` | Filter by wallet address |
+| `--limit <n>` | Page size (1–100, default 10) |
+| `--side <side>` | Trade direction: `buy` / `sell` |
+| `--filter <tag...>` | Repeatable filter conditions |
+| `--min-amount-usd <n>` | Minimum trade amount (USD) |
+| `--max-amount-usd <n>` | Maximum trade amount (USD) |
+
+## `track kol` / `track smartmoney` Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain <chain>` | Chain: `sol` / `bsc` / `base` (default `sol`) |
+| `--limit <n>` | Page size (1–200, default 100) |
+| `--side <side>` | Filter by trade direction: `buy` / `sell` (client-side filter — applied locally after fetching results) |
+
+## `track kol` / `track smartmoney` Response Fields
+
+Each item in `list` contains:
+
+| Field | Description |
+|-------|-------------|
+| `transaction_hash` | On-chain transaction hash |
+| `maker` | Wallet address of the trader (KOL / Smart Money) |
+| `side` | Trade direction: `buy` or `sell` |
+| `base_address` | Token contract address |
+| `base_token.symbol` | Token ticker symbol |
+| `base_token.launchpad` | Launchpad platform (e.g. `pump`) |
+| `amount_usd` | Trade value in USD |
+| `token_amount` | Token quantity traded |
+| `price_usd` | Token price in USD at time of trade |
+| `buy_cost_usd` | Original buy cost in USD (0 if this record is the buy) |
+| `is_open_or_close` | `0` = position opened / added, `1` = position closed / reduced |
+| `timestamp` | Unix timestamp of the trade |
+| `maker_info.twitter_username` | KOL's Twitter username |
+| `maker_info.tags` | Wallet tags (e.g. `kol`, `smart_degen`, `photon`) |
+
+## Notes
+
+- `track kol` / `track smartmoney` use normal auth (API Key only, no signature required)
+- `track follow-wallet` requires `GMGN_PRIVATE_KEY` for signature auth — and wallets must be followed via the GMGN platform first
+- Use `--raw` to get single-line JSON for further processing
+- `track kol` / `track smartmoney` `--side` is a **client-side filter** — the CLI fetches all results then filters locally; it is NOT sent to the API
@@ -148,17 +148,19 @@ export class OpenApiClient {
  }

  async getFollowWallet(chain: string, extra: Record<string, string | number | string[]> = {}): Promise<unknown> {
-    return this.normalRequest("GET", "/v1/trade/follow_wallet", { chain, ...extra });
+    return this.criticalRequest("GET", "/v1/trade/follow_wallet", { chain, ...extra }, null);
  }

-  async getKol(limit?: number): Promise<unknown> {
+  async getKol(chain?: string, limit?: number): Promise<unknown> {
    const query: Record<string, string | number> = {};
+    if (chain) query["chain"] = chain;
    if (limit != null) query["limit"] = limit;
    return this.normalRequest("GET", "/v1/user/kol", query);
  }

-  async getSmartMoney(limit?: number): Promise<unknown> {
+  async getSmartMoney(chain?: string, limit?: number): Promise<unknown> {
    const query: Record<string, string | number> = {};
+    if (chain) query["chain"] = chain;
    if (limit != null) query["limit"] = limit;
    return this.normalRequest("GET", "/v1/user/smartmoney", query);
  }
@@ -113,63 +113,5 @@ export function registerPortfolioCommands(program: Command): void {
      printResult(data, opts.raw);
    });

-  portfolio
-    .command("follow-wallet")
-    .description("Get follow-wallet trade records")
-    .requiredOption("--chain <chain>", "Chain: sol / bsc / base / eth")
-    .option("--wallet <address>", "Filter by wallet address")
-    .option("--base-token <address>", "Filter by base token address")
-    .option("--page-token <cursor>", "Pagination cursor")
-    .option("--limit <n>", "Page size (1–200, default 100)", parseInt)
-    .option("--side <side>", "Trade direction filter")
-    .option("--cost <cost>", "Cost filter")
-    .option("--filter <tag...>", "Filter conditions, repeatable")
-    .option("--with-balance", "Include balance in response")
-    .option("--with-security", "Include security info in response")
-    .option("--min-amount-usd <n>", "Minimum trade amount (USD)", parseFloat)
-    .option("--max-amount-usd <n>", "Maximum trade amount (USD)", parseFloat)
-    .option("--is-gray", "Gray mode filter")
-    .option("--raw", "Output raw JSON")
-    .action(async (opts) => {
-      validateChain(opts.chain);
-      const extra: Record<string, string | number | string[]> = {};
-      if (opts.wallet) extra["wallet_address"] = opts.wallet;
-      if (opts.baseToken) extra["base_token"] = opts.baseToken;
-      if (opts.pageToken) extra["page_token"] = opts.pageToken;
-      if (opts.limit != null) extra["limit"] = opts.limit;
-      if (opts.side) extra["side"] = opts.side;
-      if (opts.cost) extra["cost"] = opts.cost;
-      if (opts.filter?.length) extra["filters"] = opts.filter;
-      if (opts.withBalance) extra["with_balance"] = "true";
-      if (opts.withSecurity) extra["with_security"] = "true";
-      if (opts.minAmountUsd != null) extra["min_amount_usd"] = opts.minAmountUsd;
-      if (opts.maxAmountUsd != null) extra["max_amount_usd"] = opts.maxAmountUsd;
-      if (opts.isGray) extra["is_gray"] = "true";
-      const client = new OpenApiClient(getConfig());
-      const data = await client.getFollowWallet(opts.chain, extra).catch(exitOnError);
-      printResult(data, opts.raw);
-    });
-
-  portfolio
-    .command("kol")
-    .description("Get KOL trade records (SOL chain)")
-    .option("--limit <n>", "Page size (1–200, default 100)", parseInt)
-    .option("--raw", "Output raw JSON")
-    .action(async (opts) => {
-      const client = new OpenApiClient(getConfig());
-      const data = await client.getKol(opts.limit).catch(exitOnError);
-      printResult(data, opts.raw);
-    });
-
-  portfolio
-    .command("smartmoney")
-    .description("Get Smart Money trade records (SOL chain)")
-    .option("--limit <n>", "Page size (1–200, default 100)", parseInt)
-    .option("--raw", "Output raw JSON")
-    .action(async (opts) => {
-      const client = new OpenApiClient(getConfig());
-      const data = await client.getSmartMoney(opts.limit).catch(exitOnError);
-      printResult(data, opts.raw);
-    });
 }

@@ -0,0 +1,68 @@
+import { Command } from "commander";
+import { OpenApiClient } from "../client/OpenApiClient.js";
+import { getConfig } from "../config.js";
+import { exitOnError, printResult } from "../output.js";
+import { validateChain } from "../validate.js";
+
+export function registerTrackCommands(program: Command): void {
+  const track = program.command("track").description("On-chain tracking commands: follow-wallet trades, KOL trades, Smart Money trades");
+
+  track
+    .command("follow-wallet")
+    .description("Get follow-wallet trade records")
+    .requiredOption("--chain <chain>", "Chain: sol / bsc / base")
+    .option("--wallet <address>", "Filter by wallet address")
+    .option("--limit <n>", "Page size (1–100, default 10)", parseInt)
+    .option("--side <side>", "Trade direction filter: buy / sell")
+    .option("--filter <tag...>", "Filter conditions, repeatable")
+    .option("--min-amount-usd <n>", "Minimum trade amount (USD)", parseFloat)
+    .option("--max-amount-usd <n>", "Maximum trade amount (USD)", parseFloat)
+    .option("--raw", "Output raw JSON")
+    .action(async (opts) => {
+      validateChain(opts.chain);
+      const extra: Record<string, string | number | string[]> = {};
+      if (opts.wallet) extra["wallet_address"] = opts.wallet;
+      if (opts.limit != null) extra["limit"] = opts.limit;
+      if (opts.side) extra["side"] = opts.side;
+      if (opts.filter?.length) extra["filters"] = opts.filter;
+      if (opts.minAmountUsd != null) extra["min_amount_usd"] = opts.minAmountUsd;
+      if (opts.maxAmountUsd != null) extra["max_amount_usd"] = opts.maxAmountUsd;
+      const client = new OpenApiClient(getConfig(true));
+      const data = await client.getFollowWallet(opts.chain, extra).catch(exitOnError);
+      printResult(data, opts.raw);
+    });
+
+  track
+    .command("kol")
+    .description("Get KOL trade records")
+    .option("--chain <chain>", "Chain: sol / bsc / base")
+    .option("--limit <n>", "Page size (1–200, default 100)", parseInt)
+    .option("--side <side>", "Filter by trade direction: buy / sell (client-side filter)")
+    .option("--raw", "Output raw JSON")
+    .action(async (opts) => {
+      if (opts.chain) validateChain(opts.chain);
+      const client = new OpenApiClient(getConfig());
+      const data = await client.getKol(opts.chain, opts.limit).catch(exitOnError) as { list?: { side: string }[] };
+      if (opts.side && data?.list) {
+        data.list = data.list.filter((item) => item.side === opts.side);
+      }
+      printResult(data, opts.raw);
+    });
+
+  track
+    .command("smartmoney")
+    .description("Get Smart Money trade records")
+    .option("--chain <chain>", "Chain: sol / bsc / base")
+    .option("--limit <n>", "Page size (1–200, default 100)", parseInt)
+    .option("--side <side>", "Filter by trade direction: buy / sell (client-side filter)")
+    .option("--raw", "Output raw JSON")
+    .action(async (opts) => {
+      if (opts.chain) validateChain(opts.chain);
+      const client = new OpenApiClient(getConfig());
+      const data = await client.getSmartMoney(opts.chain, opts.limit).catch(exitOnError) as { list?: { side: string }[] };
+      if (opts.side && data?.list) {
+        data.list = data.list.filter((item) => item.side === opts.side);
+      }
+      printResult(data, opts.raw);
+    });
+}
@@ -8,6 +8,7 @@ import { Command } from "commander";
 import { registerTokenCommands } from "./commands/token.js";
 import { registerMarketCommands } from "./commands/market.js";
 import { registerPortfolioCommands } from "./commands/portfolio.js";
+import { registerTrackCommands } from "./commands/track.js";
 import { registerSwapCommands } from "./commands/swap.js";

 const proxy = process.env.HTTPS_PROXY ?? process.env.https_proxy
@@ -50,6 +51,7 @@ program
 registerTokenCommands(program);
 registerMarketCommands(program);
 registerPortfolioCommands(program);
+registerTrackCommands(program);
 registerSwapCommands(program);

 program.parseAsync().catch((err) => {