gmgn-cli 1.1.6 → 1.1.9

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,100 @@ 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 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 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 — REQUIRED: Set up personal API key**
+
+⚠️ This step is mandatory. The demo key in Step 2 supports testing only and is not for actual use.
+
+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 && \
+  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
+```
 
-> **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.
-> ```
+**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
+```
+
+> For the full upgrade reference, see [Section 9 — Upgrade Skills and CLI](#9-upgrade-skills-and-cli).
 
 ---
 
@@ -64,17 +217,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 +247,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 +405,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'`).
 
@@ -291,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
@@ -351,37 +510,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 +535,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