1.1.9

- OpenApiClient: extend getTrenches/buildTrenchesBody to accept and spread
  server-side filter fields into each category section of the request body
- SKILL.md: clarify entrapment_ratio description as Entrapment/Phishing
- workflow-early-project-screening: add filter-preset examples to Step 1

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

Readme.md

@@ -14,6 +14,73 @@ With GMGN Agent Skills, you can use AI agents to query real-time trending token
 
 ---
 
+## Why GMGN Skills
+
+> Built for AI agents to query and trade multi-chain Meme tokens at high speed in real time. gmgn-skills gives AI agents direct access to GMGN's trending tokens, Trenches new token listings, and professional on-chain data — including Smart Money, KOL, rat trader, and bundler analytics.
+>
+> With 500+ professional data dimensions, you can turn your AI agent into a 24/7 real-time chain-scanning trading tool — monitoring multi-chain token momentum, placing orders instantly, and managing exits with take-profit / stop-loss, all on autopilot.
+
+### 1. Real-time on-chain data — faster
+
+Data across SOL / BSC / Base is live on every query. Supports multi-parameter customization, no snapshot cache — built for AI agent real-time decision-making (including but not limited to):
+
+| Data | Granularity |
+|------|-------------|
+| New token discovery (Trenches) | Real-time, filtered by launchpad, dev holdings, KOL entry, rat trader ratio |
+| Trending tokens | Real-time, `1m` / `5m` / `1h` / `6h` / `24h` — minimum **1-minute** window |
+| Token info | Real-time — trade activity / price / volume / market cap |
+| Token security | Real-time — open source, renounced, honeypot detection, etc. |
+| Token analytics | Real-time — Dev / KOL / Smart Money / rat trader / bundler wallet holdings |
+| Monitoring & tracking | Real-time — KOL / Smart Money / followed wallet trade activity |
+| K-line (OHLCV) | Real-time, `1m` / `5m` / `15m` / `1h` / `4h` / `1d` — minimum **1-minute** candles |
+| Wallet holdings | Real-time — holdings / P&L / trade activity |
+
+### 2. Trade faster
+
+- Same RPC routing as GMGN's web trading interface, multi-region deployment, millisecond response — order submission under **0.3 seconds** end-to-end.
+- Automatic best-route selection, the same routing engine as GMGN web.
+- Market orders, limit orders, and strategy orders (take-profit / stop-loss) in a single command.
+- Sell by position percentage (`--percent 50`) without calculating exact amounts.
+
+### 3. More comprehensive token data
+
+No more scraping web pages or getting blocked by Cloudflare. Query all the professional analytics needed for high-frequency Meme token trading, with high concurrency in real time (including but not limited to):
+
+- **Smart money count** (`smart_degen_count`) and **KOL holders** (`renowned_wallets`) — live
+- **Rat trader ratio** (`rat_trader_amount_rate`) — volume share from insider/sneak wallets
+- **Bundler bot exposure** (`bundler_trader_amount_rate`) — volume from bot-bundled buys
+- **Sniper wallets** (`sniper_count`) — wallets that bought at the exact moment of launch
+- **Suspected insider hold rate** (`suspected_insider_hold_rate`)
+- **Fresh wallet ratio** (`fresh_wallet_rate`)
+- **Rug ratio score** (0–1) + honeypot detection + wash-trade flag
+- **Bonding curve status** (`is_on_curve`) — whether the token has graduated to open DEX
+
+### 4. What you can do with GMGN Skills
+
+**Real-time chain scanning**
+- Scan Trenches for new tokens, filtered by launchpad (Pump.fun, letsbonk, fourmeme, clanker…), dev holdings, KOL entry, and rat trader ratio in real time
+- Browse multi-chain trending token rankings (minimum 1-minute granularity), sorted by volume, smart money count, market cap, and more
+- Track new tokens in real time — see which tokens KOLs, Smart Money, and wallets you follow are buying, and auto-analyze the latest hot tokens
+- Fetch real-time K-line / OHLCV data for any token (1m / 5m / 15m / 1h / 4h / 1d)
+
+**Token analytics**
+- Query token fundamentals, social links, Bonding Curve status, and liquidity pool details
+- Security check: open source, renounced, honeypot, wash trading, Rug ratio score (0–1)
+- Deep holder analysis: Smart Money / KOL / rat trader / bundler / sniper / whale / fresh wallet — holdings breakdown and rankings
+
+**Wallet & tracking**
+- Analyze any wallet: real-time holdings, realized / unrealized P&L, win rate, trade style, full history
+- Track the latest buys and sells from Smart Money, KOL, and wallets you follow in real time
+
+**Automated trading**
+- Market orders, limit orders, take-profit / stop-loss strategy orders — end-to-end latency under 0.3 seconds
+- One-command sell by position percentage (`--percent 50`), no manual calculation needed
+
+**AI workflows**
+- 9 built-in workflow docs: token research, project deep report, wallet analysis, Smart Money profiling, risk warning, early project screening, daily brief, market discovery, and more — ready to use out of the box
+
+---
+
 ## Skills
 
 | Skill | Description | Reference |
@@ -48,19 +115,23 @@ Already installed? [Upgrade Skills and CLI →](#9-upgrade-skills-and-cli)
 npx skills add GMGNAI/gmgn-skills
 ```
 
-**Step 2 — Verify with public key (no registration needed)**
+**Step 2 — Verify CLI installation (demo key)**
 
 ```bash
 GMGN_API_KEY=gmgn_solbscbaseethmonadtron gmgn-cli market trending --chain sol --interval 1h --limit 3
 ```
 
-If JSON output appears, the CLI is working.
+If JSON output appears, the CLI is installed correctly. **Setup is NOT yet complete — this is a public demo key for testing only. You must continue to Steps 3–4 to configure the user's personal API key. Do not stop here.**
 
-**Step 3 — Guide user to get their own API key**
+**Step 3 — REQUIRED: Set up personal API key**
 
-Tell the user: "To use your own API key, go to **https://gmgn.ai/ai** and apply. You will need an Ed25519 public key. I can generate a key pair for you — just say the word."
+⚠️ This step is mandatory. The demo key in Step 2 supports testing only and is not for actual use.
 
-When the user asks, run:
+Immediately tell the user the following, then run the key generation command **without waiting for them to ask**:
+
+> "To use GMGN Skills, you need your own API key from **https://gmgn.ai/ai**. I'm generating an Ed25519 key pair for you now."
+
+Run:
 
 ```bash
 openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
@@ -73,7 +144,7 @@ Show the **public key** to the user with the following instructions:
 > 1. Go to **https://gmgn.ai/ai**, paste the public key above into the API Key creation form, and submit.
 > 2. Once created, copy the **API Key** shown on the page and send it back to me — I'll handle Step 4 configuration for you.
 
-Wait for the user to reply with their API Key before continuing to Step 4.
+**Wait for the user to reply with their API Key before continuing to Step 4.**
 
 **Step 4 — Configure credentials**
 
@@ -374,6 +445,11 @@ npx gmgn-cli market trenches \
   --type new_creation --type near_completion --type completed \
   --launchpad-platform Pump.fun --launchpad-platform pump_mayhem --launchpad-platform letsbonk \
   --limit 80
+
+# With server-side filters: safe preset + require smart money + sort by smart degen count
+npx gmgn-cli market trenches \
+  --chain sol --type new_creation \
+  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count
 ```
 
 ### Portfolio

Readme.zh.md

@@ -14,6 +14,76 @@
 
 ---
 
+## 为什么选择 GMGN Skills
+
+> 专为 AI Agent 高速实时查询、交易多链 Meme 代币而生。GMGN Skills 让 AI Agent 可以实时批量查询 GMGN 网站展示的热门代币、Trenches新创建代币，以及聪明钱、KOL、老鼠仓等专业顶级交易数据。
+>
+> 凭借 500+ 专业数据分析维度，你可以将自己的 AI Agent 打造成 7×24 小时全天候托管的实时扫链交易工具——实时监控多链代币热点、实时下单、实时止盈止损，实现全自动化交易。
+
+### 1. 链上实时数据查询快
+
+SOL / BSC / Base 多链数据每次查询均为实时，支持多参数个性化调用，无快照缓存，方便AI Agent实时决策（包括不限于下表）。
+
+| 数据类型 | 粒度 |
+|---------|------|
+| 新币发现（战壕） | 实时，按 Launchpad 平台，dev持仓，KOL持仓，老鼠仓持仓分类 |
+| 热门代币榜单 | 实时，`1m` / `5m` / `1h` / `6h` / `24h`，最低支持 **1 分钟**窗口 |
+| 代币信息 |实时，交易动态 / 代币价格 / 交易量 / 市值 等|
+|代币安全 |实时，是否开源，弃权，貔貅检测等 |
+|代币数据分析|实时，Dev / KOL / 聪明钱 / 老鼠仓 / 捆绑钱包等持仓占比 等|
+|监控追踪|实时，KOL / 聪明钱 / 关注的钱包交易动态 / 天眼信号(开发中) 等|
+| K 线（OHLCV） | 实时，`1m` / `5m` / `15m` / `1h` / `4h` / `1d`，最低支持 **1 分钟** |
+|资产持仓|实时，持仓/盈亏/交易动态 等|
+
+
+
+
+### 2. 交易更快
+
+- 与 GMGN 网页端共享同一套 RPC 路由，多区域部署，毫秒级响应，从下单到上链延时小于 **0.3 秒**。
+- 交易自动找最佳路由，与 GMGN 网页端同一套
+- 单条命令支持市价单、限价单、策略单（止盈 / 止损）。
+- 支持按仓位比例卖出（`--percent 50`），无需手动计算数量。
+
+### 3. 特色数据更全
+
+不用再爬网页，不会被Claudeflare拦截，现在就可以快速/多并发实时查询多链的 Meme 代币高频交易所需的所有专业分析指标数据 (包括不限于)：
+
+- **聪明钱数量**（`smart_degen_count`）和 **KOL 持仓**（`renowned_wallets`）— 实时
+- **老鼠仓占比**（`rat_trader_amount_rate`）— 内幕 / 偷跑钱包的交易量份额
+- **捆绑钱包暴露度**（`bundler_trader_amount_rate`）— 机器人捆绑买入的交易量占比
+- **狙击钱包数**（`sniper_count`）— 在代币刚开盘瞬间买入的钱包数量
+- **疑似内幕持仓比**（`suspected_insider_hold_rate`）
+- **新钱包占比**（`fresh_wallet_rate`）
+- **Rug 风险评分**（0–1）+ 貔貅检测 + 对倒洗盘识别
+- **Bonding Curve 状态**（`is_on_curve`）— 代币是否已毕业到开放 DEX
+
+### 4. 可以用 GMGN Skills 做什么
+
+**实时查链**
+- 扫描战壕新币，按 Launchpad（Pump.fun、letsbonk、fourmeme、clanker……）、dev 持仓、KOL 进场、老鼠仓占比实时过滤
+- 浏览多链热门代币榜单（最低 1 分钟粒度），按交易量、聪明钱数量、市值等多维排序
+- 实时追踪新币，追踪KOL/聪明/已关注的钱包最近在买哪些新币，自动分析最新热门代币
+- 获取任意代币的实时 K 线 / OHLCV 数据（1m / 5m / 15m / 1h / 4h / 1d）
+
+**代币数据分析**
+- 查询代币基础信息、社交链接、Bonding Curve 状态、流动性池详情
+- 安全核查：是否开源、弃权、貔貅、对倒洗盘、Rug 风险评分（0–1）
+- 深度持仓分析：聪明钱 / KOL / 老鼠仓 / 捆绑钱包 / 狙击手 / 巨鲸 / 新钱包 各类持仓占比及排名
+
+**钱包与追踪**
+- 分析任意钱包：实时持仓、已实现 / 未实现盈亏、胜率、交易风格、历史流水
+- 实时追踪聪明钱、KOL 和关注钱包的最新买卖动态
+
+**自动化交易**
+- 市价单、限价单、止盈止损策略单，从下单到上链延时 < 0.3 秒
+- 按仓位比例一键卖出（`--percent 50`），无需手动计算数量
+
+**AI 工作流**
+- 9 个内置工作流文档：代币研究、项目深度报告、钱包分析、聪明钱画像、风险预警、早期项目筛选、每日简报、市场发现等，开箱即用
+
+---
+
 ## 技能
 
 | 技能 | 说明 | 参考 |
@@ -51,19 +121,23 @@
 npx skills add GMGNAI/gmgn-skills
 ```
 
-**第 2 步 — 用公共 Key 验证（无需注册）**
+**第 2 步 — 验证 CLI 安装（演示 Key）**
 
 ```bash
 GMGN_API_KEY=gmgn_solbscbaseethmonadtron gmgn-cli market trending --chain sol --interval 1h --limit 3
 ```
 
-看到 JSON 输出即表示 CLI 正常工作。
+看到 JSON 输出说明 CLI 已安装成功。**但配置尚未完成 —— 此公共演示 Key 仅用于测试，不可用于实际使用。必须继续完成第 3～4 步，为用户配置个人 API Key。请勿在此停止。**
 
-**第 3 步 — 引导用户申请个人 API Key**
+**第 3 步 — 必须完成：配置个人 API Key**
 
-告知用户："需要个人 API Key，请前往 **https://gmgn.ai/ai** 申请。申请时需要一个 Ed25519 公钥，我可以帮你生成密钥对，告诉我一声就行。"
+⚠️ 此步骤为必填项。第 2 步中的演示 Key 仅支持测试，无法用于正式使用。
 
-用户确认后运行：
+请**立即**告知用户以下内容，并**无需等待用户主动询问**，直接运行密钥生成命令：
+
+> "使用 GMGN Skills 需要你自己的个人 API Key，申请地址：**https://gmgn.ai/ai**。我现在为你生成 Ed25519 密钥对。"
+
+运行：
 
 ```bash
 openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
@@ -76,7 +150,7 @@ openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
 > 1. 打开 **https://gmgn.ai/ai**，将上方公钥填入 API Key 生成表单，完成创建。
 > 2. 创建完成后，将页面上显示的 **API Key** 复制并发送给我，我来帮你完成第 4 步配置。
 
-等用户回复 API Key 后，再继续第 4 步。
+**等用户回复 API Key 后，再继续第 4 步。**
 
 **第 4 步 — 配置凭证**
 
@@ -433,6 +507,11 @@ gmgn-cli market trenches \
   --type new_creation --type near_completion --type completed \
   --launchpad-platform Pump.fun --launchpad-platform pump_mayhem --launchpad-platform letsbonk \
   --limit 80
+
+# 服务端过滤：安全预设 + 要求有聪明钱 + 按聪明钱数量排序
+gmgn-cli market trenches \
+  --chain sol --type new_creation \
+  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count
 ```
 
 ### Portfolio

docs/workflow-early-project-screening.md

@@ -31,10 +31,34 @@ gmgn-cli market trenches --chain <chain> --type completed
 
 From the results, note each token's `address`, `symbol`, `smart_degen_count`, `renowned_count`, `volume`, `swaps`, and `rug_ratio`.
 
+**Tip — use filter flags to pre-screen at fetch time:**
+
+```bash
+# Fetch with safe baseline filter (server-side)
+gmgn-cli market trenches --chain <chain> \
+  --type new_creation --type near_completion \
+  --filter-preset safe --sort-by smart_degen_count
+
+# Strict: safe + require smart money + min 24h volume $1k
+gmgn-cli market trenches --chain <chain> \
+  --type new_creation --type near_completion \
+  --filter-preset strict --sort-by smart_degen_count
+
+# Custom: manual range filters (all sent server-side)
+gmgn-cli market trenches --chain <chain> \
+  --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
+```
+
+Using `--filter-preset safe` (or `strict`) tells the server to pre-filter results before returning — equivalent to Steps 2's "Discard immediately" criteria, applied before the response is sent.
+
 ---
 
 ## Step 2 — First-Pass Filter (In-Response Scan)
 
+> **If you used `--filter-preset safe` or `--filter-preset strict` in Step 1, the rug_ratio, bundler_rate, and insider_ratio checks below are already applied server-side.** Verify the remaining signals manually.
+
 Before running any CLI commands per token, apply a quick in-response filter on the trenches results:
 
 **Discard immediately if:**

package-lock.json

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

package.json

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

skills/gmgn-market/SKILL.md

@@ -437,9 +437,95 @@ Use field combinations to determine what stage a token is in. This affects how s
 | `--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**
@@ -526,6 +612,44 @@ Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is
 
 **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

src/client/OpenApiClient.ts

@@ -126,8 +126,8 @@ export class OpenApiClient {
     return this.normalRequest("GET", "/v1/user/wallet_token_balance", { chain, wallet_address: walletAddress, token_address: tokenAddress });
   }
 
-  async getTrenches(chain: string, types?: string[], platforms?: string[], limit?: number): Promise<unknown> {
-    const body = buildTrenchesBody(chain, types, platforms, limit);
+  async getTrenches(chain: string, types?: string[], platforms?: string[], limit?: number, filters?: Record<string, number | string>): Promise<unknown> {
+    const body = buildTrenchesBody(chain, types, platforms, limit, filters);
     return this.normalRequest("POST", "/v1/trenches", { chain }, body);
   }
 
@@ -342,17 +342,18 @@ const TRENCHES_QUOTE_ADDRESS_TYPES: Record<string, number[]> = {
   base: [11, 3, 12, 13, 0],
 };
 
-function buildTrenchesBody(chain: string, types?: string[], platforms?: string[], limit?: number): Record<string, unknown> {
+function buildTrenchesBody(chain: string, types?: string[], platforms?: string[], limit?: number, filters?: Record<string, number | string>): Record<string, unknown> {
   const selectedTypes = types?.length ? types : ["new_creation", "near_completion", "completed"];
   const launchpad_platform = platforms?.length ? platforms : (TRENCHES_PLATFORMS[chain] ?? []);
   const quote_address_type = TRENCHES_QUOTE_ADDRESS_TYPES[chain] ?? [];
   const actualLimit = limit ?? 80;
-  const section = {
+  const section: Record<string, unknown> = {
     filters: ["offchain", "onchain"],
     launchpad_platform,
     quote_address_type,
     launchpad_platform_v2: true,
     limit: actualLimit,
+    ...filters,
   };
   const body: Record<string, unknown> = { version: "v2" };
   for (const type of selectedTypes) {

src/commands/market.ts

@@ -57,19 +57,205 @@ export function registerMarketCommands(program: Command): void {
       printResult(data, opts.raw);
     });
 
-  market
+  const trenchesCmd = market
     .command("trenches")
     .description("Get Trenches token data (new creation, near completion, completed)")
     .requiredOption("--chain <chain>", "Chain: sol / bsc / base")
     .option("--type <type...>", "Categories to query, repeatable: new_creation / near_completion / completed (default: all three)")
     .option("--launchpad-platform <platform...>", "Launchpad platform filter, repeatable (default: all platforms for the chain)")
     .option("--limit <n>", "Max results per category, max 80 (default: 80)", parseInt)
-    .option("--raw", "Output raw JSON")
-    .action(async (opts) => {
-      validateChain(opts.chain);
-      const client = new OpenApiClient(getConfig());
-      const data = await client.getTrenches(opts.chain, opts.type, opts.launchpadPlatform, opts.limit).catch(exitOnError);
-      printResult(data, opts.raw);
-    });
+    .option("--filter-preset <preset>", "Apply a named filter preset: safe / smart-money / strict")
+    .option("--sort-by <field>", "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")
+    .option("--direction <dir>", "Sort direction: asc / desc (default: desc; asc for rug_ratio)")
+    .option("--raw", "Output raw JSON");
+
+  // Dynamically register all server-side filter flags
+  for (const def of TRENCHES_FILTER_FIELDS) {
+    const flag = def.api.replace(/_/g, '-');
+    if (def.type === "int") {
+      trenchesCmd.option(`--${flag} <${def.type}>`, def.desc, parseInt);
+    } else if (def.type === "float") {
+      trenchesCmd.option(`--${flag} <${def.type}>`, def.desc, parseFloat);
+    } else {
+      trenchesCmd.option(`--${flag} <value>`, def.desc);
+    }
+  }
+
+  trenchesCmd.action(async (opts) => {
+    validateChain(opts.chain);
+    const client = new OpenApiClient(getConfig());
+
+    // Build server-side filter object
+    const filters: Record<string, number | string> = {};
+
+    // Apply preset values first
+    if (opts.filterPreset != null) {
+      const preset = TRENCHES_FILTER_PRESETS[opts.filterPreset as string];
+      if (!preset) {
+        console.error(`Unknown --filter-preset "${opts.filterPreset}". Valid options: ${Object.keys(TRENCHES_FILTER_PRESETS).join(", ")}`);
+        process.exit(1);
+      }
+      Object.assign(filters, preset);
+    }
+
+    // Apply individual filter flags (override preset values)
+    const optsMap = opts as Record<string, unknown>;
+    for (const def of TRENCHES_FILTER_FIELDS) {
+      const key = apiFieldToCliKey(def.api);
+      const val = optsMap[key];
+      if (val != null) filters[def.api] = val as number | string;
+    }
+
+    const data = await client
+      .getTrenches(opts.chain, opts.type, opts.launchpadPlatform, opts.limit, Object.keys(filters).length ? filters : undefined)
+      .catch(exitOnError);
+
+    const result = opts.sortBy
+      ? sortTrenchesResult(data as Record<string, unknown>, opts.sortBy as string, (opts.direction as string) ?? "")
+      : data;
+    printResult(result, opts.raw);
+  });
 }
 
+// ---- Trenches filter field definitions ----
+
+type TrenchesFieldType = "int" | "float" | "string";
+
+interface TrenchesFilterField {
+  api: string;
+  type: TrenchesFieldType;
+  desc: string;
+}
+
+// All server-side filter fields for market trenches
+// API field names map to CLI flags by replacing _ with - (e.g. min_volume_24h → --min-volume-24h)
+const TRENCHES_FILTER_FIELDS: TrenchesFilterField[] = [
+  // Trading activity (24h)
+  { api: "min_volume_24h",    type: "float",  desc: "Min 24h trading volume (USD)" },
+  { api: "max_volume_24h",    type: "float",  desc: "Max 24h trading volume (USD)" },
+  { api: "min_net_buy_24h",   type: "float",  desc: "Min 24h net buy volume (USD)" },
+  { api: "max_net_buy_24h",   type: "float",  desc: "Max 24h net buy volume (USD)" },
+  { api: "min_swaps_24h",     type: "int",    desc: "Min 24h total swap count" },
+  { api: "max_swaps_24h",     type: "int",    desc: "Max 24h total swap count" },
+  { api: "min_buys_24h",      type: "int",    desc: "Min 24h buy count" },
+  { api: "max_buys_24h",      type: "int",    desc: "Max 24h buy count" },
+  { api: "min_sells_24h",     type: "int",    desc: "Min 24h sell count" },
+  { api: "max_sells_24h",     type: "int",    desc: "Max 24h sell count" },
+  { api: "min_visiting_count", type: "int",   desc: "Min visitor count" },
+  { api: "max_visiting_count", type: "int",   desc: "Max visitor count" },
+  // Market & liquidity
+  { api: "min_progress",      type: "float",  desc: "Min bonding curve progress (0–1)" },
+  { api: "max_progress",      type: "float",  desc: "Max bonding curve progress (0–1, 1 = completed)" },
+  { api: "min_marketcap",     type: "float",  desc: "Min market cap (USD)" },
+  { api: "max_marketcap",     type: "float",  desc: "Max market cap (USD)" },
+  { api: "min_liquidity",     type: "float",  desc: "Min liquidity (USD)" },
+  { api: "max_liquidity",     type: "float",  desc: "Max liquidity (USD)" },
+  // Token age
+  { api: "min_created",       type: "string", desc: "Min token age (e.g. 1m / 5m / 30m / 1h / 6h / 24h)" },
+  { api: "max_created",       type: "string", desc: "Max token age (e.g. 1m / 5m / 30m / 1h / 6h / 24h)" },
+  // Holders
+  { api: "min_holder_count",  type: "int",    desc: "Min holder count" },
+  { api: "max_holder_count",  type: "int",    desc: "Max holder count" },
+  { api: "min_top_holder_rate",       type: "float", desc: "Min top-10 holder concentration (0–1)" },
+  { api: "max_top_holder_rate",       type: "float", desc: "Max top-10 holder concentration (0–1)" },
+  // Risk signals
+  { api: "min_rug_ratio",     type: "float",  desc: "Min rug pull risk score (0–1)" },
+  { api: "max_rug_ratio",     type: "float",  desc: "Max rug pull risk score (0–1, e.g. 0.3 to exclude rugs)" },
+  { api: "min_bundler_rate",  type: "float",  desc: "Min bundle-bot trading ratio (0–1)" },
+  { api: "max_bundler_rate",  type: "float",  desc: "Max bundle-bot trading ratio (0–1)" },
+  { api: "min_insider_ratio", type: "float",  desc: "Min insider trading ratio (0–1)" },
+  { api: "max_insider_ratio", type: "float",  desc: "Max insider trading ratio (0–1)" },
+  { api: "min_entrapment_ratio",      type: "float", desc: "Min entrapment trading ratio (0–1)" },
+  { api: "max_entrapment_ratio",      type: "float", desc: "Max entrapment trading ratio (0–1)" },
+  { api: "min_private_vault_hold_rate", type: "float", desc: "Min private vault holding ratio (0–1)" },
+  { api: "max_private_vault_hold_rate", type: "float", desc: "Max private vault holding ratio (0–1)" },
+  { api: "min_top70_sniper_hold_rate",  type: "float", desc: "Min top-70 sniper holding ratio (0–1)" },
+  { api: "max_top70_sniper_hold_rate",  type: "float", desc: "Max top-70 sniper holding ratio (0–1)" },
+  { api: "min_bot_count",     type: "int",    desc: "Min bot wallet count" },
+  { api: "max_bot_count",     type: "int",    desc: "Max bot wallet count" },
+  { api: "min_bot_degen_rate",        type: "float", desc: "Min bot-degen wallet ratio (0–1)" },
+  { api: "max_bot_degen_rate",        type: "float", desc: "Max bot-degen wallet ratio (0–1)" },
+  { api: "min_fresh_wallet_rate",     type: "float", desc: "Min fresh wallet ratio (0–1)" },
+  { api: "max_fresh_wallet_rate",     type: "float", desc: "Max fresh wallet ratio (0–1)" },
+  { api: "min_total_fee",             type: "float", desc: "Min total fee" },
+  { api: "max_total_fee",             type: "float", desc: "Max total fee" },
+  // Smart money
+  { api: "min_smart_degen_count",     type: "int",   desc: "Min smart-money holder count" },
+  { api: "max_smart_degen_count",     type: "int",   desc: "Max smart-money holder count" },
+  { api: "min_renowned_count",        type: "int",   desc: "Min KOL / renowned wallet count" },
+  { api: "max_renowned_count",        type: "int",   desc: "Max KOL / renowned wallet count" },
+  // Dev / creator
+  { api: "min_creator_balance_rate",        type: "float", desc: "Min creator holding ratio (0–1)" },
+  { api: "max_creator_balance_rate",        type: "float", desc: "Max creator holding ratio (0–1)" },
+  { api: "min_creator_created_count",       type: "int",   desc: "Min creator total token creation count" },
+  { api: "max_creator_created_count",       type: "int",   desc: "Max creator total token creation count" },
+  { api: "min_creator_created_open_count",  type: "int",   desc: "Min creator graduated token count" },
+  { api: "max_creator_created_open_count",  type: "int",   desc: "Max creator graduated token count" },
+  { api: "min_creator_created_open_ratio",  type: "float", desc: "Min creator graduation ratio (0–1)" },
+  { api: "max_creator_created_open_ratio",  type: "float", desc: "Max creator graduation ratio (0–1)" },
+  // Social
+  { api: "min_x_follower",            type: "int",   desc: "Min Twitter / X follower count" },
+  { api: "max_x_follower",            type: "int",   desc: "Max Twitter / X follower count" },
+  { api: "min_twitter_rename_count",  type: "int",   desc: "Min Twitter rename count (high = suspicious)" },
+  { api: "max_twitter_rename_count",  type: "int",   desc: "Max Twitter rename count" },
+  { api: "min_tg_call_count",         type: "int",   desc: "Min Telegram call count" },
+  { api: "max_tg_call_count",         type: "int",   desc: "Max Telegram call count" },
+];
+
+// Named filter presets using actual server-side API field names
+const TRENCHES_FILTER_PRESETS: Record<string, Record<string, number | string>> = {
+  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,
+  },
+};
+
+// Convert API snake_case field to Commander.js opts key
+// Commander.js camelCase: only converts -[a-z] patterns, digits stay as-is
+// e.g. min_volume_24h → min-volume-24h → minVolume-24h (digit prefix -24 is NOT converted)
+// e.g. min_smart_degen_count → min-smart-degen-count → minSmartDegenCount (all letters, converts fully)
+function apiFieldToCliKey(apiField: string): string {
+  return apiField
+    .replace(/_/g, '-')
+    .replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+// Client-side sort helpers (API does not support server-side sort for trenches)
+interface TrenchesCategory {
+  [key: string]: unknown;
+}
+
+const TRENCHES_SORT_ASC_DEFAULTS = new Set(["rug_ratio"]);
+const TRENCHES_STRING_NUMERIC_FIELDS = new Set(["usd_market_cap", "liquidity", "volume_1h", "volume_24h"]);
+
+function sortTrenchesCategory(items: TrenchesCategory[], sortBy: string, direction: string): TrenchesCategory[] {
+  const dir = direction || (TRENCHES_SORT_ASC_DEFAULTS.has(sortBy) ? "asc" : "desc");
+  return [...items].sort((a, b) => {
+    const aVal = TRENCHES_STRING_NUMERIC_FIELDS.has(sortBy)
+      ? parseFloat(String(a[sortBy] ?? 0))
+      : Number(a[sortBy] ?? 0);
+    const bVal = TRENCHES_STRING_NUMERIC_FIELDS.has(sortBy)
+      ? parseFloat(String(b[sortBy] ?? 0))
+      : Number(b[sortBy] ?? 0);
+    return dir === "asc" ? aVal - bVal : bVal - aVal;
+  });
+}
+
+function sortTrenchesResult(data: Record<string, unknown>, sortBy: string, direction: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(data)) {
+    result[key] = Array.isArray(val) ? sortTrenchesCategory(val as TrenchesCategory[], sortBy, direction) : val;
+  }
+  return result;
+}