gmgn-cli 1.1.6 → 1.1.8

package/skills/gmgn-token/SKILL.md

@@ -2,14 +2,34 @@
 name: gmgn-token
 description: Query GMGN token information — basic info, security, pool, top holders and top traders. Supports sol / bsc / base.
 argument-hint: "<sub-command> --chain <sol|bsc|base> --address <token_address>"
+metadata:
+  cliHelp: "gmgn-cli token --help"
 ---
 
 **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.**
 
-**⚠️ IPv6 NOT SUPPORTED: GMGN CLI commands do not support IPv6. If you get a `401` or `403` error and credentials look correct, the outbound connection is likely going via IPv6. Run `curl -s https://api64.ipify.org` to check — if the result is an IPv6 address, tell the user to ensure their network routes requests over IPv4.**
+**⚠️ 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."**
+
+**IMPORTANT: Do NOT guess field names or values. When a field's meaning is unclear, look it up in the Response Field Reference tables below before using it.**
 
 Use the `gmgn-cli` tool to query token information based on the user's request.
 
+## Core Concepts
+
+- **Token address** — The on-chain contract address that uniquely identifies a token on its chain. Required for all token sub-commands. Format: base58 (SOL) or `0x...` hex (BSC/Base).
+- **Chain** — The blockchain network: `sol` = Solana, `bsc` = BNB Smart Chain, `base` = Base (Coinbase L2).
+- **Market cap** — Not returned directly by `token info`. Calculate as `price × circulating_supply` (both are top-level fields in the response, already in human-readable units).
+- **Liquidity** — USD value of token reserves in the main trading pool. Low liquidity (< $10k) means high price impact / slippage when buying or selling.
+- **Holder** — A wallet that currently holds the token. `token holders` returns wallets ranked by current balance.
+- **Trader** — Any wallet that has transacted with the token (bought or sold), regardless of current holdings. `token traders` covers both current holders and past traders.
+- **Smart money (`smart_degen`)** — Wallets with a proven track record of profitable trading, tagged by GMGN's algorithm. High `smart_degen_count` is a bullish signal.
+- **KOL (`renowned`)** — Known influencer, fund, or public figure wallets, tagged by GMGN. Their positions are publicly tracked.
+- **Honeypot** — A token where buy transactions succeed but sell transactions always fail. User funds become permanently trapped. Only detectable on BSC/Base (`is_honeypot`); not applicable on SOL.
+- **Renounced (mint / freeze / ownership)** — The developer has permanently given up that authority. On SOL: `renounced_mint` (cannot create new supply) and `renounced_freeze_account` (cannot freeze wallets) both `true` is the safe baseline. On EVM: `owner_renounced` `"yes"` means no admin backdoors.
+- **rug_ratio** — A 0–1 risk score estimating the likelihood of a rug pull. Values above `0.3` are high-risk. Do not treat as a binary safe/unsafe flag — use in combination with other signals.
+- **Bonding curve** — Price discovery mechanism used by launchpads (e.g. Pump.fun, letsbonk). Token price rises as more is bought. When the curve fills, the token "graduates" to an open DEX pool. `is_on_curve: true` means the token has not graduated yet.
+- **Wallet tags** — GMGN-assigned labels on wallets: `smart_degen` (smart money), `renowned` (KOL), `sniper` (launched at token open), `bundler` (bot-bundled buy), `rat_trader` (insider/sneak trading). Use `--tag` to filter `token holders` / `token traders` by these labels.
+
 ## Sub-commands
 
 | Sub-command | Description |
@@ -67,6 +87,23 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
 | `renowned` | KOL / well-known wallets (influencers, funds, public figures) |
 | `smart_degen` | Smart money wallets (historically high-performing traders) |
 
+### `--tag` + `--order-by` Combination Guide
+
+`--tag` and `--order-by` are independent — all `--order-by` values are valid with or without `--tag`. Omitting `--tag` returns all wallets (no filter).
+
+Recommended combinations for common use cases:
+
+| Goal | `--tag` | `--order-by` |
+|------|---------|--------------|
+| Largest smart money holders by supply | `smart_degen` | `amount_percentage` |
+| Smart money with highest realized profit | `smart_degen` | `profit` |
+| Smart money sitting on unrealized gains | `smart_degen` | `unrealized_profit` |
+| Smart money aggressively accumulating | `smart_degen` | `buy_volume_cur` |
+| Smart money distributing (exit signal) | `smart_degen` | `sell_volume_cur` |
+| KOLs who already took profit | `renowned` | `profit` |
+| KOLs still holding with paper gains | `renowned` | `unrealized_profit` |
+| Largest holders overall (no filter) | *(omit)* | `amount_percentage` |
+
 ## Response Field Reference
 
 ### `token info` — Key Fields
@@ -209,23 +246,106 @@ The response has four nested objects: `pool`, `link`, `stat`, `wallet_tags_stat`
 
 ---
 
-### `token holders` / `token traders` — Item Fields
+### `token holders` / `token traders` — Response Fields
+
+The response is an object with a `list` array. Each item in `list` represents one wallet.
 
-Each item in the result array:
+**Identity & Holdings**
 
 | Field | Description |
 |-------|-------------|
 | `address` | Wallet address |
-| `name` | Wallet label or alias (if known) |
-| `tags` | Wallet tags (e.g. `["renowned"]`, `["smart_degen"]`) |
-| `amount_percentage` | Percentage of total supply held (0–1); e.g. `0.05` = 5% |
-| `amount` | Raw token amount held |
-| `value` | USD value of holdings |
-| `profit` | Realized profit in USD (positive = profit, negative = loss) |
-| `unrealized_profit` | Unrealized profit in USD based on current price |
-| `buy_volume_cur` | Total buy volume in USD for the current period |
-| `sell_volume_cur` | Total sell volume in USD for the current period |
-| `profit_change` | Profit change ratio |
+| `account_address` | Token account address (the on-chain account holding the token, distinct from the wallet address) |
+| `addr_type` | Address type: `0` = regular wallet, `2` = exchange / liquidity pool |
+| `exchange` | Exchange or pool name if `addr_type` is `2` (e.g. `pump_amm`, `raydium`) |
+| `wallet_tag_v2` | Rank label in this list (e.g. `TOP1`, `TOP2`, ...) |
+| `native_balance` | Native token balance in smallest unit (lamports for SOL) |
+| `balance` | Current token balance (human-readable units) |
+| `amount_cur` | Same as `balance` — current token amount held |
+| `usd_value` | USD value of current holdings at current price |
+| `amount_percentage` | Ratio of total supply held (0–1); e.g. `0.05` = 5% |
+| `is_on_curve` | `true` = still on bonding curve (pump.fun pre-graduation); `false` = open market |
+| `is_new` | Whether this is a newly created wallet |
+| `is_suspicious` | Whether this wallet is flagged as suspicious |
+| `transfer_in` | Whether the current holding was received via transfer (not bought) |
+
+**Trading Summary**
+
+| Field | Description |
+|-------|-------------|
+| `buy_volume_cur` | Total buy volume in USD |
+| `sell_volume_cur` | Total sell volume in USD |
+| `buy_amount_cur` | Total tokens bought |
+| `sell_amount_cur` | Total tokens sold |
+| `sell_amount_percentage` | Ratio of bought tokens that have been sold (0–1); `1.0` = fully exited |
+| `buy_tx_count_cur` | Number of buy transactions |
+| `sell_tx_count_cur` | Number of sell transactions |
+| `netflow_usd` | Net USD flow = sell income − buy cost (negative = net spent) |
+| `netflow_amount` | Net token flow = bought − sold (positive = still holding net position) |
+
+**Cost & P&L**
+
+| Field | Description |
+|-------|-------------|
+| `avg_cost` | Average buy price in USD per token |
+| `avg_sold` | Average sell price in USD per token |
+| `history_bought_cost` | Total USD spent buying |
+| `history_bought_fee` | Total fees paid on buys in USD |
+| `history_sold_income` | Total USD received from selling |
+| `history_sold_fee` | Total fees paid on sells in USD |
+| `total_cost` | Total cost basis including fees |
+| `profit` | Total profit in USD (realized + unrealized) |
+| `profit_change` | Total profit ratio = profit / total_cost |
+| `realized_profit` | Realized profit in USD from completed sells |
+| `realized_pnl` | Realized profit ratio = realized_profit / buy_cost |
+| `unrealized_profit` | Unrealized profit in USD on current holdings at current price |
+| `unrealized_pnl` | Unrealized profit ratio; `null` if no current holdings |
+
+**Transfer History**
+
+| Field | Description |
+|-------|-------------|
+| `current_transfer_in_amount` | Tokens received via transfer (not bought) in current period |
+| `current_transfer_out_amount` | Tokens sent out via transfer (not sold) in current period |
+| `history_transfer_in_amount` | Historical total tokens received via transfer |
+| `history_transfer_in_cost` | Estimated cost basis of transferred-in tokens |
+| `history_transfer_out_amount` | Historical total tokens sent out via transfer |
+| `history_transfer_out_income` | Estimated income from transferred-out tokens |
+| `history_transfer_out_fee` | Fees paid on transfer-outs |
+| `transfer_in_count` | Number of inbound transfers |
+| `transfer_out_count` | Number of outbound transfers |
+
+**Timing**
+
+| Field | Description |
+|-------|-------------|
+| `start_holding_at` | Unix timestamp when wallet first acquired this token |
+| `end_holding_at` | Unix timestamp when wallet fully exited; `null` if still holding |
+| `last_active_timestamp` | Unix timestamp of most recent on-chain activity for this token |
+| `last_block` | Block number of last activity |
+
+**Wallet Identity**
+
+| Field | Description |
+|-------|-------------|
+| `name` | Wallet display name (if known) |
+| `twitter_username` | Twitter / X username |
+| `twitter_name` | Twitter / X display name |
+| `avatar` | Avatar image URL |
+| `tags` | Platform-level wallet tags (e.g. `["kol"]`, `["smart_degen"]`, `["axiom"]`) |
+| `maker_token_tags` | Token-specific behavior tags for this wallet (e.g. `["bundler"]`, `["paper_hands"]`, `["top_holder"]`) |
+| `created_at` | Wallet creation timestamp (Unix seconds); `0` if unknown |
+
+**Last Transaction Records**
+
+Each of the following is an object with `name`, `address`, `timestamp`, `tx_hash`, `type`:
+
+| Field | Description |
+|-------|-------------|
+| `native_transfer` | Most recent native token (SOL/BNB/ETH) transfer associated with this wallet |
+| `token_transfer` | Most recent token transfer (buy or sell) |
+| `token_transfer_in` | Most recent inbound token transfer |
+| `token_transfer_out` | Most recent outbound token transfer |
 
 ---
 
@@ -312,6 +432,20 @@ gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGG
   --limit 100 --raw
 ```
 
+### `token traders` — `--tag` + `--order-by` Combination Guide
+
+Use this table to pick the right combination for common `token traders` use cases:
+
+| Use case | `--tag` | `--order-by` |
+|----------|---------|-------------|
+| Smart money with highest buy volume | `smart_degen` | `buy_volume_cur` |
+| Smart money with highest sell volume (exit signal) | `smart_degen` | `sell_volume_cur` |
+| KOLs recently active | `renowned` | `last_active_timestamp` |
+| Smart money most profitable traders | `smart_degen` | `profit` |
+| Snipers still holding | `sniper` | `amount_percentage` |
+| Smart money sitting on biggest unrealized gains | `smart_degen` | `unrealized_profit` |
+| KOLs who already took profit | `renowned` | `profit` |
+
 ### `token traders` — Find Active Traders
 
 ```bash
@@ -345,66 +479,92 @@ gmgn-cli token traders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD95
 
 ---
 
-## Workflow: Full Token Due Diligence
+## Token Quick Scoring Card
 
-Use this workflow before deciding to buy a token.
+After fetching `token security` and `token info`, apply this scoring card to give a structured verdict. Do not skip this step when the user asks for a safety check or due diligence.
 
-### Step 1 — Get basic info
+| Field | ✅ Safe | ⚠️ Warning | 🚫 Danger (Hard Stop) |
+|-------|---------|-----------|----------------------|
+| `is_honeypot` | `"no"` | — | `"yes"` → **stop immediately** |
+| `open_source` | `"yes"` | `"unknown"` | `"no"` |
+| `owner_renounced` | `"yes"` | `"unknown"` | `"no"` |
+| `renounced_mint` (SOL) | `true` | — | `false` |
+| `renounced_freeze_account` (SOL) | `true` | — | `false` |
+| `rug_ratio` | `< 0.10` | `0.10–0.30` | `> 0.30` |
+| `top_10_holder_rate` | `< 0.20` | `0.20–0.50` | `> 0.50` |
+| `creator_token_status` | `creator_close` | — | `creator_hold` |
+| `buy_tax` / `sell_tax` | `0` | `0.01–0.05` | `> 0.10` |
+| `sniper_count` | `< 5` | `5–20` | `> 20` |
+| `smart_wallets` (from `wallet_tags_stat`) | `≥ 3` | `1–2` | `0` (bearish, not a hard stop) |
+| `renowned_wallets` (from `wallet_tags_stat`) | `≥ 1` | — | `0` (neutral, not a hard stop) |
+
+**Final scoring logic:**
+- If `is_honeypot = "yes"` → **hard stop immediately**, do not proceed regardless of other signals
+- If other 🚫 fields present → **skip** (strong warning — present to user)
+- `smart_wallets = 0` alone is NOT a hard stop — it means no smart money interest yet, which is bearish but not disqualifying for very new tokens
+- If 3+ ⚠️ with no 🚫 → **needs more research** — present findings and ask user how to proceed
+- If mostly ✅ with `smart_wallets ≥ 3` → **worth researching** — proceed to holders/traders analysis
 
-```bash
-gmgn-cli token info --chain sol --address <token_address> --raw
-```
+## Workflow: Full Token Due Diligence
 
-Check: `price`, `liquidity`, `holder_count`, `wallet_tags_stat.smart_wallets`, `wallet_tags_stat.renowned_wallets`, `link.website` / `link.twitter_username` / `link.telegram`.
+When the user asks for a full token research / due diligence, follow the steps in [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md).
 
-**Red flags**: all `link.*` social fields empty, very low liquidity (<$10k), zero `wallet_tags_stat.smart_wallets` and `renowned_wallets`.
+Steps: `token info` → `token security` → `token pool` → market heat check → `token holders/traders` (smart money signals) → Decision Framework.
 
-### Step 2 — Check security
+**For a more comprehensive report** (user asks for a "deep report", "full analysis", "is this worth a large position"), use the extended workflow: [`docs/workflow-project-deep-report.md`](../../docs/workflow-project-deep-report.md). This adds a scored multi-dimension analysis (fundamentals + security + liquidity + smart money conviction + price action) and produces a full written report.
 
-```bash
-gmgn-cli token security --chain sol --address <token_address> --raw
-```
+**For active risk monitoring** on a held position (user asks "any risk warnings", "are whales dumping", "is liquidity still healthy"), follow: [`docs/workflow-risk-warning.md`](../../docs/workflow-risk-warning.md). Uses `token security` + `token pool` + `token holders` to flag whale exits, liquidity drain, and developer dumps.
 
-Check these fields and their safe thresholds:
+---
 
-| Field | Safe | Warning | Danger |
-|-------|------|---------|--------|
-| `is_honeypot` | `"no"` | — | `"yes"` → Do not buy |
-| `open_source` | `"yes"` | `"unknown"` | `"no"` |
-| `owner_renounced` | `"yes"` | `"unknown"` | `"no"` |
-| `renounced_mint` (SOL) | `true` | — | `false` → mint risk |
-| `renounced_freeze_account` (SOL) | `true` | — | `false` → freeze risk |
-| `buy_tax` / `sell_tax` | `0` | `0.01–0.05` | `>0.10` → high tax |
-| `top_10_holder_rate` | `<0.20` | `0.20–0.40` | `>0.50` → whale risk |
-| `rug_ratio` | `<0.10` | `0.10–0.30` | `>0.30` → high rug risk |
-| `creator_token_status` | `creator_close` | — | `creator_hold` → dev not sold |
-| `sniper_count` | `<5` | `5–20` | `>20` → heavily sniped |
+## Output Format
 
-### Step 3 — Check liquidity pool
+### `token info` — Summary Card
 
-```bash
-gmgn-cli token pool --chain sol --address <token_address> --raw
+Present as a concise card. Do not dump raw JSON.
+
+```
+{symbol} ({name})
+Price: ${price}  |  Market Cap: ~${price × circulating_supply}  |  Liquidity: ${liquidity}
+Holders: {holder_count}  |  Smart Money: {wallet_tags_stat.smart_wallets}  |  KOLs: {wallet_tags_stat.renowned_wallets}
+Social: @{link.twitter_username}  |  {link.website}  |  {link.telegram}
 ```
 
-Check: liquidity amount, which DEX (`exchange`), pool age (`creation_timestamp`). Low liquidity means high slippage risk when buying or selling.
+If any social fields are empty, omit them rather than showing `null`.
 
-### Step 4 — Check smart money signals
+### `token security` — Risk Assessment Summary
 
-```bash
-# Is smart money accumulating?
-gmgn-cli token holders --chain sol --address <token_address> \
-  --tag smart_degen --order-by buy_volume_cur --direction desc --limit 20 --raw
+After fetching security data, present a structured risk summary using this format:
 
-# Have KOLs already taken profit?
-gmgn-cli token traders --chain sol --address <token_address> \
-  --tag renowned --order-by profit --direction desc --limit 20 --raw
+```
+Token: {symbol}  |  Chain: {chain}  |  Address: {short address}
+─── Security ──────────────────────────────────────
+Contract verified:    ✅ yes  / 🚫 no / ⚠️ unknown
+Owner renounced:      ✅ yes  / 🚫 no / ⚠️ unknown
+Honeypot:             ✅ no   / 🚫 YES — DO NOT BUY
+Mint renounced (SOL): ✅ yes  / ⚠️ no
+Freeze renounced(SOL):✅ yes  / ⚠️ no
+Rug risk score:       {rug_ratio} → ✅ <0.1 Low / ⚠️ 0.1–0.3 Med / 🚫 >0.3 High
+Top-10 holder %:      {top_10_holder_rate%} → ✅ <20% / ⚠️ 20–50% / 🚫 >50%
+Dev still holding:    ✅ sold (creator_close) / ⚠️ holding (creator_hold)
+Sniper wallets:       ✅ <5  / ⚠️ 5–20 / 🚫 >20
+─── Smart Money ───────────────────────────────────
+SM holders: {smart_wallets}   KOL holders: {renowned_wallets}
+─── Verdict ───────────────────────────────────────
+🟢 Clean — worth researching
+🟡 Mixed signals — proceed with caution
+🔴 Red flags present — skip or verify manually
 ```
 
-**Bullish signals**: smart_degen wallets buying heavily, unrealized_profit is large (still holding), renowned wallets accumulating, low sell_volume_cur.
+**If `is_honeypot = "yes"`, stop immediately and display: "🚫 HONEYPOT DETECTED — Do not buy this token." Do NOT proceed to further analysis steps.**
 
-**Bearish signals**: sell_volume_cur > buy_volume_cur for smart money, large realized profits already taken (they may be done), top holders with very high amount_percentage starting to sell.
+### `token holders` / `token traders` — Ranked Table
 
----
+```
+# | Wallet (name or short addr) | Hold% | Avg Buy | Realized P&L | Unrealized P&L | Tags
+```
+
+Show top rows only. Highlight wallets tagged `kol`, `smart_degen`, or flagged `bundler` / `rat_trader` in `maker_token_tags`.
 
 ## Notes
 

package/skills/gmgn-track/SKILL.md

@@ -2,31 +2,43 @@
 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>]"
+metadata:
+  cliHelp: "gmgn-cli track --help"
 ---
 
 **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.**
 
-**⚠️ IPv6 NOT SUPPORTED: GMGN CLI commands do not support IPv6. If you get a `401` or `403` error and credentials look correct, the outbound connection is likely going via IPv6. Run `curl -s https://api64.ipify.org` to check — if the result is an IPv6 address, tell the user to ensure their network routes requests over IPv4.**
+**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 — CRITICAL
+**⚠️ 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."**
 
-**The `track follow-wallet` sub-command does NOT support IPv6. Requests MUST go out over IPv4.**
+Use the `gmgn-cli` tool to query on-chain tracking data based on the user's request.
 
-This sub-command is known to fail with `401` or `403` when the outbound connection uses IPv6 — even when credentials are valid.
+## Core Concepts
 
-**How to diagnose:**
-```bash
-curl -s https://api64.ipify.org   # if result is an IPv6 address, that's the problem
-```
+- **`follow-wallet` vs `kol` vs `smartmoney`** — Three distinct data sources. `follow-wallet` returns trades from wallets the user has personally followed on the GMGN platform (user-specific, requires private key). `kol` and `smartmoney` return trades from platform-tagged public wallet lists (not user-specific, API Key only). Never substitute one for another.
 
-**Rule for AI models:** If `track follow-wallet` returns 401/403 and credentials look correct — stop and tell the user: "Your outbound connection may be using IPv6, which is not supported by this command. Please check your network configuration and ensure requests go out over IPv4."
+- **KOL (Key Opinion Leader)** — Wallets publicly identified as influencers or well-known traders on GMGN. Tagged as `renowned` in the platform's wallet label system. Their trades carry social/marketing signal, not necessarily alpha.
 
-Use the `gmgn-cli` tool to query on-chain tracking data based on the user's request.
+- **Smart Money (`smart_degen`)** — Wallets with a statistically proven record of profitable trading, identified by GMGN's algorithm. Same concept as `smart_degen` in gmgn-token. Their trades are a stronger alpha signal than KOL trades.
+
+- **`is_open_or_close`** — Indicates whether a trade is a full position event. Interpretation differs by sub-command:
+  - `follow-wallet`: `1` = full position open or close; `0` = partial add or reduce.
+  - `kol` / `smartmoney`: `0` = position opened / added; `1` = position closed / reduced.
+  Do not apply the same interpretation to both sub-commands.
+
+- **`price_change`** — Ratio of price change since the trade was made. `6.66` = the token is now 6.66× what it was when the wallet traded (i.e. +566%). `0.5` = price halved since the trade (-50%). Use this to assess "how well did this trade age."
+
+- **`base_address` vs `quote_address`** — In a trading pair, `base_address` is the token being bought/sold; `quote_address` is what it was priced in (typically SOL native address on Solana). To get the token of interest, always read `base_address`.
+
+- **`maker_info.tags`** — Array of platform labels on the wallet (e.g. `["kol", "gmgn"]`, `["smart_degen", "photon"]`). A wallet can carry multiple tags. Use `tag_rank` (follow-wallet only) to see the wallet's rank within each tag category.
+
+- **Cluster signal** — When multiple followed/tracked wallets trade the same token in the same direction within a short time window, this is a stronger conviction signal than a single wallet. Highlight this pattern when it appears in results.
 
 **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
+- `track follow-wallet` — user asks "what did the wallets I follow trade?", "show me my follow list trades", "show my followed wallet activity" → requires wallets followed via GMGN platform
+- `track kol` — user asks "what are KOLs buying?", "show me influencer trades", "what are KOLs doing recently" → returns trades from known KOL wallets
+- `track smartmoney` — user asks "what is smart money doing?", "show me whale trades", "what is smart money buying recently" → returns trades from smart money / whale wallets
 
 **Do NOT confuse these three:**
 - `follow-wallet` = wallets the user has personally followed on GMGN
@@ -150,7 +162,7 @@ Each item in `list` contains:
 
 ## `track kol` / `track smartmoney` Response Fields
 
-Each item in `list` contains:
+The response is an object with a `list` array. Each item in `list` contains:
 
 | Field | Description |
 |-------|-------------|
@@ -169,6 +181,101 @@ Each item in `list` contains:
 | `maker_info.twitter_username` | KOL's Twitter username |
 | `maker_info.tags` | Wallet tags (e.g. `kol`, `smart_degen`, `photon`) |
 
+## Smart Money Behavior Interpretation
+
+After receiving trade data, interpret the signals using these frameworks before presenting results. Do not just list trades — analyze what they mean.
+
+### 1. Signal Strength Levels
+
+| Level | Criteria |
+|-------|----------|
+| Weak | 1 KOL buys |
+| Medium | 2–3 smart money buys in the same direction, OR 1 smart money full position open |
+| Strong | ≥ 3 smart money wallets same direction within 30 min (cluster signal) |
+| Very Strong | Cluster signal + full position opens + KOL joining the same trade |
+
+### 2. Reading `is_open_or_close` — Conviction Signals
+
+The field has opposite meanings by sub-command:
+
+- **`follow-wallet`**: `1` = full position open or close; `0` = partial add or reduce.
+- **`kol` / `smartmoney`**: `0` = position opened / added; `1` = position closed / reduced.
+
+Full position events (full open or full close) carry much stronger conviction than partial adds. A wallet opening a full new position signals high confidence. A wallet doing a full close signals they are exiting completely — treat this as a potential exit signal for that token.
+
+### 3. Using `price_change` to Evaluate Track Record
+
+`price_change` is a ratio of current price vs price at trade time:
+- `price_change > 2` → this wallet's trade aged well (token is now 2x+ since they bought) — strong conviction signal
+- `price_change 1–2` → modest gain, trade is in profit
+- `price_change < 1` → trade is underwater (current price below entry)
+
+Use this to build a mental model of a wallet's past performance before acting on their current trades.
+
+### 4. Cluster Signal Detection
+
+When multiple trades hit the same `base_address` in a short time window, this is a convergence signal — stronger than any single trade. To identify:
+- Group results by `base_address`
+- Count distinct `maker` addresses trading the same direction
+- If ≥ 3 distinct wallets buy the same token within ~30 min → highlight as **cluster signal**
+
+Cluster signals from `smartmoney` are stronger than from `kol` alone.
+
+### 5. Red Flags in Smart Money Data
+
+- **Smart money selling** (`side = sell` + `is_open_or_close` = full close) → exit signal — evaluate whether to exit or reduce position
+- **Only KOL buying, zero smart_degen** → social hype without fundamental backing; higher risk
+- **Renowned buying + smart money selling simultaneously** → divergence signal — insiders may be distributing into retail/KOL demand; high risk
+- **Single very large buy, no follow-through** → may be one-off; wait for confirmation from other wallets
+
+## Output Format
+
+### `track follow-wallet` / `track kol` / `track smartmoney` — Trade Feed
+
+Present as a reverse-chronological trade feed. Do not dump raw JSON.
+
+```
+{timestamp}  {side}  {base_token.symbol}  ${amount_usd}  by {maker_info.name or short address}
+             [{tags}]  Price: ${price_usd}  |  Price now: ${price_now}  ({price_change}x since trade)
+```
+
+Group by token if multiple trades hit the same token. Highlight tokens where several followed wallets traded in the same direction within a short window (cluster signal).
+
+For `follow-wallet`, also show `is_open_or_close`: flag full position opens/closes distinctly from partial adds/reduces.
+
+### Cluster Signal Summary
+
+After presenting the trade feed, check for convergence signals. If ≥ 2 distinct wallets traded the same token in the same direction, display a summary block:
+
+```
+⚡ Convergence Signals
+──────────────────────────────────────────
+TOKEN_X ({short_address})
+  5 smart money wallets — all BUY — $42,300 total — within 15 min
+  Signal strength: STRONG
+
+TOKEN_Y ({short_address})
+  2 KOL wallets — BUY (full open) — $8,100 total
+  Signal strength: MEDIUM
+```
+
+For STRONG signals: proceed to full token research before acting — see [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md)
+For MEDIUM signals: monitor and wait for more wallets to confirm before acting.
+
+If no convergence signals are detected: output "No cluster signals detected in this result set."
+
+To research any token surfaced by smart money activity, follow [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md)
+
+**Smart money leaderboard / wallet profiling:** When the user asks "which smart money wallets are best to follow", "rank wallets by win rate", or wants to compare wallet performance — use `track smartmoney` to collect active wallet addresses, then batch-query their stats via `gmgn-portfolio stats`. Full workflow: [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)
+
+**Daily brief:** When the user asks for a market overview ("what's the market like today", "what is smart money buying today", "give me a daily brief") — combine `track smartmoney` + `track kol` with `gmgn-market trending`. Full workflow: [`docs/workflow-daily-brief.md`](../../docs/workflow-daily-brief.md)
+
+## Safety Constraints
+
+- **`track follow-wallet` requires `GMGN_PRIVATE_KEY`** — this signing key is linked to your GMGN account. It is used for authentication only (no on-chain access), but must be protected like any credential. Never expose it in logs or command output.
+- **`follow-wallet` reveals your following list** — results expose which wallets you have followed on GMGN. Do not share raw output in public channels.
+- **`track kol` / `track smartmoney` expose no personal data** — these use API Key auth only and return platform-tagged public wallet activity. Safe to share raw output.
+
 ## Notes
 
 - `track kol` / `track smartmoney` use normal auth (API Key only, no signature required)