gmgn-cli 1.0.1 → 1.1.0

package/skills/gmgn-market/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: gmgn-market
-description: Query GMGN market data — token K-line (candlestick) and trending token swap data. 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 <1h|3h|6h|24h>"
+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>"
 ---
 
-Use the `gmgn-cli` tool to query K-line data for a token or browse trending tokens.
+Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens, or view Trenches token lists.
 
 ## Sub-commands
 
@@ -12,6 +12,7 @@ Use the `gmgn-cli` tool to query K-line data for a token or browse trending toke
 |-------------|-------------|
 | `market kline` | Token candlestick data |
 | `market trending` | Trending token swap data |
+| `market trenches` | Trenches token lists (new creation, near completion, completed) |
 
 ## Supported Chains
 
@@ -21,7 +22,7 @@ Use the `gmgn-cli` tool to query K-line data for a token or browse trending toke
 
 - `.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.0.1`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
 
 ## Kline Parameters
 
@@ -42,12 +43,12 @@ Use the `gmgn-cli` tool to query K-line data for a token or browse trending toke
 | Option | Description |
 |--------|-------------|
 | `--chain` | Required. `sol` / `bsc` / `base` |
-| `--interval` | Required. `1h` / `3h` / `6h` / `24h` |
+| `--interval` | Required. `1m` / `5m` / `1h` / `6h` / `24h` (default `1h`) |
 | `--limit <n>` | Number of results (default 100, max 100) |
-| `--orderby <field>` | Sort field: `score` / `volume` / `swaps` / `liquidity` / `marketcap` / `holders` / `price` / `change` / `change1m` / `change5m` / `change1h` / `renowned_count` / `smart_degen_count` / `bluechip_owner_percentage` / `rank` / `creation_timestamp` / `square_mentions` / `history_highest_market_cap` / `gas_fee` |
+| `--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: `has_social` / `not_risk` / `not_honeypot` / `verified` / `locked` / `renounced` / `distributed` / `frozen` / `burn` / `token_burnt` / `creator_hold` / `creator_close` / `creator_add_liquidity` / `creator_remove_liquidity` / `creator_sell` / `creator_buy` / `not_wash_trading` / `not_social_dup` / `not_image_dup` / `is_internal_market` / `is_out_market` |
-| `--platform <name...>` | Repeatable platform filter: `pump` / `moonshot` / `launchlab` |
+| `--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` |
+| `--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
 
@@ -73,15 +74,15 @@ gmgn-cli market kline \
 # Linux: use $(date -d '24 hours ago' +%s) instead of $(date -v-24H +%s)
 
 # Top 20 hot tokens on SOL in the last 1 hour, sorted by volume
-gmgn-cli market trending --chain sol --interval 1h --orderby volume --limit 20
+gmgn-cli market trending --chain sol --interval 1h --order-by volume --limit 20
 
-# Hot tokens with social links only, not risky, on BSC over 24h
+# Hot tokens with social links only, verified and not honeypot, on BSC over 24h
 gmgn-cli market trending \
   --chain bsc --interval 24h \
-  --filter has_social --filter not_risk
+  --filter has_social --filter not_honeypot --filter verified
 
-# Pump platform tokens on SOL, last 6 hours
-gmgn-cli market trending --chain sol --interval 6h --platform pump
+# Pump.fun platform tokens on SOL, last 6 hours
+gmgn-cli market trending --chain sol --interval 6h --platform Pump.fun
 
 # Raw output for further processing
 gmgn-cli market kline --chain sol --address <addr> \
@@ -92,13 +93,13 @@ gmgn-cli market kline --chain sol --address <addr> \
 
 ### Step 1 — Fetch trending data
 
-Fetch a broad pool with safe filters, sorted by GMGN's composite score:
+Fetch a broad pool with safe filters:
 
 ```bash
 gmgn-cli market trending \
   --chain <chain> --interval 1h \
-  --orderby score --limit 50 \
-  --filter not_risk --filter not_honeypot --filter has_social --raw
+  --order-by volume --limit 50 \
+  --filter not_honeypot --filter has_social --raw
 ```
 
 ### Step 2 — AI multi-factor analysis
@@ -107,7 +108,6 @@ Analyze each record in the response using the following signals (apply judgment,
 
 | Signal | Field(s) | Weight | Notes |
 |--------|----------|--------|-------|
-| GMGN quality score | `score` | High | Primary ranking signal from GMGN |
 | 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 |
@@ -115,7 +115,7 @@ Analyze each record in the response using the following signals (apply judgment,
 | 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 |
 
-Select the **top 5** tokens with the best composite profile. Prefer tokens that score well across multiple signals rather than excelling in just one.
+Select the **top 5** tokens with the best composite profile. Prefer tokens that perform well across multiple signals rather than excelling in just one.
 
 ### Step 3 — Present top 5 to user
 
@@ -124,8 +124,8 @@ Present results as a concise table, then give a one-line rationale for each pick
 ```
 Top 5 Trending Tokens — SOL / 1h
 
-# | Symbol | Address (short) | Score | Smart Degens | Volume | 1h Chg | Reasoning
-1 | ...     | ...             | ...   | ...          | ...    | ...    | High score + smart money accumulating
+# | Symbol | Address (short) | Smart Degens | Volume | 1h Chg | Reasoning
+1 | ...     | ...             | ...          | ...    | ...    | Smart money accumulating + high volume
 2 | ...
 ...
 ```
@@ -136,6 +136,19 @@ 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
 
+## Trenches Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` / `base` |
+
+Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is an array of `RankItem` (same fields as `market trending` rank items).
+
+```bash
+# Trenches token lists on SOL
+gmgn-cli market trenches --chain sol --raw
+```
+
 ## Notes
 
 - `market kline`: `--from` and `--to` are Unix timestamps in **seconds** — CLI converts to milliseconds automatically

package/skills/gmgn-portfolio/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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>]"
+description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, token balance, follow-wallet trades, KOL trades, and Smart Money trades. Supports sol / bsc / base.
+argument-hint: "<info|holdings|activity|stats|token-balance|follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
 ---
 
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
@@ -15,6 +15,9 @@ Use the `gmgn-cli` tool to query wallet portfolio data based on the user's reque
 | `portfolio activity` | Transaction history |
 | `portfolio stats` | Trading statistics (supports batch) |
 | `portfolio token-balance` | Token balance for a specific token |
+| `portfolio follow-wallet` | Follow-wallet trade records |
+| `portfolio kol` | KOL trade records (SOL chain) |
+| `portfolio smartmoney` | Smart Money trade records (SOL chain) |
 
 ## Supported Chains
 
@@ -24,7 +27,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.0.1`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
 
 ## Usage Examples
 
@@ -75,7 +78,7 @@ gmgn-cli portfolio token-balance \
 |--------|-------------|
 | `--limit <n>` | Page size (default `20`, max 50) |
 | `--cursor <cursor>` | Pagination cursor |
-| `--order-by <field>` | Sort field: `usd_value` / `price` / `unrealized_profit` / `realized_profit` / `total_profit` / `history_bought_cost` / `history_sold_income` (default `usd_value`) |
+| `--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 |
@@ -90,15 +93,57 @@ gmgn-cli portfolio token-balance \
 |--------|-------------|
 | `--token <address>` | Filter by token |
 | `--limit <n>` | Page size |
-| `--cursor <cursor>` | Pagination cursor |
+| `--cursor <cursor>` | Pagination cursor (pass the `next` value from the previous response) |
 | `--type <type>` | Repeatable: `buy` / `sell` / `add` / `remove` / `transfer` |
 
+The activity response includes a `next` field. Pass it to `--cursor` to fetch the next page.
+
 ## Stats Options
 
 | Option | Description |
 |--------|-------------|
 | `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |
 
+## Follow-Wallet Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required. `sol` / `bsc` / `base` / `eth` |
+| `--wallet <address>` | Filter by wallet address |
+| `--base-token <address>` | Filter by base token address |
+| `--page-token <cursor>` | Pagination cursor |
+| `--limit <n>` | Page size (1–200, default 100) |
+| `--side <side>` | Trade direction filter |
+| `--cost <cost>` | Cost filter |
+| `--filter <tag...>` | Repeatable filter conditions |
+| `--with-balance` | Include balance in response |
+| `--with-security` | Include security info in response |
+| `--min-amount-usd <n>` | Minimum trade amount (USD) |
+| `--max-amount-usd <n>` | Maximum trade amount (USD) |
+| `--is-gray` | Gray mode filter |
+
+## KOL / Smart Money Options
+
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Page size (1–200, default 100) |
+
+Both `kol` and `smartmoney` return SOL chain data only — no `--chain` flag needed.
+
+```bash
+# Follow-wallet trades filtered by wallet
+gmgn-cli portfolio follow-wallet --chain sol --wallet <wallet_address>
+
+# Follow-wallet with balance info
+gmgn-cli portfolio follow-wallet --chain sol --with-balance --limit 20
+
+# KOL trade records
+gmgn-cli portfolio kol --limit 10 --raw
+
+# Smart Money trade records
+gmgn-cli portfolio smartmoney --limit 10 --raw
+```
+
 ## Notes
 
 - All portfolio commands use normal auth (API Key only, no signature required)

package/skills/gmgn-swap/SKILL.md

@@ -20,6 +20,7 @@ Use the `gmgn-cli` tool to submit a token swap or query an existing order. **Req
 | Sub-command | Description |
 |-------------|-------------|
 | `swap` | Submit a token swap |
+| `order quote` | Get a swap quote (no transaction submitted) |
 | `order get` | Query order status |
 
 ## Supported Chains
@@ -45,7 +46,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.0.1
+npm install -g gmgn-cli@1.1.0
 ```
 
 ### Credential Model
@@ -92,6 +93,31 @@ gmgn-cli swap \
   --percent 50
 ```
 
+## Quote Usage
+
+Get an estimated output amount before submitting a swap. Uses normal auth — no private key required.
+
+```bash
+gmgn-cli order quote \
+  --chain sol \
+  --from <wallet_address> \
+  --input-token <input_token_address> \
+  --output-token <output_token_address> \
+  --amount <input_amount_smallest_unit> \
+  --slippage 0.01
+```
+
+### Quote Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `input_token` | string | Input token contract address |
+| `output_token` | string | Output token contract address |
+| `input_amount` | string | Input amount (smallest unit) |
+| `output_amount` | string | Expected output amount (smallest unit) |
+| `min_output_amount` | string | Minimum output after slippage |
+| `slippage` | number | Actual slippage percentage |
+
 ## Order Query
 
 ```bash
@@ -124,13 +150,9 @@ gmgn-cli order get --chain sol --order-id <order_id>
 |-------|------|-------------|
 | `order_id` | string | Order ID for follow-up queries |
 | `hash` | string | Transaction hash |
-| `state` | int | Order state code |
-| `confirmation.state` | string | `processed` / `confirmed` / `failed` / `expired` |
-| `confirmation.detail` | string | Confirmation detail message |
+| `status` | string | Order status: `pending` / `processed` / `confirmed` / `failed` / `expired` |
 | `error_code` | string | Error code on failure |
 | `error_status` | string | Error description on failure |
-| `height` | number | Block height of the transaction |
-| `order_height` | number | Block height when the order was placed |
 | `input_token` | string | Input token contract address |
 | `output_token` | string | Output token contract address |
 | `filled_input_amount` | string | Actual input consumed (smallest unit); empty if not filled |
@@ -160,6 +182,20 @@ Before passing any address or amount to a command:
 
 4. **User confirmation** — See "Execution Guidelines" below — always present resolved parameters to the user before executing a swap. This creates a human review checkpoint for any unexpected values.
 
+## Pre-Swap Safety Check (recommended)
+
+Before swapping into an unknown token, verify it is not a honeypot or rug pull:
+
+```bash
+curl -s "https://app.maiat.io/api/v1/token/<output_token_address>" | jq '{trustScore: .trustScore, verdict: .verdict, riskFlags: .riskFlags}'
+```
+
+- If `verdict` is `"avoid"` → **do NOT proceed** with the swap.
+- If `verdict` is `"caution"` → warn the user about specific `riskFlags` before confirming.
+- If `verdict` is `"proceed"` or `"trusted"` → safe to continue.
+
+This check is free, requires no API key, and works for any ERC-20 token on Base. Powered by [Maiat](https://app.maiat.io) — trust infrastructure for on-chain agents.
+
 ## Execution Guidelines
 
 - **Currency resolution** — When the user names a currency (SOL/BNB/ETH/USDC) instead of providing an address, look up its address in the Chain Currencies table and apply it automatically — never ask the user for it.
@@ -169,7 +205,7 @@ Before passing any address or amount to a command:
 - **Percentage sell restriction** — `--percent` is ONLY valid when `input_token` is NOT a currency. Do NOT use `--percent` when `input_token` is SOL/BNB/ETH (native) or USDC. This includes: "sell 50% of my SOL", "use 30% of my BNB to buy X", "spend 50% of my USDC on X" — all unsupported. Explain the restriction to the user and ask for an explicit absolute amount instead.
 - **Chain-wallet compatibility** — SOL addresses are incompatible with EVM chains (bsc/base). Warn the user and abort if the address format does not match the chain.
 - **Credential sensitivity** — `GMGN_API_KEY` and `GMGN_PRIVATE_KEY` can directly execute trades on the linked wallet. Never log, display, or expose these values.
-- **Order polling** — After a swap, if `confirmation.state` is not yet `confirmed` / `failed` / `expired`, poll with `order get` up to 3 times at 5-second intervals before reporting a timeout. Once confirmed, display the trade result using `filled_input_amount` and `filled_output_amount` (convert from smallest unit using token decimals), e.g. "Spent 0.1 SOL → received 98.5 USDC" or "Sold 1000 TOKEN → received 0.08 SOL".
+- **Order polling** — After a swap, if `status` is not yet `confirmed` / `failed` / `expired`, poll with `order get` up to 3 times at 5-second intervals before reporting a timeout. Once confirmed, display the trade result using `filled_input_amount` and `filled_output_amount` (convert from smallest unit using token decimals), e.g. "Spent 0.1 SOL → received 98.5 USDC" or "Sold 1000 TOKEN → received 0.08 SOL".
 - **Block explorer links** — After a successful swap, display a clickable explorer link for the returned `hash`:
 
   | Chain | Explorer |

package/skills/gmgn-token/SKILL.md

@@ -24,7 +24,25 @@ 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.0.1`
+- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
+
+## Info / Security / Pool Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required. `sol` / `bsc` / `base` |
+| `--address` | Required. Token contract address |
+
+## Holders / Traders Options
+
+| Option | Description |
+|--------|-------------|
+| `--chain` | Required. `sol` / `bsc` / `base` |
+| `--address` | Required. Token contract address |
+| `--limit <n>` | Number of results (default `20`, max `100`) |
+| `--order-by <field>` | Sort field: `amount_percentage` / `profit` / `unrealized_profit` / `buy_volume_cur` / `sell_volume_cur` (default `amount_percentage`) |
+| `--direction <asc\|desc>` | Sort direction (default `desc`) |
+| `--tag <tag>` | Wallet tag filter: `renowned` / `smart_degen` (default `renowned`) |
 
 ## Usage Examples
 
@@ -39,11 +57,9 @@ gmgn-cli token security --chain sol --address <token_address>
 gmgn-cli token pool --chain sol --address <token_address>
 
 # Top holders
-gmgn-cli token holders --chain sol --address <token_address>
 gmgn-cli token holders --chain sol --address <token_address> --limit 50
 
 # Top traders
-gmgn-cli token traders --chain sol --address <token_address>
 gmgn-cli token traders --chain sol --address <token_address> --limit 50
 
 # Raw JSON output (for piping)