gmgn-cli 1.1.6 → 1.1.9

package/skills/gmgn-market/SKILL.md

@@ -2,21 +2,52 @@
 name: gmgn-market
 description: Query GMGN market data — token K-line (candlestick), trending token swap data, and Trenches token lists. Supports 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>"
+metadata:
+  cliHelp: "gmgn-cli market --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: 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."**
 
 Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens, or view Trenches token lists.
 
+## Core Concepts
+
+- **`--filter` chain defaults** — SOL and EVM chains have different default safety filters that are applied automatically when `--filter` is omitted. Do not assume the same defaults apply across chains:
+  - **SOL**: defaults to `renounced frozen` (mint and freeze authority renounced)
+  - **BSC / Base (EVM)**: defaults to `not_honeypot verified renounced`
+  - Omitting `--filter` is NOT the same as "no filter" — the chain defaults are always applied. To use a custom filter set, explicitly specify all desired filter tags.
+
+- **`volume` vs `amount` (kline)** — Naming is counterintuitive. `volume` = USD dollar value of trades; `amount` = token units traded. For a token priced at $0.0002, these differ by 5,000×. Always use `volume` for "how much USD was traded" and `amount` for "how many tokens changed hands."
+
+- **`rug_ratio`** — A 0–1 score estimating rug pull likelihood. Values above `0.3` are high-risk. Do not treat as binary — combine with `top_10_holder_rate`, `dev_team_hold_rate`, and `is_honeypot` for a full picture.
+
+- **`smart_degen_count` / `renowned_count`** — Number of platform-tagged smart money wallets (`smart_degen`) and KOL wallets (`renowned`) holding or trading this token. High values are bullish signals. These are GMGN-tagged wallet lists, not user-defined.
+
+- **`hot_level`** — Trending intensity score. Higher = more actively traded right now. Not normalized — compare relative values within the same result set, not across time windows.
+
+- **`renounced_mint` / `renounced_freeze_account`** — SOL-specific. Indicate whether the creator gave up the ability to mint more tokens or freeze wallets. Both being `1` is a safety baseline on Solana. Always `false` on EVM chains (concept does not apply).
+
+- **`is_honeypot`** — EVM-specific (BSC / Base). Indicates whether the token contract prevents selling. Always empty/null on SOL — do not interpret an empty value as "not a honeypot" on Solana.
+
+- **`creator_token_status`** — Dev holding status. `creator_hold` = dev still holds tokens (sell pressure risk). `creator_close` = dev has sold or burned their allocation (exit signal confirmed).
+
+- **`cto_flag`** — Community Takeover flag. `1` = original dev abandoned the project and a community group took over marketing/development. Neutral to positive signal; evaluate in context.
+
+- **Trenches categories** — Three lifecycle stages of launchpad tokens: `new_creation` (just created, still on bonding curve), `near_completion` (bonding curve nearly full, about to graduate), `completed` (graduated to open market / DEX). In the response, `near_completion` is always returned under the key `data.pump` regardless of the input `--type`.
+
+- **`wash_trading` / `rat_trader_amount_rate` / `bundler_rate`** — Risk signals for artificial activity. `is_wash_trading` = coordinated fake volume detected. `rat_trader_amount_rate` = ratio of insider/sneak trading. `bundler_rate` = ratio of bot-bundled buys at launch. High values (> 0.3) suggest manipulated price action.
+
 ## Sub-commands
 
 | Sub-command | Description |
 |-------------|-------------|
 | `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 paltform 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 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) |
 
 ## Supported Chains
 
@@ -67,11 +98,11 @@ The response is an object with a `list` array. Each element in `list` is one can
 
 | User says | `--interval` |
 |-----------|-------------|
-| "1分钟热门" / "1m trending" / "hottest right now" | `1m` |
-| "5分钟" / "5m" | `5m` |
-| "1小时" / "1h" / no time specified (default) | `1h` |
-| "6小时" / "6h" | `6h` |
-| "24小时" / "今日" / "daily" | `24h` |
+| "1m trending" / "hottest right now" | `1m` |
+| "5m" / "5 minute" | `5m` |
+| "1h" / "1 hour" / no time specified (default) | `1h` |
+| "6h" / "6 hour" | `6h` |
+| "24h" / "today" / "daily" | `24h` |
 
 | Option | Description |
 |--------|-------------|
@@ -80,7 +111,7 @@ The response is an object with a `list` array. Each element in `list` is one can
 | `--limit <n>` | Number of results (default 100, max 100) |
 | `--order-by <field>` | Sort field: `default` / `swaps` / `marketcap` / `history_highest_market_cap` / `liquidity` / `volume` / `holder_count` / `smart_degen_count` / `renowned_count` / `gas_fee` / `price` / `change1m` / `change5m` / `change1h` / `creation_timestamp` |
 | `--direction <asc\|desc>` | Sort direction (default `desc`) |
-| `--filter <tag...>` | Repeatable filter tags (chain-specific). **sol** (defaults: `renounced frozen`): `renounced` / `frozen` / `burn` / `token_burnt` / `has_social` / `not_social_dup` / `not_image_dup` / `dexscr_update_link` / `not_wash_trading` / `is_internal_market` / `is_out_market`. **evm** (defaults: `not_honeypot verified renounced`): `not_honeypot` / `verified` / `renounced` / `locked` / `token_burnt` / `has_social` / `not_social_dup` / `not_image_dup` / `dexscr_update_link` / `is_internal_market` / `is_out_market` |
+| `--filter <tag...>` | Repeatable filter tags (chain-specific). **⚠️ SOL defaults: `renounced frozen`; BSC/Base defaults: `not_honeypot verified renounced`.** Omitting `--filter` is NOT "no filter" — chain defaults always apply. **sol** tags: `renounced` / `frozen` / `burn` / `token_burnt` / `has_social` / `not_social_dup` / `not_image_dup` / `dexscr_update_link` / `not_wash_trading` / `is_internal_market` / `is_out_market`. **evm** tags: `not_honeypot` / `verified` / `renounced` / `locked` / `token_burnt` / `has_social` / `not_social_dup` / `not_image_dup` / `dexscr_update_link` / `is_internal_market` / `is_out_market` |
 | `--platform <name...>` | Repeatable platform filter (chain-specific). **sol**: `Pump.fun` / `pump_mayhem` / `pump_mayhem_agent` / `pump_agent` / `letsbonk` / `bonkers` / `bags` / `memoo` / `liquid` / `bankr` / `zora` / `surge` / `anoncoin` / `moonshot_app` / `wendotdev` / `heaven` / `sugar` / `token_mill` / `believe` / `trendsfun` / `trends_fun` / `jup_studio` / `Moonshot` / `boop` / `xstocks` / `ray_launchpad` / `meteora_virtual_curve` / `pool_ray` / `pool_meteora` / `pool_pump_amm` / `pool_orca`. **bsc**: `fourmeme` / `fourmeme_agent` / `bn_fourmeme` / `flap` / `clanker` / `lunafun` / `pool_uniswap` / `pool_pancake`. **base**: `clanker` / `bankr` / `flaunch` / `zora` / `zora_creator` / `baseapp` / `basememe` / `virtuals_v2` / `klik` |
 
 ## Usage Examples
@@ -314,50 +345,80 @@ The response is `data.rank` — an array of rank items. Each item represents one
 
 ## Workflow: Discover Trading Opportunities via Trending
 
-### Step 1 — Fetch trending data
+Full workflow for discovering market opportunities: [`docs/workflow-market-opportunities.md`](../../docs/workflow-market-opportunities.md)
 
-Fetch a broad pool with safe filters:
+Steps: fetch trending (50 results, safe filters) → AI multi-factor analysis (smart money, volume, momentum, liquidity, maturity) → present top 5 table with rationale → offer deep dive or swap.
 
-```bash
-gmgn-cli market trending \
-  --chain <chain> --interval 1h \
-  --order-by volume --limit 50 \
-  --filter not_honeypot --filter has_social --raw
-```
+When results contain interesting tokens, proceed to full token due diligence: [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md)
 
-### Step 2 — AI multi-factor analysis
+**For new / launchpad tokens** (`market trenches`): apply the structured early project screening workflow that includes security check and smart money entry detection — [`docs/workflow-early-project-screening.md`](../../docs/workflow-early-project-screening.md)
 
-Analyze each record in the response using the following signals (apply judgment, not rigid rules):
+**For a daily market overview** (user asks "what's the market like today", "give me a daily brief", "what is smart money buying today"): combine `market trending` + `market trenches` with `gmgn-track smartmoney` — [`docs/workflow-daily-brief.md`](../../docs/workflow-daily-brief.md)
 
-| Signal | Field(s) | Weight | Notes |
-|--------|----------|--------|-------|
-| Smart money interest | `smart_degen_count`, `renowned_count` | High | Key conviction indicator |
-| Bluechip ownership | `bluechip_owner_percentage` | Medium | Quality of holder base |
-| Real trading activity | `volume`, `swaps` | Medium | Distinguishes genuine interest from wash trading |
-| Price momentum | `change1h`, `change5m` | Medium | Prefer positive, non-parabolic moves |
-| Pool safety | `liquidity` | Medium | Low liquidity = high slippage risk |
-| Token maturity | `creation_timestamp` | Low | Avoid tokens less than ~1h old unless other signals are very strong |
+## Token Quality Filter Criteria
 
-Select the **top 5** tokens with the best composite profile. Prefer tokens that perform well across multiple signals rather than excelling in just one.
+When evaluating tokens returned from `market trending` or `market trenches`, apply these criteria to quickly separate high-quality opportunities from noise. Do not present raw results without filtering.
 
-### Step 3 — Present top 5 to user
+### Pass / Watch / Skip Criteria
 
-Present results as a concise table, then give a one-line rationale for each pick:
+| Signal | 🟢 Pass | 🟡 Watch | 🔴 Skip |
+|--------|---------|---------|---------|
+| `smart_degen_count` | ≥ 3 | 1–2 | 0 |
+| `rug_ratio` | < 0.1 | 0.1–0.3 | > 0.3 |
+| `creator_token_status` | `creator_close` | — | `creator_hold` |
+| `is_wash_trading` | `false` | — | `true` → skip immediately |
+| `top_10_holder_rate` | < 0.20 | 0.20–0.50 | > 0.50 |
+| `liquidity` | > $50k | $10k–$50k | < $10k |
+| `has_social` (or any social field present) | yes | — | no (weak signal only) |
 
-```
-Top 5 Trending Tokens — SOL / 1h
+**Quick disqualification rule:** If `rug_ratio > 0.3` OR `is_wash_trading = true` OR `is_honeypot = 1` → skip immediately, no further analysis needed.
 
-# | Symbol | Address (short) | Smart Degens | Volume | 1h Chg | Reasoning
-1 | ...     | ...             | ...          | ...    | ...    | Smart money accumulating + high volume
-2 | ...
-...
-```
+**Strong buy signal combination:** `smart_degen_count ≥ 3` + `rug_ratio < 0.2` + `creator_close` + `is_wash_trading = false` + `liquidity > $50k` → high-quality opportunity, proceed to full token research.
 
-### Step 4 — Follow-up actions
+For full due diligence on any token surfaced here: [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md)
 
-For each token, offer:
-- **Deep dive**: `token info` + `token security` for full due diligence
-- **Swap**: execute directly if the user is satisfied with the trending data alone
+## Token Lifecycle Stage
+
+Use field combinations to determine what stage a token is in. This affects how signals should be interpreted.
+
+### Stage 1 — Early (New Born)
+
+**Indicators:**
+- `creation_timestamp` < 1 hour ago
+- `hot_level` low or just starting to rise
+- `smart_degen_count = 0`, `renowned_count = 0`
+
+**Interpretation:** Too early for smart money signals. No on-chain track record. High risk, high potential reward. **Wait for Stage 2 confirmation before acting.** Only the most risk-tolerant traders enter here.
+
+### Stage 2 — Breakout
+
+**Indicators:**
+- `smart_degen_count ≥ 3` AND rising
+- Volume surging (compare `swaps_1h` vs `swaps_24h / 24` — significantly higher)
+- `price_change_percent1h > 20%`
+- `creator_token_status = creator_hold` is OK at this stage (dev hasn't distributed yet)
+
+**Interpretation:** Strongest entry signal. Smart money is accumulating. Verify security before acting. This window is often short — act on confirmation, not anticipation.
+
+### Stage 3 — Distribution
+
+**Indicators:**
+- `creator_token_status = creator_close` (dev has sold their allocation)
+- `renowned_count` buying (late social signal — KOLs often enter after smart money)
+- `smart_degen_count` plateauing or declining
+- Volume still high but momentum slowing
+
+**Interpretation:** Late stage entry. Smart money may be exiting into retail/KOL demand. Higher risk for new entries. If already holding from Stage 2, evaluate exit levels.
+
+### Stage 4 — Decline
+
+**Indicators:**
+- Volume declining across all windows
+- `holder_count` declining
+- `rat_trader_amount_rate` high (insider/sneak trading dominating)
+- `smart_degen_count = 0` or clearly declining
+
+**Interpretation:** Avoid new entries entirely. If still holding, consider exiting. The opportunity has likely passed.
 
 ## `market trenches` Parameters
 
@@ -376,9 +437,95 @@ For each token, offer:
 | `--type` | No | Categories to query, repeatable: `new_creation` / `near_completion` / `completed` (default: all three) |
 | `--launchpad-platform` | No | Launchpad platform filter, repeatable (default: all platforms for the chain) |
 | `--limit` | No | Max results per category, max 80 (default: 80) |
+| `--filter-preset` | No | Named server-side filter preset: `safe` / `smart-money` / `strict` |
+| `--sort-by` | No | Client-side sort per category: `smart_degen_count` / `renowned_count` / `volume_24h` / `volume_1h` / `swaps_24h` / `swaps_1h` / `rug_ratio` / `holder_count` / `usd_market_cap` / `created_timestamp` |
+| `--direction` | No | Sort direction: `asc` / `desc` (default: `desc`; `asc` for `rug_ratio`) |
+| `--min-*` / `--max-*` | No | Server-side filter range flags — see Filter Fields Reference below |
+
+### Filter Presets
+
+Presets are applied server-side: the API filters tokens before returning results.
+
+| Preset | Server-side filters applied |
+|--------|----------------------------|
+| `safe` | `max_rug_ratio=0.3` + `max_bundler_rate=0.3` + `max_insider_ratio=0.3` |
+| `smart-money` | `min_smart_degen_count=1` |
+| `strict` | `max_rug_ratio=0.3` + `max_bundler_rate=0.3` + `max_insider_ratio=0.3` + `min_smart_degen_count=1` + `min_volume_24h=1000` |
+
+**Preset + explicit flag interaction:** Explicit filter flags always override preset values. For example, `--filter-preset safe --max-rug-ratio 0.1` applies the `safe` preset but overrides rug_ratio threshold to `0.1`.
+
+**All filter flags are sent as part of the API request body (server-side)** — the server filters tokens before returning results. Use `--limit 80` (the default maximum) to maximise the pool.
 
 Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is an array of `RankItem` (same fields as `market trending` rank items). **Important: `data.pump` in the response corresponds to `--type near_completion` in the request. The API always returns this category under the key `pump`, not `near_completion`.**
 
+### Server-Side Filter Fields
+
+All filter flags are sent as part of the API request body — the server filters tokens before returning results. Flags follow the naming convention `--min-{field}` / `--max-{field}`.
+
+| Flag pair | Type | Description |
+|-----------|------|-------------|
+| `--min-volume-24h` / `--max-volume-24h` | float | 24h trading volume (USD) |
+| `--min-net-buy-24h` / `--max-net-buy-24h` | float | 24h net buy volume (USD) |
+| `--min-swaps-24h` / `--max-swaps-24h` | int | 24h total swap count |
+| `--min-buys-24h` / `--max-buys-24h` | int | 24h buy count |
+| `--min-sells-24h` / `--max-sells-24h` | int | 24h sell count |
+| `--min-visiting-count` / `--max-visiting-count` | int | Visitor count |
+| `--min-progress` / `--max-progress` | float | Bonding curve progress (0–1) |
+| `--min-marketcap` / `--max-marketcap` | float | Market cap (USD) |
+| `--min-liquidity` / `--max-liquidity` | float | Liquidity (USD) |
+| `--min-created` / `--max-created` | string | Token age (e.g. `1m` / `5m` / `1h` / `24h`) |
+| `--min-holder-count` / `--max-holder-count` | int | Holder count |
+| `--min-top-holder-rate` / `--max-top-holder-rate` | float | Top-10 holder concentration (0–1) |
+| `--min-rug-ratio` / `--max-rug-ratio` | float | Rug pull risk score (0–1) |
+| `--min-bundler-rate` / `--max-bundler-rate` | float | Bundle-bot trading ratio (0–1) |
+| `--min-insider-ratio` / `--max-insider-ratio` | float | Insider trading ratio (0–1) |
+| `--min-entrapment-ratio` / `--max-entrapment-ratio` | float | Entrapment/Phishing trading ratio (0–1) |
+| `--min-private-vault-hold-rate` / `--max-private-vault-hold-rate` | float | Private vault holding ratio (0–1) |
+| `--min-top70-sniper-hold-rate` / `--max-top70-sniper-hold-rate` | float | Top-70 sniper holding ratio (0–1) |
+| `--min-bot-count` / `--max-bot-count` | int | Bot wallet count |
+| `--min-bot-degen-rate` / `--max-bot-degen-rate` | float | Bot-degen wallet ratio (0–1) |
+| `--min-fresh-wallet-rate` / `--max-fresh-wallet-rate` | float | Fresh wallet ratio (0–1) |
+| `--min-total-fee` / `--max-total-fee` | float | Total fee |
+| `--min-smart-degen-count` / `--max-smart-degen-count` | int | Smart-money holder count |
+| `--min-renowned-count` / `--max-renowned-count` | int | KOL / renowned wallet count |
+| `--min-creator-balance-rate` / `--max-creator-balance-rate` | float | Creator holding ratio (0–1) |
+| `--min-creator-created-count` / `--max-creator-created-count` | int | Creator's total token creation count |
+| `--min-creator-created-open-count` / `--max-creator-created-open-count` | int | Creator's graduated token count |
+| `--min-creator-created-open-ratio` / `--max-creator-created-open-ratio` | float | Creator's graduation ratio (0–1) |
+| `--min-x-follower` / `--max-x-follower` | int | Twitter / X follower count |
+| `--min-twitter-rename-count` / `--max-twitter-rename-count` | int | Twitter rename count |
+| `--min-tg-call-count` / `--max-tg-call-count` | int | Telegram call count |
+
+### Trenches Filter Examples
+
+```bash
+# Apply the safe preset (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --filter-preset safe
+
+# Require at least 1 smart money holder (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --min-smart-degen-count 1
+
+# Safe preset + require smart money + sort by smart degen count (server-side filter, client-side sort)
+gmgn-cli market trenches --chain sol --type new_creation \
+  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count
+
+# Strict preset — safe + smart money + min $1k volume (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --type near_completion \
+  --filter-preset strict --sort-by smart_degen_count
+
+# Manual range filters (all sent server-side)
+gmgn-cli market trenches --chain sol --type new_creation \
+  --max-rug-ratio 0.3 --max-bundler-rate 0.3 --max-insider-ratio 0.3 \
+  --min-smart-degen-count 1 --min-volume-24h 1000
+
+# Filter by token age: only tokens created within the last 30 minutes
+gmgn-cli market trenches --chain sol --type new_creation --max-created 30m
+
+# Filter by market cap range
+gmgn-cli market trenches --chain sol --type new_creation \
+  --min-marketcap 10000 --max-marketcap 500000
+```
+
 ## `market trenches` Response Fields
 
 **Basic Info**
@@ -463,6 +610,46 @@ Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is
 | `dexscr_trending_bar` | Whether paid for Dexscreener trending bar placement |
 | `dexscr_boost_fee` | Amount paid for Dexscreener boost (0 = none) |
 
+**After fetching trenches results, apply the Token Quality Filter Criteria section before presenting tokens to the user.** Do not dump raw results — filter first, then surface the strongest candidates.
+
+### Trenches Filter Examples
+
+```bash
+# Quick safe screen — exclude rugs, wash trading, and bundlers
+gmgn-cli market trenches --chain sol --type new_creation \
+  --filter-preset safe --raw
+
+# Smart money screen — only tokens with smart money or KOL presence
+gmgn-cli market trenches --chain sol \
+  --type new_creation --type near_completion \
+  --filter-preset smart-money \
+  --sort-by smart_degen_count --raw
+
+# Strict screen — safe + smart money + minimum volume, sorted by smart degens
+gmgn-cli market trenches --chain sol --type completed \
+  --filter-preset strict --sort-by smart_degen_count --raw
+
+# Custom filter — no wash trading, rug_ratio <= 0.2, at least 1 smart degen
+gmgn-cli market trenches --chain sol \
+  --type new_creation --type near_completion \
+  --exclude-wash-trading --max-rug-ratio 0.2 --min-smart-degen 1 \
+  --sort-by smart_degen_count --raw
+
+# BSC — safe screen on new tokens from fourmeme
+gmgn-cli market trenches --chain bsc --type new_creation \
+  --launchpad-platform fourmeme --launchpad-platform fourmeme_agent \
+  --filter-preset safe --sort-by volume_1h --raw
+
+# Sort by rug_ratio ascending (safest first), no other filters
+gmgn-cli market trenches --chain sol --type completed \
+  --sort-by rug_ratio --raw
+
+# Find tokens with many holders and strong 1h swap activity
+gmgn-cli market trenches --chain sol --type completed \
+  --min-holders 100 --min-swaps 50 \
+  --sort-by swaps_1h --raw
+```
+
 ### Solana Trenches Examples
 
 ```bash
@@ -547,6 +734,49 @@ gmgn-cli market trenches --chain base --raw \
   --limit 80
 ```
 
+## Output Format
+
+### `market kline` — Price Summary
+
+After fetching candles, present a brief price analysis. Do not dump raw candle arrays.
+
+```
+{symbol} — {resolution} chart ({from} → {to})
+Open: ${open of first candle}  |  Close: ${close of last candle}  |  Range: ${min low} – ${max high}
+Total volume: ${sum of all volume fields} USD
+Trend: [brief description — e.g. "steady uptrend", "sharp drop then recovery", "sideways"]
+```
+
+### `market trending` — Top Tokens Table
+
+Present the top results (default: top 10, or as requested) as a table:
+
+```
+# | Symbol | Price | MCap | Volume ({interval}) | 1h Chg | SM | Liq | Platform | Signal
+```
+
+Where **Signal** = quality flag derived from the token's data:
+- 🟢 Pass: `smart_degen_count ≥ 3` AND `rug_ratio < 0.2` AND `is_wash_trading = false`
+- 🔴 Skip: `rug_ratio > 0.3` OR `is_wash_trading = true` OR `is_honeypot = 1`
+- 🟡 Watch: everything else
+
+Then give a one-line highlight for any standout tokens (e.g. "TOKEN1 has 12 smart money holders and +85% in 1h — 🟢 strong signal").
+
+### `market trenches` — Grouped by Category
+
+Present each category separately with a header:
+
+```
+🆕 New Creation ({count} tokens)
+# | Symbol | Created | Liquidity | Swaps (1h) | Smart Degens | Social
+
+⏳ Near Completion ({count} tokens)
+# | Symbol | Market Cap | Swaps (1h) | Smart Degens | Social
+
+✅ Graduated ({count} tokens)
+# | Symbol | Market Cap | Volume (1h) | Smart Degens | Social
+```
+
 ## Notes
 
 - `market kline`: `--from` and `--to` are Unix timestamps in **seconds** — CLI converts to milliseconds automatically

package/skills/gmgn-portfolio/SKILL.md

@@ -2,14 +2,34 @@
 name: gmgn-portfolio
 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>]"
+metadata:
+  cliHelp: "gmgn-cli portfolio --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."**
 
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
 
+**For full wallet analysis (holdings + stats + activity + verdict), follow [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)**
+
+## Core Concepts
+
+- **`realized_profit` vs `unrealized_profit`** — `realized_profit` = profit locked in from completed sells (cash in hand). `unrealized_profit` = paper gains on positions still held, calculated at current price. These are separate numbers — do not add them unless answering "total P&L including open positions."
+
+- **`profit_change`** — A multiplier ratio, not a dollar amount. `1.5` = +150% return. `0` = break-even. `-0.5` = -50% loss. Computed as `total_profit / cost`. Do not display this as a raw decimal — convert to percentage for user-facing output.
+
+- **`pnl`** — Profit/loss ratio from `portfolio stats`: `realized_profit / total_cost`. Same multiplier format as `profit_change`. A `pnl` of `2.0` means the wallet doubled its money on completed trades over the period.
+
+- **`winrate`** — Ratio of profitable trades over the period (0–1). `0.6` = 60% of trades were profitable. Does not reflect the size of wins vs losses — a wallet can have high winrate but net negative if losses are large.
+
+- **`cost` vs `usd_value`** — In holdings: `cost` is the historical amount spent buying this token (your cost basis); `usd_value` is the current market value of the position. The difference is unrealized P&L.
+
+- **`history_bought_cost` vs `cost`** — `history_bought_cost` is the all-time cumulative spend on this token (including positions already sold). `cost` is the cost basis of the current open position only.
+
+- **Pagination (`cursor`)** — Activity results are paginated. The response includes a `next` field; pass it as `--cursor` to fetch the next page. An empty or missing `next` means you are on the last page.
+
 ## Sub-commands
 
 | Sub-command | Description |
@@ -81,11 +101,9 @@ gmgn-cli portfolio token-balance \
 | `--cursor <cursor>` | Pagination cursor |
 | `--order-by <field>` | Sort field: `usd_value` / `last_active_timestamp` / `realized_profit` / `unrealized_profit` / `total_profit` / `history_bought_cost` / `history_sold_income` (default `usd_value`) |
 | `--direction <asc\|desc>` | Sort direction (default `desc`) |
-| `--sell-out` | Include sold-out positions |
-| `--show-small` | Include small-value positions |
-| `--hide-abnormal` | Hide abnormal positions |
-| `--hide-airdrop` | Hide airdrop positions |
-| `--hide-closed` | Hide closed positions |
+| `--hide-abnormal <bool>` | Hide abnormal positions: `true` / `false` (default: `false`) |
+| `--hide-airdrop <bool>` | Hide airdrop positions: `true` / `false` (default: `true`) |
+| `--hide-closed <bool>` | Hide closed positions: `true` / `false` (default: `true`) |
 | `--hide-open` | Hide open positions |
 
 ## `portfolio activity` Options
@@ -105,6 +123,104 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 |--------|-------------|
 | `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |
 
+## Response Field Reference
+
+### `portfolio holdings` — Key Fields
+
+The response has a `holdings` array. Each item is one token position.
+
+| Field | Description |
+|-------|-------------|
+| `token.address` | Token contract address |
+| `token.symbol` / `token.name` | Token ticker and full name |
+| `token.price` | Current token price in USD |
+| `balance` | Current token balance (human-readable units) |
+| `usd_value` | Current USD value of this position |
+| `cost` | Total amount spent buying this token (USD) |
+| `realized_profit` | Profit from completed sells (USD) |
+| `unrealized_profit` | Profit on current unsold holdings at current price (USD) |
+| `total_profit` | `realized_profit + unrealized_profit` (USD) |
+| `profit_change` | Total profit ratio = `total_profit / cost` (e.g. `1.5` = +150%) |
+| `avg_cost` | Average buy price per token (USD) |
+| `buy_tx_count` | Number of buy transactions |
+| `sell_tx_count` | Number of sell transactions |
+| `last_active_timestamp` | Unix timestamp of the most recent transaction |
+| `history_bought_cost` | Total USD spent buying (all-time) |
+| `history_sold_income` | Total USD received from selling (all-time) |
+
+### `portfolio activity` — Key Fields
+
+The response has a `activities` array and a `next` cursor field for pagination.
+
+| Field | Description |
+|-------|-------------|
+| `transaction_hash` | On-chain transaction hash |
+| `type` | Transaction type: `buy` / `sell` / `add` / `remove` / `transfer` |
+| `token.address` | Token contract address |
+| `token.symbol` | Token ticker |
+| `token_amount` | Token quantity in this transaction |
+| `cost_usd` | USD value of this transaction |
+| `price` | Token price in USD at time of transaction |
+| `timestamp` | Unix timestamp of the transaction |
+| `next` | Pagination cursor — pass to `--cursor` to fetch the next page |
+
+### `portfolio stats` — Key Fields
+
+The response is an object (or array for batch). Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `realized_profit` | Total realized profit over the period (USD) |
+| `unrealized_profit` | Total unrealized profit on open positions (USD) |
+| `winrate` | Win rate — ratio of profitable trades (0–1) |
+| `total_cost` | Total amount spent buying in the period (USD) |
+| `buy_count` | Number of buy transactions |
+| `sell_count` | Number of sell transactions |
+| `pnl` | Profit/loss ratio = `realized_profit / total_cost` |
+
+**Do NOT guess field names not listed here.** If a field appears in the response but is not in this table, do not interpret it without reading the raw output first.
+
+## Output Format
+
+**Do NOT dump raw JSON.** Always parse and present data in the structured formats below. Use `--raw` only when piping to `jq` or further processing.
+
+### `portfolio holdings` — Holdings Table
+
+Present a table sorted by `usd_value` (descending). Show total portfolio value at the top.
+
+```
+Wallet: {wallet} | Chain: {chain}
+Total value: ~${sum of usd_value across all positions}
+
+# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells
+```
+
+Flag positions where `profit_change` is strongly negative (e.g. < -50%) or positive (e.g. > 200%) with a brief note.
+
+### `portfolio activity` — Activity Feed
+
+Present as a chronological list (newest first). Use human-readable timestamps.
+
+```
+{type} {token.symbol}  |  {token_amount} tokens  |  ${cost_usd}  |  {timestamp}  |  tx: {short hash}
+```
+
+Group by token if the user asks about a specific token.
+
+### `portfolio stats` — Stats Summary
+
+```
+Wallet: {wallet} | Period: {period}
+Realized P&L:   ${realized_profit}
+Unrealized P&L: ${unrealized_profit}
+Win Rate:        {winrate × 100}%
+Total Spent:     ${total_cost}
+Buys / Sells:    {buy_count} / {sell_count}
+PnL Ratio:       {pnl}x
+```
+
+For batch queries (multiple wallets), present one summary block per wallet.
+
 ## Notes
 
 - All portfolio commands use normal auth (API Key only, no signature required)
@@ -112,3 +228,14 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 - 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`)
+
+## Workflow
+
+For full wallet analysis including trade history and follow-through on top holdings, see [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)
+
+For in-depth trading style analysis, copy-trade ROI estimation, and smart money leaderboard comparison, see [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)
+
+**When to use which:**
+- User asks "is this wallet worth following" → [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)
+- User asks "what's this wallet's trading style", "when does he take profit", "smart money profile", "if I copied this wallet what would my return be" → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)
+- User wants to compare multiple smart money wallets by winrate/PnL → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md) Step 5 (leaderboard)