gmgn-cli 1.1.6 → 1.1.9

package/skills/gmgn-swap/SKILL.md

@@ -2,26 +2,35 @@
 name: gmgn-swap
 description: "[FINANCIAL EXECUTION] Submit a real blockchain token swap or query order status. Executes irreversible on-chain transactions. Requires explicit user confirmation before every swap. Supports sol / bsc / base."
 argument-hint: "[--chain <chain> --from <wallet> --input-token <addr> --output-token <addr> --amount <n>] | [order get --chain <chain> --order-id <id>]"
+metadata:
+  cliHelp: "gmgn-cli swap --help"
 ---
 
 **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.**
+**IMPORTANT: Do NOT guess field names or values. When a field's meaning is unclear, look it up in the Response Fields sections below before using it.**
 
-## ⚠️ IPv6 Not Supported — CRITICAL
+**⚠️ IPv6 NOT SUPPORTED: If you get a `401` or `403` error and credentials look correct, check for IPv6 immediately: (1) list all network interfaces and their IPv6 addresses — run `ifconfig | grep inet6` (macOS) or `ip addr show | grep inet6` (Linux); (2) send a test request to `https://ipv6.icanhazip.com` — if the response is an IPv6 address, outbound traffic is going via IPv6. Tell the user immediately: "Please disable IPv6 on your network interface — gmgn-cli commands only work over IPv4."**
 
-**The `swap` sub-command does NOT support IPv6. Requests MUST 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`).
 
-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.
+## Core Concepts
 
-**How to diagnose:**
-```bash
-curl -s https://api64.ipify.org   # shows your outbound IP — if it's an IPv6 address, that's the problem
-```
+- **Smallest unit** — `--amount` is always in the token's smallest indivisible unit, not human-readable amounts. For SOL: 1 SOL = 1,000,000,000 lamports. For EVM tokens: depends on decimals (most ERC-20 tokens use 18 decimals). Always convert before passing to the command — do not pass human amounts directly.
 
-**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."
+- **`slippage`** — Price tolerance expressed as a decimal, not a percentage. `0.01` = 1% slippage. `0.5` = 50% slippage. If the price moves beyond this threshold before the transaction confirms, the swap is rejected. Use `--auto-slippage` for volatile tokens to let GMGN set an appropriate value automatically.
 
-Use the `gmgn-cli` tool to submit a token swap or query an existing order. **Requires private key** (`GMGN_PRIVATE_KEY` in `.env`).
+- **`--amount` vs `--percent`** — Mutually exclusive. `--amount` specifies an exact input quantity (in smallest unit). `--percent` sells a percentage of the current balance and is only valid when `input_token` is NOT a currency (SOL/BNB/ETH/USDC). Never use `--percent` to spend a fraction of SOL/BNB/ETH.
+
+- **Currency tokens** — Each chain has designated currency tokens (SOL, BNB, ETH, USDC). These are the base assets used to buy other tokens or receive swap proceeds. Their contract addresses are fixed — look them up in the Chain Currencies table, never guess them.
+
+- **Anti-MEV** — MEV (Miner/Maximal Extractable Value) refers to frontrunning and sandwich attacks where bots exploit pending transactions. `--anti-mev` routes the transaction through protected channels to reduce this risk. Enabled by default.
+
+- **Critical auth** — `swap` requires both `GMGN_API_KEY` and `GMGN_PRIVATE_KEY`. The private key never leaves the machine — the CLI uses it only for local signing and sends only the resulting signature. Normal commands (like `order quote`) use API Key alone.
+
+- **`order_id` / `status`** — After submitting a swap, the response includes an `order_id`. Use `order get --order-id` to poll for final status. Possible values: `pending` → `processed` → `confirmed` (success) or `failed` / `expired`. Do not report success until status is `confirmed`.
+
+- **`filled_input_amount` / `filled_output_amount`** — Actual amounts consumed/received, in smallest unit. Convert to human-readable using token decimals before displaying to the user.
 
 ## Financial Risk Notice
 
@@ -158,10 +167,10 @@ gmgn-cli order get --chain sol --order-id <order_id>
 | `--from` | Yes | Wallet address (must match API Key binding) |
 | `--input-token` | Yes | Input token contract address |
 | `--output-token` | Yes | Output token contract address |
-| `--amount` | No* | Input amount in smallest unit. Required unless `--percent` is used. |
-| `--percent <pct>` | No* | Sell percentage of `input_token`, e.g. `50` = 50%, `1` = 1%. Sets `input_amount` to `0` automatically. **Only valid when `input_token` is NOT a currency (SOL/BNB/ETH/USDC).** |
-| `--slippage <n>` | No | Slippage tolerance, e.g. `0.01` = 1% |
-| `--auto-slippage` | No | Enable automatic slippage |
+| `--amount` | No* | Input amount in smallest unit. **Mutually exclusive with `--percent`** — provide one or the other, never both. Required unless `--percent` is used. |
+| `--percent <pct>` | No* | Sell percentage of `input_token`, e.g. `50` = 50%, `1` = 1%. Sets `input_amount` to `0` automatically. **Mutually exclusive with `--amount`. Only valid when `input_token` is NOT a currency (SOL/BNB/ETH/USDC).** |
+| `--slippage <n>` | No | Slippage tolerance, e.g. `0.01` = 1%. **Mutually exclusive with `--auto-slippage`** — use one or the other. |
+| `--auto-slippage` | No | Enable automatic slippage. **Mutually exclusive with `--slippage`.** |
 | `--min-output <n>` | No | Minimum output amount |
 | `--anti-mev` | No | Enable anti-MEV protection (default true) |
 | `--priority-fee <sol>` | No | Priority fee in SOL (≥ 0.00001, SOL only) |
@@ -185,6 +194,60 @@ gmgn-cli order get --chain sol --order-id <order_id>
 | `filled_input_amount` | string | Actual input consumed (smallest unit); empty if not filled |
 | `filled_output_amount` | string | Actual output received (smallest unit); empty if not filled |
 
+## Output Format
+
+### Pre-swap Confirmation
+
+Before displaying the confirmation, run `order quote` to get the estimated output (uses normal auth — no private key required):
+
+```bash
+gmgn-cli order quote \
+  --chain <chain> \
+  --from <wallet> \
+  --input-token <input_token> \
+  --output-token <output_token> \
+  --amount <amount> \
+  --slippage <slippage>
+```
+
+Then display the confirmation summary using `output_amount` from the quote response:
+
+```
+⚠️ Swap Confirmation Required
+
+Chain:        {chain}
+Wallet:       {--from}
+Sell:         {input amount in human units} {input token symbol}
+Buy:          {output token symbol}
+Slippage:     {slippage}% (or "auto")
+Est. output:  ~{output_amount from quote} {output token symbol}
+Risk Level:   🟢 Low / 🟡 Medium / 🔴 High  (based on rug_ratio from security check)
+
+Reply "confirm" to proceed.
+```
+
+**Note**: `Risk Level` is derived from the required security check:
+- 🟢 Low: `rug_ratio < 0.1`
+- 🟡 Medium: `rug_ratio 0.1–0.3`
+- 🔴 High: `rug_ratio > 0.3` (requires re-confirmation)
+
+If the user explicitly skipped the security check, omit the Risk Level line and add a note: "(Security check skipped by user)"
+
+### Post-swap Receipt
+
+After a confirmed swap, display:
+
+```
+✅ Swap Confirmed
+
+Spent:    {filled_input_amount in human units} {input symbol}
+Received: {filled_output_amount in human units} {output symbol}
+Tx:       {explorer link for hash}
+Order ID: {order_id}
+```
+
+Convert `filled_input_amount` and `filled_output_amount` from smallest unit using token decimals before displaying.
+
 ## Notes
 
 - Swap uses **critical auth** (API Key + signature) — CLI handles signing automatically, no manual processing needed
@@ -209,22 +272,27 @@ 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)
+## Pre-Swap Safety Check (REQUIRED)
 
-Before swapping into an unknown token, verify it is not a honeypot or rug pull:
+Before swapping into any token, run a mandatory security check using `gmgn-cli`:
 
 ```bash
-curl -s "https://app.maiat.io/api/v1/token/<output_token_address>" | jq '{trustScore: .trustScore, verdict: .verdict, riskFlags: .riskFlags}'
+gmgn-cli token security --chain <chain> --address <output_token>
 ```
 
-- 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.
+Check the two critical fields:
+- **`is_honeypot`**: If `"yes"` → **abort immediately**. Display: "🚫 HONEYPOT DETECTED — swap aborted." Do NOT proceed.
+- **`rug_ratio`**: If `> 0.3` → display 🔴 High Risk warning and require explicit re-confirmation from the user before proceeding.
+
+**User override**: The user may explicitly skip this check by saying "I already checked" or "skip security check". In that case, document that the check was skipped in the confirmation summary. This is the only valid override — do NOT skip the check silently.
+
+For a quick pre-swap due diligence checklist (info + security + pool + smart money, 4 steps), see [`docs/workflow-token-due-diligence.md`](../../docs/workflow-token-due-diligence.md)
 
-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.
+For full token research before swapping, see [`docs/workflow-token-research.md`](../../docs/workflow-token-research.md)
 
 ## Execution Guidelines
 
+- **[REQUIRED] Token security check** — Run before every swap. See **Pre-Swap Safety Check (REQUIRED)** section above. Uses normal auth (API Key only — no private key needed for this step).
 - **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.
   - Buy ("buy X SOL of TOKEN", "spend 0.5 USDC on TOKEN") → resolve currency to `--input-token`
   - Sell ("sell TOKEN for SOL", "sell 50% of TOKEN to USDC") → resolve currency to `--output-token`

package/skills/gmgn-token/SKILL.md

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