gmgn-cli 1.1.6 → 1.1.8

package/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 |
@@ -28,14 +95,96 @@ With GMGN Agent Skills, you can use AI agents to query real-time trending token
 
 ### Quick Start
 
-Ready to install skills? [Jump to Installation →](#get-started)
+> **Note for AI assistants:** If you are an AI Agent helping the user install or configure gmgn-cli, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent) — it contains all the steps you need to complete, including how to guide the user through API key generation. If the user asks to upgrade, jump to [Upgrade (AI Agent)](#upgrade-ai-agent).
+
+Ready to install? [Jump to Installation →](#1-installation)
+
+Already installed? [Upgrade 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.`
+
+---
+
+## Quick Start (AI Agent)
+
+> The following steps are for AI Agents. Some steps require the user to complete actions in a browser.
+
+**Step 1 — Install CLI and Skills**
+
+```bash
+npx skills add GMGNAI/gmgn-skills
+```
+
+**Step 2 — Verify with public key (no registration needed)**
+
+```bash
+GMGN_API_KEY=gmgn_solbscbaseethmonadtron gmgn-cli market trending --chain sol --interval 1h --limit 3
+```
+
+If JSON output appears, the CLI is working.
+
+**Step 3 — Guide user to get their own 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."
+
+When the user asks, run:
+
+```bash
+openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+  openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+```
+
+Show the **public key** to the user with the following instructions:
+
+> This is your Ed25519 public key. Please complete these two steps:
+> 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.
+
+**Step 4 — Configure credentials**
+
+After the user receives their API key, write it to the global config:
+
+```bash
+mkdir -p ~/.config/gmgn
+# Write API key (replace with the actual key the user provides)
+echo 'GMGN_API_KEY=<user_api_key>' > ~/.config/gmgn/.env
+chmod 600 ~/.config/gmgn/.env
+```
+
+If the user also needs swap capability, append the private key:
 
-Already installed? [Update Skills and CLI →](#9-upgrade-skills-and-cli)
+```bash
+# Append private key (use the PEM content from Step 3)
+echo 'GMGN_PRIVATE_KEY="<pem_content>"' >> ~/.config/gmgn/.env
+```
+
+**Step 5 — Verify**
+
+```bash
+gmgn-cli market trending --chain sol --interval 1h --limit 3
+```
+
+If output appears without error, setup is complete.
+
+---
+
+## Upgrade (AI Agent)
+
+> Run this command to upgrade both the CLI and Skills to the latest version.
+
+```bash
+npx skills add GMGNAI/gmgn-skills
+```
+
+Check the installed version after upgrading:
+
+```bash
+gmgn-cli --version
+```
 
-> **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.
-> ```
+> For the full upgrade reference, see [Section 9 — Upgrade Skills and CLI](#9-upgrade-skills-and-cli).
 
 ---
 
@@ -64,17 +213,10 @@ Check the first token's K-line, analyze entry timing, plot price + volume chart,
 
 ---
 
-## Get Started
-
-Before installing, create your API Key at **https://gmgn.ai/ai**. The API key is used for:
-
-1. Read data: tokens, trending lists, K-line, and featured on-chain metrics
-2. Submit trades: market orders, limit orders, strategy orders, and more
-
----
-
 ## 1. Installation
 
+> **Prerequisites:** Before installing, create your API Key at **https://gmgn.ai/ai** (see [Section 3](#3-get-your-own-api-key) for the full setup guide).
+
 Choose one of the following methods:
 
 ### 1.1 Via Agent (recommended)
@@ -101,23 +243,15 @@ node dist/index.js <command> [options]
 
 ## 2. Verify Connection
 
-### Option 1: Via AI Agent
-
-Send this prompt to your AI Agent:
-
-```
-Run this CLI command: GMGN_API_KEY=gmgn_solbscbaseethmonadtron npx gmgn-cli market trending --chain sol --interval 1h --limit 3
-```
-
-### Option 2: Via CLI
-
 Test with the public API key — no registration required:
 
 ```bash
 GMGN_API_KEY=gmgn_solbscbaseethmonadtron gmgn-cli market trending --chain sol --interval 1h --limit 3
 ```
 
-If you see JSON output, the CLI is working. The public key supports all read-only commands (token / market / portfolio). The public key is for testing only — apply for your own API key to use any feature (see step 3).
+If you see JSON output, the CLI is working. The public key supports all read-only commands (token / market / portfolio) and is for testing only — apply for your own API key to use any feature (see step 3).
+
+> **Troubleshooting — 401 / 403 errors:** If the command fails with `401` or `403` and credentials look correct, your outbound traffic may be going via IPv6 (not supported). Check immediately: (1) run `ifconfig | grep inet6` (macOS) or `ip addr show | grep inet6` (Linux) to list all network interfaces and their IPv6 addresses; (2) run `curl -s https://ipv6.icanhazip.com` — if it returns an IPv6 address, your traffic is going via IPv6. **Disable IPv6 on your network interface — gmgn-cli commands only work over IPv4.**
 
 ## 3. Get Your Own API Key
 
@@ -267,7 +401,23 @@ market trending (top 50)  →  AI selects top 5 by multi-factor analysis  →  u
 
 ---
 
-## 7. CLI Reference
+## 7. Workflow Docs
+
+Step-by-step guides for common analysis tasks:
+
+| Workflow | When to use |
+|----------|-------------|
+| [workflow-token-research.md](docs/workflow-token-research.md) | Pre-buy token due diligence (address → buy/watch/skip) |
+| [workflow-project-deep-report.md](docs/workflow-project-deep-report.md) | Comprehensive project analysis with scored dimensions and full written report |
+| [workflow-wallet-analysis.md](docs/workflow-wallet-analysis.md) | Wallet quality assessment (address → follow/skip) |
+| [workflow-smart-money-profile.md](docs/workflow-smart-money-profile.md) | Trading style analysis, copy-trade ROI estimate, smart money leaderboard |
+| [workflow-risk-warning.md](docs/workflow-risk-warning.md) | Active risk monitoring for held positions (whale exit, liquidity, dev dump) |
+| [workflow-early-project-screening.md](docs/workflow-early-project-screening.md) | Screen newly launched launchpad tokens for smart money entry |
+| [workflow-daily-brief.md](docs/workflow-daily-brief.md) | Daily market overview: trending + smart money moves + early watch + risk scan |
+| [workflow-market-opportunities.md](docs/workflow-market-opportunities.md) | Discover trading opportunities from trending data |
+| [workflow-token-due-diligence.md](docs/workflow-token-due-diligence.md) | 4-step token due diligence checklist |
+
+## 8. CLI Reference
 
 Full parameter reference: [docs/cli-usage.md](docs/cli-usage.md). All commands support `--raw` for single-line JSON output (pipe-friendly, e.g. `| jq '.price'`).
 
@@ -351,37 +501,21 @@ npx gmgn-cli order get --chain sol --order-id <order-id>
 
 ## 9. Upgrade Skills and CLI
 
-To upgrade `gmgn-cli` and Skills to the latest version:
-
-**Via AI Agent (recommended)**
-
-Send this to your AI agent:
-
-```
-Run these two commands to update gmgn-cli and the skills:
-1. npm install -g gmgn-cli
-2. npx skills add GMGNAI/gmgn-skills
-```
-
-**Via CLI**
-
 ```bash
-# Upgrade gmgn-cli
-npm install -g gmgn-cli
-
-# Upgrade Skills
+# Upgrade CLI and Skills
 npx skills add GMGNAI/gmgn-skills
-```
-
-**Check the current version**
 
-```bash
+# Check current version
 gmgn-cli --version
 ```
 
+> **Via AI Agent:** Tell your agent — "Upgrade gmgn-cli and the skills to the latest version." See also [Upgrade (AI Agent)](#upgrade-ai-agent).
+
 ---
 
-## 10. Security & Disclaimer
+## 10. Security & Disclaimer (Read Before Use)
+
+This tool can be invoked by an AI Agent to submit real on-chain transactions automatically. It carries inherent risks including model hallucination, uncontrolled execution, and prompt injection. Once authorized, the AI Agent will submit transactions on behalf of your linked wallet address — **on-chain transactions are irreversible once confirmed** and may result in financial loss. Use with caution.
 
 **About `GMGN_PRIVATE_KEY`**
 
@@ -392,11 +526,13 @@ gmgn-cli --version
 - Restrict config file permissions: `chmod 600 ~/.config/gmgn/.env`
 - Never commit your `.env` file to version control — add it to `.gitignore`
 - Do not share `GMGN_API_KEY` or `GMGN_PRIVATE_KEY` in logs, screenshots, or chat messages
+- Before every swap, carefully review the trade summary presented by the AI (chain, wallet, token addresses, amount) and confirm only when it matches your intent
+- Test with small amounts first before executing larger trades
 - Always use the latest version of gmgn-cli (`npm install -g gmgn-cli`). To check your current version: `gmgn-cli --version`
 
 **Disclaimer**
 
-Use of this tool and any financial decisions made based on its output are entirely at your own risk. GMGN is not liable for any trading losses, errors, or unauthorized access resulting from improper credential management.
+Use of this tool and any financial decisions made based on its output are entirely at your own risk. GMGN is not liable for any trading losses, errors, or unauthorized access resulting from model hallucination, prompt injection, improper credential management, or user confirmation errors. By using this tool, you acknowledge that you have fully understood the above risks and voluntarily accept all responsibility.
 
 The npm package is published with provenance attestation, linking each release to a specific git commit and CI pipeline run. Verify with:
 ```bash

package/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 个内置工作流文档：代币研究、项目深度报告、钱包分析、聪明钱画像、风险预警、早期项目筛选、每日简报、市场发现等，开箱即用
+
+---
+
 ## 技能
 
 | 技能 | 说明 | 参考 |
@@ -28,8 +98,12 @@
 
 ### 快速开始安装
 
+> **AI Agent 注意：** 如果你是正在协助用户安装或配置 gmgn-cli 的 AI Agent，请直接跳转到 [AI Agent 快速开始](#ai-agent-快速开始) — 其中包含你需要完成的所有步骤，包括如何引导用户完成 API Key 申请。如果用户要求升级，请跳转到 [AI Agent 升级](#ai-agent-升级)。
+
 已准备好？[点击这里开始安装 Skills →](#开始安装-skills)
 
+已安装？[升级 Skills 和 CLI →](#9-升级-skills-和-cli)
+
 > **提示：** 如果你的 AI Agent 尝试直接打开 gmgn.ai 网站而不是使用 CLI，请在提示词中加上：
 > ```
 > 用 gmgn-cli 命令，不要直接请求gmgn.ai网页接口。
@@ -37,6 +111,89 @@
 
 ---
 
+## AI Agent 快速开始
+
+> 以下步骤面向 AI Agent。部分步骤需要用户在浏览器中配合完成。
+
+**第 1 步 — 安装 CLI 和 Skills**
+
+```bash
+npx skills add GMGNAI/gmgn-skills
+```
+
+**第 2 步 — 用公共 Key 验证（无需注册）**
+
+```bash
+GMGN_API_KEY=gmgn_solbscbaseethmonadtron gmgn-cli market trending --chain sol --interval 1h --limit 3
+```
+
+看到 JSON 输出即表示 CLI 正常工作。
+
+**第 3 步 — 引导用户申请个人 API Key**
+
+告知用户："需要个人 API Key，请前往 **https://gmgn.ai/ai** 申请。申请时需要一个 Ed25519 公钥，我可以帮你生成密钥对，告诉我一声就行。"
+
+用户确认后运行：
+
+```bash
+openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+  openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+```
+
+将**公钥**展示给用户，并附上以下说明：
+
+> 以上是你的 Ed25519 公钥。接下来请你完成以下两步：
+> 1. 打开 **https://gmgn.ai/ai**，将上方公钥填入 API Key 生成表单，完成创建。
+> 2. 创建完成后，将页面上显示的 **API Key** 复制并发送给我，我来帮你完成第 4 步配置。
+
+等用户回复 API Key 后，再继续第 4 步。
+
+**第 4 步 — 配置凭证**
+
+用户收到 API Key 后，写入全局配置：
+
+```bash
+mkdir -p ~/.config/gmgn
+# 写入 API Key（替换为用户提供的实际 Key）
+echo 'GMGN_API_KEY=<user_api_key>' > ~/.config/gmgn/.env
+chmod 600 ~/.config/gmgn/.env
+```
+
+如果用户需要 swap 能力，追加私钥：
+
+```bash
+# 追加私钥（使用第 3 步输出的 PEM 内容）
+echo 'GMGN_PRIVATE_KEY="<pem_content>"' >> ~/.config/gmgn/.env
+```
+
+**第 5 步 — 验证**
+
+```bash
+gmgn-cli market trending --chain sol --interval 1h --limit 3
+```
+
+有输出且无报错即配置完成。
+
+---
+
+## AI Agent 升级
+
+> 运行以下命令，将 CLI 和 Skills 同时升级到最新版本。
+
+```bash
+npx skills add GMGNAI/gmgn-skills
+```
+
+升级后检查版本：
+
+```bash
+gmgn-cli --version
+```
+
+> 完整升级说明请参阅[第 9 节 — 升级 Skills 和 CLI](#9-升级-skills-和-cli)。
+
+---
+
 ## 使用案例
 
 ### 查询热门代币榜
@@ -117,6 +274,8 @@ GMGN_API_KEY=gmgn_solbscbaseethmonadtron npx gmgn-cli market trending --chain so
 
 看到 JSON 输出即表示 CLI 正常工作。公共 Key 支持所有只读接口（token / market / portfolio），公共 Key 仅用于测试，正式使用任何接口均需申请个人 API Key（见第 3 步）。
 
+> **排查 401 / 403 错误：** 如果命令返回 `401` 或 `403` 且凭证看起来正确，出口请求可能走了 IPv6（GMGN API 不支持）。立即排查：(1) 运行 `ifconfig | grep inet6`（macOS）或 `ip addr show | grep inet6`（Linux）列出所有网络接口及其 IPv6 地址；(2) 运行 `curl -s https://ipv6.icanhazip.com`——如果返回 IPv6 地址，说明流量走了 IPv6。**请立即关闭 IPv6，gmgn-cli 命令只能通过 IPv4 请求。**
+
 ## 3. 申请个人 API Key
 
 第 2 步的公共 Key 仅用于测试。正式使用（只读接口和 swap）均需在 https://gmgn.ai/ai 申请个人 API Key，需要准备：
@@ -276,7 +435,23 @@ solana 上的 <token_address> 安全吗，值得买入吗？
 
 ---
 
-## 7. CLI 参考
+## 7. 工作流文档
+
+常用分析任务的分步指引：
+
+| 工作流 | 适用场景 |
+|--------|---------|
+| [workflow-token-research.md](docs/workflow-token-research.md) | 买入前 Token 尽调（地址 → 买入/观望/跳过） |
+| [workflow-project-deep-report.md](docs/workflow-project-deep-report.md) | 多维度评分的深度项目报告 |
+| [workflow-wallet-analysis.md](docs/workflow-wallet-analysis.md) | 钱包质量评估（地址 → 是否值得跟随） |
+| [workflow-smart-money-profile.md](docs/workflow-smart-money-profile.md) | 聪明钱行为画像、跟单收益估算、排行榜对比 |
+| [workflow-risk-warning.md](docs/workflow-risk-warning.md) | 持仓风险预警（巨鲸出货、流动性、开发者跑路） |
+| [workflow-early-project-screening.md](docs/workflow-early-project-screening.md) | 筛选新发 Launchpad Token，识别聪明钱早入信号 |
+| [workflow-daily-brief.md](docs/workflow-daily-brief.md) | 每日市场简报：热门趋势 + 聪明钱动向 + 早期机会 + 风险扫描 |
+| [workflow-market-opportunities.md](docs/workflow-market-opportunities.md) | 从趋势数据中发现交易机会 |
+| [workflow-token-due-diligence.md](docs/workflow-token-due-diligence.md) | 4 步 Token 尽调清单 |
+
+## 8. CLI 参考
 
 完整参数说明：[docs/cli-usage.md](docs/cli-usage.md)。所有命令均支持 `--raw` 输出单行 JSON（方便 `jq` 等工具处理）。
 
@@ -284,23 +459,23 @@ solana 上的 <token_address> 安全吗，值得买入吗？
 
 ```bash
 # 基本信息 + 实时价格
-npx gmgn-cli token info --chain sol --address <addr>
+gmgn-cli token info --chain sol --address <addr>
 
 # 安全指标（蜜罐、税率、集中度、rug 风险）
-npx gmgn-cli token security --chain sol --address <addr>
+gmgn-cli token security --chain sol --address <addr>
 
 # 流动池信息（DEX、储备量、深度）
-npx gmgn-cli token pool --chain sol --address <addr>
+gmgn-cli token pool --chain sol --address <addr>
 
 # 持仓大户（按持仓比例排序）
-npx gmgn-cli token holders --chain sol --address <addr> --limit 50
+gmgn-cli token holders --chain sol --address <addr> --limit 50
 
 # 聪明钱持仓大户（按买入量排序）
-npx gmgn-cli token holders --chain sol --address <addr> \
+gmgn-cli token holders --chain sol --address <addr> \
   --tag smart_degen --order-by buy_volume_cur --limit 20
 
 # 交易大户（KOL，按已实现盈利排序）
-npx gmgn-cli token traders --chain sol --address <addr> \
+gmgn-cli token traders --chain sol --address <addr> \
   --tag renowned --order-by profit --limit 20
 ```
 
@@ -309,21 +484,21 @@ npx gmgn-cli token traders --chain sol --address <addr> \
 ```bash
 # K 线数据（1h 周期，最近 24 小时）
 # macOS:
-npx gmgn-cli market kline \
+gmgn-cli market kline \
   --chain sol --address <addr> \
   --resolution 1h \
   --from $(date -v-24H +%s) --to $(date +%s)
 # Linux: $(date -d '24 hours ago' +%s)
 
 # 热门代币榜（SOL，1h，按交易量排序）
-npx gmgn-cli market trending \
+gmgn-cli market trending \
   --chain sol \
   --interval 1h \
   --order-by volume --limit 20 \
   --filter not_risk --filter not_honeypot
 
 # 战壕新币列表
-npx gmgn-cli market trenches \
+gmgn-cli market trenches \
   --chain sol \
   --type new_creation --type near_completion --type completed \
   --launchpad-platform Pump.fun --launchpad-platform pump_mayhem --launchpad-platform letsbonk \
@@ -334,42 +509,42 @@ npx gmgn-cli market trenches \
 
 ```bash
 # 钱包持仓
-npx gmgn-cli portfolio holdings --chain sol --wallet <addr>
+gmgn-cli portfolio holdings --chain sol --wallet <addr>
 
 # 交易记录
-npx gmgn-cli portfolio activity --chain sol --wallet <addr>
+gmgn-cli portfolio activity --chain sol --wallet <addr>
 
 # 交易统计（支持多钱包）
-npx gmgn-cli portfolio stats --chain sol --wallet <addr1> --wallet <addr2>
+gmgn-cli portfolio stats --chain sol --wallet <addr1> --wallet <addr2>
 
 # API Key 绑定的钱包及主币余额
-npx gmgn-cli portfolio info
+gmgn-cli portfolio info
 
 # 单个 token 余额
-npx gmgn-cli portfolio token-balance --chain sol --wallet <addr> --token <token_addr>
+gmgn-cli portfolio token-balance --chain sol --wallet <addr> --token <token_addr>
 ```
 
 ### Track
 
 ```bash
 # 追踪关注钱包的交易动态（需要 GMGN_PRIVATE_KEY）
-npx gmgn-cli track follow-wallet --chain sol
-npx gmgn-cli track follow-wallet --chain sol --wallet <wallet_address> --side buy
+gmgn-cli track follow-wallet --chain sol
+gmgn-cli track follow-wallet --chain sol --wallet <wallet_address> --side buy
 
 # KOL 交易动态
-npx gmgn-cli track kol --limit 100 --raw
-npx gmgn-cli track kol --chain sol --side buy --limit 50 --raw
+gmgn-cli track kol --limit 100 --raw
+gmgn-cli track kol --chain sol --side buy --limit 50 --raw
 
 # 聪明钱交易动态
-npx gmgn-cli track smartmoney --limit 100 --raw
-npx gmgn-cli track smartmoney --chain sol --side sell --limit 50 --raw
+gmgn-cli track smartmoney --limit 100 --raw
+gmgn-cli track smartmoney --chain sol --side sell --limit 50 --raw
 ```
 
 ### Swap（需要私钥）
 
 ```bash
 # 提交兑换（固定滑点）
-npx gmgn-cli swap \
+gmgn-cli swap \
   --chain sol \
   --from <wallet-address> \
   --input-token <input-token-addr> \
@@ -378,7 +553,7 @@ npx gmgn-cli swap \
   --slippage 0.01
 
 # 提交兑换（自动滑点）
-npx gmgn-cli swap \
+gmgn-cli swap \
   --chain sol \
   --from <wallet-address> \
   --input-token <input-token-addr> \
@@ -387,7 +562,7 @@ npx gmgn-cli swap \
   --auto-slippage
 
 # 按持仓比例卖出（例：卖出 50%）
-npx gmgn-cli swap \
+gmgn-cli swap \
   --chain sol \
   --from <wallet-address> \
   --input-token <token-addr> \
@@ -396,7 +571,7 @@ npx gmgn-cli swap \
   --auto-slippage
 
 # 获取报价（不提交交易）
-npx gmgn-cli order quote \
+gmgn-cli order quote \
   --chain sol \
   --from <wallet-address> \
   --input-token <input-token-addr> \
@@ -405,7 +580,7 @@ npx gmgn-cli order quote \
   --slippage 0.01
 
 # 查询订单状态
-npx gmgn-cli order get --chain sol --order-id <order-id>
+gmgn-cli order get --chain sol --order-id <order-id>
 ```
 
 ## 8. 支持的链
@@ -449,7 +624,9 @@ gmgn-cli --version
 
 ---
 
-## 10. 安全与免责
+## 10. 安全与免责（使用前必读）
+
+本工具可供 AI Agent 调用以自动执行链上交易，存在模型幻觉、执行不可控、提示词注入等固有风险。AI Agent 在获得授权后，将以您绑定的钱包地址提交真实的链上交易，**交易一经上链即不可撤销**，可能导致资金损失，请您谨慎使用。
 
 **关于 `GMGN_PRIVATE_KEY`**
 
@@ -460,8 +637,10 @@ gmgn-cli --version
 - 限制配置文件权限：`chmod 600 ~/.config/gmgn/.env`
 - 不要将 `.env` 文件提交到版本控制系统，请将其加入 `.gitignore`
 - 不要在日志、截图或聊天中泄露 `GMGN_API_KEY` 或 `GMGN_PRIVATE_KEY`
-- 请使用最新的 gmgn-cli（`npm install -g gmgn-cli`），查看当前版本请使用 `gmgn-cli --version`。
+- 每次 swap 前，仔细核对 AI 呈现的交易摘要（链、钱包、代币地址、金额），确认无误后再回复确认
+- 建议先用小额资金验证配置后再进行大额操作
+- 请使用最新的 gmgn-cli（`npm install -g gmgn-cli`），查看当前版本请使用 `gmgn-cli --version`
 
 **免责声明**
 
-使用本工具及根据其输出做出的任何财务决策，风险由用户自行承担。GMGN 对因凭证管理不当导致的任何交易损失、错误或未授权访问不承担责任。
+使用本工具及根据其输出做出的任何财务决策，风险由用户自行承担。GMGN 对因模型幻觉、提示词注入、凭证管理不当或用户操作失误导致的任何交易损失、错误或未授权访问不承担责任。使用本工具即视为您已充分知悉上述风险并自愿承担全部责任。