fix: move wallet_holdings filter defaults to CLI, remove no-op flags

Portfolio holdings to return empty results for wallets that only have closed positions (issue #21).

Changes:
- Convert --hide-closed, --hide-airdrop, --hide-abnormal to value options with explicit defaults (hide_closed=true, hide_airdrop=true, hide_abnormal=false), so defaults are enforced by the CLI and users can override with e.g. --hide-closed false
- Remove --sell-out and --show-small which are hard-coded in the service and were never forwarded to the upstream API
- Update SKILL.md to reflect new option signatures and defaults

Fixes #21

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

CLAUDE.md

@@ -70,7 +70,7 @@ EOF
 When creating or updating any file in `skills/`:
 
 - **Language**: English only — no bilingual content. SKILL.md files are read by AI, not humans.
-- **Package runner**: Always use the pre-installed `gmgn-cli` binary (e.g. `gmgn-cli token info ...`). Never use `npx gmgn-cli` or `npx gmgn-cli@<version>` — npx downloads the package at runtime alongside live credentials. The package must be installed once with `npm install -g gmgn-cli@1.1.0`.
+- **Package runner**: Always use the pre-installed `gmgn-cli` binary (e.g. `gmgn-cli token info ...`). Never use `npx gmgn-cli` or `npx gmgn-cli@<version>` — npx downloads the package at runtime alongside live credentials. The package must be installed once with `npm install -g gmgn-cli`.
 - **Section order**: Sub-commands → Supported Chains → Prerequisites → Parameters/Options (if needed) → Usage Examples → Notes
 - **`--raw` flag**: All commands support `--raw` for single-line JSON output. Always document it in the Notes section.
 - **YAML frontmatter**: Quote `argument-hint` values that contain `|` characters to avoid YAML parsing errors.

Readme.md

@@ -30,6 +30,8 @@ With GMGN Agent Skills, you can use AI agents to query real-time trending token
 
 Ready to install skills? [Jump to Installation →](#get-started)
 
+Already installed? [Update Skills and CLI →](#9-upgrade-skills-and-cli)
+
 > **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.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "gmgn-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "gmgn-cli",
-      "version": "1.1.3",
+      "version": "1.1.5",
       "license": "MIT",
       "dependencies": {
         "commander": "^12.1.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gmgn-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "GMGN OpenAPI CLI — call GMGN market, token, portfolio and swap APIs from the command line",
   "type": "module",
   "bin": {

skills/gmgn-market/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "kline --chain <sol|bsc|base> --address <token_address> --resolut
 
 **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.**
+
 Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens, or view Trenches token lists.
 
 ## Sub-commands
@@ -24,7 +26,7 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
 
 - `.env` file with `GMGN_API_KEY` set
 - 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`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli`
 
 ## `market kline` Parameters
 

skills/gmgn-portfolio/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "<info|holdings|activity|stats|token-balance> [--chain <sol|bsc|b
 
 **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.**
+
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
 
 ## Sub-commands
@@ -26,7 +28,7 @@ Use the `gmgn-cli` tool to query wallet portfolio data based on the user's reque
 
 - `.env` file with `GMGN_API_KEY` set
 - 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`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli`
 
 ## Usage Examples
 
@@ -79,11 +81,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

skills/gmgn-swap/SKILL.md

@@ -6,6 +6,21 @@ argument-hint: "[--chain <chain> --from <wallet> --input-token <addr> --output-t
 
 **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.**
 
+**⚠️ 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 — CRITICAL
+
+**The `swap` sub-command does NOT support IPv6. Requests MUST go out over IPv4.**
+
+If you receive a `401` or `403` error, the **first thing to check** is whether the machine is sending requests via IPv6. This is a known cause of auth failures even with valid credentials.
+
+**How to diagnose:**
+```bash
+curl -s https://api64.ipify.org   # shows your outbound IP — if it's an IPv6 address, that's the problem
+```
+
+**Rule for AI models:** If `swap` or `order` commands return 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."
+
 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
@@ -48,7 +63,7 @@ Both `GMGN_API_KEY` and `GMGN_PRIVATE_KEY` must be set in `.env`. The private ke
 `gmgn-cli` must be installed globally before use (one-time setup):
 
 ```bash
-npm install -g gmgn-cli@1.1.0
+npm install -g gmgn-cli
 ```
 
 ### Credential Model

skills/gmgn-token/SKILL.md

@@ -6,6 +6,8 @@ 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.**
 
+**⚠️ 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.**
+
 Use the `gmgn-cli` tool to query token information based on the user's request.
 
 ## Sub-commands
@@ -26,7 +28,7 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
 
 - `.env` file with `GMGN_API_KEY` set
 - 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`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli`
 
 ## Parameters — `token info` / `token security` / `token pool`
 
@@ -45,7 +47,7 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
 | `--limit` | No | `20` | Number of results, max `100` |
 | `--order-by` | No | `amount_percentage` | Sort field — see table below |
 | `--direction` | No | `desc` | Sort direction: `asc` / `desc` |
-| `--tag` | No | `renowned` | Wallet filter: `renowned` (KOL wallets) / `smart_degen` (smart money) |
+| `--tag` | No | — | Wallet filter: `renowned` (KOL wallets) / `smart_degen` (smart money) |
 | `--raw` | No | — | Output raw single-line JSON |
 
 ### `--order-by` Values

skills/gmgn-track/SKILL.md

@@ -6,6 +6,21 @@ argument-hint: "<follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--walle
 
 **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 — CRITICAL
+
+**The `track follow-wallet` sub-command does NOT support IPv6. Requests MUST go out over IPv4.**
+
+This sub-command is known to fail with `401` or `403` when the outbound connection uses IPv6 — even when credentials are valid.
+
+**How to diagnose:**
+```bash
+curl -s https://api64.ipify.org   # if result is an IPv6 address, that's the problem
+```
+
+**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."
+
 Use the `gmgn-cli` tool to query on-chain tracking data based on the user's request.
 
 **When to use which sub-command:**
@@ -35,7 +50,7 @@ Use the `gmgn-cli` tool to query on-chain tracking data based on the user's requ
 - `.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`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli`
 
 ## Usage Examples
 
@@ -85,6 +100,54 @@ gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw
 | `--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 follow-wallet` Response Fields
+
+Top-level fields:
+
+| Field | Description |
+|-------|-------------|
+| `next_page_token` | Opaque token for fetching the next page of results |
+| `list` | Array of trade records |
+
+Each item in `list` contains:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Record ID (base64-encoded, use as cursor) |
+| `chain` | Chain name (e.g. `sol`) |
+| `transaction_hash` | On-chain transaction hash |
+| `maker` | Wallet address of the followed wallet |
+| `side` | Trade direction: `buy` or `sell` |
+| `base_address` | Token contract address |
+| `quote_address` | Quote token address (SOL native address for buys/sells on SOL) |
+| `base_amount` | Token quantity in smallest unit |
+| `quote_amount` | Quote token amount spent / received (e.g. SOL) |
+| `amount_usd` | Trade value in USD |
+| `cost_usd` | Same as `amount_usd` — USD value of this transaction leg |
+| `buy_cost_usd` | Original buy cost in USD (`0` if this record is the buy itself) |
+| `price` | Token price denominated in quote token at time of trade |
+| `price_usd` | Token price in USD at time of trade |
+| `price_now` | Token current price in USD |
+| `price_change` | Price change ratio since trade time (e.g. `6.66` = +666%) |
+| `timestamp` | Unix timestamp of the trade |
+| `is_open_or_close` | `1` = full position open or close; `0` = partial add or reduce |
+| `launchpad` | Launchpad display name (e.g. `Pump.fun`) |
+| `launchpad_platform` | Launchpad platform identifier (e.g. `Pump.fun`, `pump_agent`) |
+| `migrated_pool_exchange` | DEX the token migrated to, if any (e.g. `pump_amm`); empty if not migrated |
+| `base_token.symbol` | Token ticker symbol |
+| `base_token.logo` | Token logo image URL |
+| `base_token.hot_level` | Hotness level (`0` = normal, higher = trending) |
+| `base_token.total_supply` | Total token supply (string) |
+| `base_token.token_create_time` | Unix timestamp when token was created |
+| `base_token.token_open_time` | Unix timestamp when trading opened (`0` if not yet migrated/opened) |
+| `maker_info.address` | Followed wallet address |
+| `maker_info.name` | Wallet display name |
+| `maker_info.twitter_username` | Twitter / X username |
+| `maker_info.twitter_name` | Twitter / X display name |
+| `maker_info.tags` | Array of wallet tags (e.g. `["kol","gmgn"]`) |
+| `maker_info.tag_rank` | Map of tag → rank within that category (e.g. `{"kol": 854}`) |
+| `balance_info` | Wallet token balance info; `null` if not available |
+
 ## `track kol` / `track smartmoney` Response Fields
 
 Each item in `list` contains:

src/commands/portfolio.ts

@@ -17,11 +17,9 @@ export function registerPortfolioCommands(program: Command): void {
     .option("--order-by <field>", "Sort field: usd_value / last_active_timestamp / realized_profit / unrealized_profit / total_profit / history_bought_cost / history_sold_income", "usd_value")
     .option("--direction <dir>", "Sort direction: asc / desc", "desc")
     .option("--interval <interval>", "Stats interval (default 24h)")
-    .option("--sell-out", "Include sold-out positions")
-    .option("--show-small", "Include small-value positions")
-    .option("--hide-abnormal", "Hide abnormal positions")
-    .option("--hide-airdrop", "Hide airdrop positions")
-    .option("--hide-closed", "Hide closed positions")
+    .option("--hide-abnormal <bool>", "Hide abnormal positions (default: false)", "false")
+    .option("--hide-airdrop <bool>", "Hide airdrop positions (default: true)", "true")
+    .option("--hide-closed <bool>", "Hide closed positions (default: true)", "true")
     .option("--hide-open", "Hide open positions")
     .option("--tx30d", "Only show positions with trades in last 30 days")
     .option("--raw", "Output raw JSON")
@@ -34,11 +32,9 @@ export function registerPortfolioCommands(program: Command): void {
       if (opts.orderBy) extra["order_by"] = opts.orderBy;
       if (opts.direction) extra["direction"] = opts.direction;
       if (opts.interval) extra["interval"] = opts.interval;
-      if (opts.sellOut) extra["sell_out"] = "true";
-      if (opts.showSmall) extra["show_small"] = "true";
-      if (opts.hideAbnormal) extra["hide_abnormal"] = "true";
-      if (opts.hideAirdrop) extra["hide_airdrop"] = "true";
-      if (opts.hideClosed) extra["hide_closed"] = "true";
+      extra["hide_abnormal"] = opts.hideAbnormal;
+      extra["hide_airdrop"]  = opts.hideAirdrop;
+      extra["hide_closed"]   = opts.hideClosed;
       if (opts.hideOpen) extra["hide_open"] = "true";
       if (opts.tx30d) extra["tx30d"] = "true";