gmgn-cli 1.1.8 → 1.1.10

package/skills/gmgn-market/SKILL.md

@@ -55,9 +55,40 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
 
 ## Prerequisites
 
-- `.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`
+- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
+- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`
+
+## Rate Limit Handling
+
+All market routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.
+
+| Command | Route | Weight |
+|---------|-------|--------|
+| `market kline` | `GET /v1/market/token_kline` | 2 |
+| `market trending` | `GET /v1/market/rank` | 1 |
+| `market trenches` | `POST /v1/trenches` | 3 |
+
+When a request returns `429`:
+
+- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
+- The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
+- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.
+
+**First-time setup** (if `GMGN_API_KEY` is not configured):
+
+1. Generate key pair and show the public key to the user:
+   ```bash
+   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+   ```
+   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form, then send me the API Key value shown on the page."*
+
+2. Wait for the user's API key, then configure:
+   ```bash
+   mkdir -p ~/.config/gmgn
+   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
+   chmod 600 ~/.config/gmgn/.env
+   ```
 
 ## `market kline` Parameters
 
@@ -437,9 +468,95 @@ Use field combinations to determine what stage a token is in. This affects how s
 | `--type` | No | Categories to query, repeatable: `new_creation` / `near_completion` / `completed` (default: all three) |
 | `--launchpad-platform` | No | Launchpad platform filter, repeatable (default: all platforms for the chain) |
 | `--limit` | No | Max results per category, max 80 (default: 80) |
+| `--filter-preset` | No | Named server-side filter preset: `safe` / `smart-money` / `strict` |
+| `--sort-by` | No | Client-side sort per category: `smart_degen_count` / `renowned_count` / `volume_24h` / `volume_1h` / `swaps_24h` / `swaps_1h` / `rug_ratio` / `holder_count` / `usd_market_cap` / `created_timestamp` |
+| `--direction` | No | Sort direction: `asc` / `desc` (default: `desc`; `asc` for `rug_ratio`) |
+| `--min-*` / `--max-*` | No | Server-side filter range flags — see Filter Fields Reference below |
+
+### Filter Presets
+
+Presets are applied server-side: the API filters tokens before returning results.
+
+| Preset | Server-side filters applied |
+|--------|----------------------------|
+| `safe` | `max_rug_ratio=0.3` + `max_bundler_rate=0.3` + `max_insider_ratio=0.3` |
+| `smart-money` | `min_smart_degen_count=1` |
+| `strict` | `max_rug_ratio=0.3` + `max_bundler_rate=0.3` + `max_insider_ratio=0.3` + `min_smart_degen_count=1` + `min_volume_24h=1000` |
+
+**Preset + explicit flag interaction:** Explicit filter flags always override preset values. For example, `--filter-preset safe --max-rug-ratio 0.1` applies the `safe` preset but overrides rug_ratio threshold to `0.1`.
+
+**All filter flags are sent as part of the API request body (server-side)** — the server filters tokens before returning results. Use `--limit 80` (the default maximum) to maximise the pool.
 
 Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is an array of `RankItem` (same fields as `market trending` rank items). **Important: `data.pump` in the response corresponds to `--type near_completion` in the request. The API always returns this category under the key `pump`, not `near_completion`.**
 
+### Server-Side Filter Fields
+
+All filter flags are sent as part of the API request body — the server filters tokens before returning results. Flags follow the naming convention `--min-{field}` / `--max-{field}`.
+
+| Flag pair | Type | Description |
+|-----------|------|-------------|
+| `--min-volume-24h` / `--max-volume-24h` | float | 24h trading volume (USD) |
+| `--min-net-buy-24h` / `--max-net-buy-24h` | float | 24h net buy volume (USD) |
+| `--min-swaps-24h` / `--max-swaps-24h` | int | 24h total swap count |
+| `--min-buys-24h` / `--max-buys-24h` | int | 24h buy count |
+| `--min-sells-24h` / `--max-sells-24h` | int | 24h sell count |
+| `--min-visiting-count` / `--max-visiting-count` | int | Visitor count |
+| `--min-progress` / `--max-progress` | float | Bonding curve progress (0–1) |
+| `--min-marketcap` / `--max-marketcap` | float | Market cap (USD) |
+| `--min-liquidity` / `--max-liquidity` | float | Liquidity (USD) |
+| `--min-created` / `--max-created` | string | Token age (e.g. `1m` / `5m` / `1h` / `24h`) |
+| `--min-holder-count` / `--max-holder-count` | int | Holder count |
+| `--min-top-holder-rate` / `--max-top-holder-rate` | float | Top-10 holder concentration (0–1) |
+| `--min-rug-ratio` / `--max-rug-ratio` | float | Rug pull risk score (0–1) |
+| `--min-bundler-rate` / `--max-bundler-rate` | float | Bundle-bot trading ratio (0–1) |
+| `--min-insider-ratio` / `--max-insider-ratio` | float | Insider trading ratio (0–1) |
+| `--min-entrapment-ratio` / `--max-entrapment-ratio` | float | Entrapment/Phishing trading ratio (0–1) |
+| `--min-private-vault-hold-rate` / `--max-private-vault-hold-rate` | float | Private vault holding ratio (0–1) |
+| `--min-top70-sniper-hold-rate` / `--max-top70-sniper-hold-rate` | float | Top-70 sniper holding ratio (0–1) |
+| `--min-bot-count` / `--max-bot-count` | int | Bot wallet count |
+| `--min-bot-degen-rate` / `--max-bot-degen-rate` | float | Bot-degen wallet ratio (0–1) |
+| `--min-fresh-wallet-rate` / `--max-fresh-wallet-rate` | float | Fresh wallet ratio (0–1) |
+| `--min-total-fee` / `--max-total-fee` | float | Total fee |
+| `--min-smart-degen-count` / `--max-smart-degen-count` | int | Smart-money holder count |
+| `--min-renowned-count` / `--max-renowned-count` | int | KOL / renowned wallet count |
+| `--min-creator-balance-rate` / `--max-creator-balance-rate` | float | Creator holding ratio (0–1) |
+| `--min-creator-created-count` / `--max-creator-created-count` | int | Creator's total token creation count |
+| `--min-creator-created-open-count` / `--max-creator-created-open-count` | int | Creator's graduated token count |
+| `--min-creator-created-open-ratio` / `--max-creator-created-open-ratio` | float | Creator's graduation ratio (0–1) |
+| `--min-x-follower` / `--max-x-follower` | int | Twitter / X follower count |
+| `--min-twitter-rename-count` / `--max-twitter-rename-count` | int | Twitter rename count |
+| `--min-tg-call-count` / `--max-tg-call-count` | int | Telegram call count |
+
+### Trenches Filter Examples
+
+```bash
+# Apply the safe preset (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --filter-preset safe
+
+# Require at least 1 smart money holder (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --min-smart-degen-count 1
+
+# Safe preset + require smart money + sort by smart degen count (server-side filter, client-side sort)
+gmgn-cli market trenches --chain sol --type new_creation \
+  --filter-preset safe --min-smart-degen-count 1 --sort-by smart_degen_count
+
+# Strict preset — safe + smart money + min $1k volume (server-side)
+gmgn-cli market trenches --chain sol --type new_creation --type near_completion \
+  --filter-preset strict --sort-by smart_degen_count
+
+# Manual range filters (all sent server-side)
+gmgn-cli market trenches --chain sol --type new_creation \
+  --max-rug-ratio 0.3 --max-bundler-rate 0.3 --max-insider-ratio 0.3 \
+  --min-smart-degen-count 1 --min-volume-24h 1000
+
+# Filter by token age: only tokens created within the last 30 minutes
+gmgn-cli market trenches --chain sol --type new_creation --max-created 30m
+
+# Filter by market cap range
+gmgn-cli market trenches --chain sol --type new_creation \
+  --min-marketcap 10000 --max-marketcap 500000
+```
+
 ## `market trenches` Response Fields
 
 **Basic Info**
@@ -526,6 +643,44 @@ Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is
 
 **After fetching trenches results, apply the Token Quality Filter Criteria section before presenting tokens to the user.** Do not dump raw results — filter first, then surface the strongest candidates.
 
+### Trenches Filter Examples
+
+```bash
+# Quick safe screen — exclude rugs, wash trading, and bundlers
+gmgn-cli market trenches --chain sol --type new_creation \
+  --filter-preset safe --raw
+
+# Smart money screen — only tokens with smart money or KOL presence
+gmgn-cli market trenches --chain sol \
+  --type new_creation --type near_completion \
+  --filter-preset smart-money \
+  --sort-by smart_degen_count --raw
+
+# Strict screen — safe + smart money + minimum volume, sorted by smart degens
+gmgn-cli market trenches --chain sol --type completed \
+  --filter-preset strict --sort-by smart_degen_count --raw
+
+# Custom filter — no wash trading, rug_ratio <= 0.2, at least 1 smart degen
+gmgn-cli market trenches --chain sol \
+  --type new_creation --type near_completion \
+  --exclude-wash-trading --max-rug-ratio 0.2 --min-smart-degen 1 \
+  --sort-by smart_degen_count --raw
+
+# BSC — safe screen on new tokens from fourmeme
+gmgn-cli market trenches --chain bsc --type new_creation \
+  --launchpad-platform fourmeme --launchpad-platform fourmeme_agent \
+  --filter-preset safe --sort-by volume_1h --raw
+
+# Sort by rug_ratio ascending (safest first), no other filters
+gmgn-cli market trenches --chain sol --type completed \
+  --sort-by rug_ratio --raw
+
+# Find tokens with many holders and strong 1h swap activity
+gmgn-cli market trenches --chain sol --type completed \
+  --min-holders 100 --min-swaps 50 \
+  --sort-by swaps_1h --raw
+```
+
 ### Solana Trenches Examples
 
 ```bash

package/skills/gmgn-portfolio/SKILL.md

@@ -46,9 +46,42 @@ Use the `gmgn-cli` tool to query wallet portfolio data based on the user's reque
 
 ## Prerequisites
 
-- `.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`
+- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
+- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`
+
+## Rate Limit Handling
+
+All portfolio routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.
+
+| Command | Route | Weight |
+|---------|-------|--------|
+| `portfolio info` | `GET /v1/user/info` | 1 |
+| `portfolio holdings` | `GET /v1/user/wallet_holdings` | 2 |
+| `portfolio activity` | `GET /v1/user/wallet_activity` | 3 |
+| `portfolio stats` | `GET /v1/user/wallet_stats` | 3 |
+| `portfolio token-balance` | `GET /v1/user/wallet_token_balance` | 1 |
+
+When a request returns `429`:
+
+- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
+- The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
+- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.
+
+**First-time setup** (if `GMGN_API_KEY` is not configured):
+
+1. Generate key pair and show the public key to the user:
+   ```bash
+   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+   ```
+   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form, then send me the API Key value shown on the page."*
+
+2. Wait for the user's API key, then configure:
+   ```bash
+   mkdir -p ~/.config/gmgn
+   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
+   chmod 600 ~/.config/gmgn/.env
+   ```
 
 ## Usage Examples
 

package/skills/gmgn-swap/SKILL.md

@@ -48,6 +48,9 @@ Use the `gmgn-cli` tool to submit a token swap or query an existing order. **Req
 | `swap` | Submit a token swap |
 | `order quote` | Get a swap quote (no transaction submitted) |
 | `order get` | Query order status |
+| `order strategy create` | Create a limit/strategy order (requires private key) |
+| `order strategy list` | List strategy orders (normal auth) |
+| `order strategy cancel` | Cancel a strategy order (requires private key) |
 
 ## Supported Chains
 
@@ -67,13 +70,44 @@ Currency tokens are the base/native assets of each chain. They are used to buy o
 
 ## Prerequisites
 
-Both `GMGN_API_KEY` and `GMGN_PRIVATE_KEY` must be set in `.env`. The private key must correspond to the wallet bound to the API Key.
+Both `GMGN_API_KEY` and `GMGN_PRIVATE_KEY` must be configured in `~/.config/gmgn/.env`. The private key must correspond to the wallet bound to the API Key.
 
-`gmgn-cli` must be installed globally before use (one-time setup):
+- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
 
-```bash
-npm install -g gmgn-cli
-```
+## Rate Limit Handling
+
+All swap-related routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.
+
+| Command | Route | Weight |
+|---------|-------|--------|
+| `swap` | `POST /v1/trade/swap` | 5 |
+| `order quote` | `GET /v1/trade/quote` | 2 |
+| `order get` | `GET /v1/trade/query_order` | 1 |
+
+When a request returns `429`:
+
+- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
+- `swap` is a real transaction: never loop or auto-submit repeated swap attempts after a `429`. Wait until the reset time, then ask for confirmation again before retrying.
+- The CLI may wait and retry once automatically for short cooldowns on read-only commands such as `order quote` and `order get`. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
+- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes.
+- `POST /v1/trade/swap` also has an error-count limiter. Repeatedly triggering the same business error, especially `40003701` (insufficient token balance), can return `ERROR_RATE_LIMIT_BLOCKED`. When this happens, do not retry until the reset time and fix the underlying request first.
+
+**First-time setup** (if credentials are not configured):
+
+1. Generate key pair and show the public key to the user:
+   ```bash
+   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+   ```
+   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form (enable swap capability), then send me the API Key value shown on the page."*
+
+2. Wait for the user's API key, then configure both credentials:
+   ```bash
+   mkdir -p ~/.config/gmgn
+   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
+   echo 'GMGN_PRIVATE_KEY="<pem_content_from_step_1>"' >> ~/.config/gmgn/.env
+   chmod 600 ~/.config/gmgn/.env
+   ```
 
 ### Credential Model
 
@@ -248,11 +282,108 @@ Order ID: {order_id}
 
 Convert `filled_input_amount` and `filled_output_amount` from smallest unit using token decimals before displaying.
 
+## `order strategy create` Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` / `base` |
+| `--from` | Yes | Wallet address (must match API Key binding) |
+| `--base-token` | Yes | Base token contract address |
+| `--quote-token` | Yes | Quote token contract address |
+| `--side` | Yes | Direction: `buy` / `sell` |
+| `--check-price` | Yes | Trigger check price |
+| `--amount-in` | No* | Input amount (smallest unit). Mutually exclusive with `--amount-in-percent` |
+| `--amount-in-percent` | No* | Input as percentage (e.g. `50` = 50%). Mutually exclusive with `--amount-in` |
+| `--limit-price-mode` | No | `exact` / `slippage` (default: `slippage`) |
+| `--expire-in` | No | Order expiry in seconds |
+| `--sell-ratio-type` | No | `buy_amount` (default) / `hold_amount` |
+| `--slippage` | No | Slippage tolerance, e.g. `0.01` = 1%. Mutually exclusive with `--auto-slippage` |
+| `--auto-slippage` | No | Enable automatic slippage |
+| `--priority-fee` | No | Priority fee in SOL (SOL only) |
+| `--tip-fee` | No | Tip fee |
+| `--gas-price` | No | Gas price in wei (EVM chains) |
+| `--anti-mev` | No | Enable anti-MEV protection |
+
+
+**`order strategy create` Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `order_id` | string | Created strategy order ID |
+| `is_update` | bool | `true` if an existing order was updated, `false` if newly created |
+
+## `order strategy list` Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` / `base` |
+| `--type` | No | `open` (default) / `history` |
+| `--from` | No | Filter by wallet address |
+| `--base-token` | No | Filter by token address |
+| `--page-token` | No | Pagination cursor from previous response |
+| `--limit` | No | Results per page (default 10 for history) |
+
+**`order strategy list` Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `next_page_token` | string | Cursor for next page; empty when no more data |
+| `total` | int | Total count (only returned when `--type open`) |
+| `list` | array | Strategy order list |
+
+## `order strategy cancel` Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--chain` | Yes | `sol` / `bsc` / `base` |
+| `--from` | Yes | Wallet address (must match API Key binding) |
+| `--order-id` | Yes | Order ID to cancel |
+| `--close-sell-model` | No | Sell model when closing the order |
+
+## `order strategy` Usage Examples
+
+```bash
+# Create a take-profit order: sell when price rises to target
+gmgn-cli order strategy create \
+  --chain sol \
+  --from <wallet_address> \
+  --base-token <token_address> \
+  --quote-token <sol_address> \
+  --sub-order-type take_profit \
+  --check-price 0.002 \
+  --amount-in 1000000 \
+  --slippage 0.01
+
+# Create a stop-loss order: sell when price drops to target
+gmgn-cli order strategy create \
+  --chain sol \
+  --from <wallet_address> \
+  --base-token <token_address> \
+  --quote-token <sol_address> \
+  --sub-order-type stop_loss \
+  --check-price 0.0005 \
+  --amount-in-percent 100 \
+  --slippage 0.01
+
+# List open strategy orders
+gmgn-cli order strategy list --chain sol
+
+# List history orders with pagination
+gmgn-cli order strategy list --chain sol --type history --limit 20
+
+# Cancel a strategy order
+gmgn-cli order strategy cancel \
+  --chain sol \
+  --from <wallet_address> \
+  --order-id <order_id>
+```
+
 ## Notes
 
 - Swap uses **critical auth** (API Key + signature) — CLI handles signing automatically, no manual processing needed
 - After submitting a swap, use `order get` to poll for confirmation
 - `--amount` is in the **smallest unit** (e.g., lamports for SOL)
+- `order strategy create` and `order strategy cancel` use critical auth (require `GMGN_PRIVATE_KEY`); `order strategy list` uses normal auth
 - Use `--raw` to get single-line JSON for further processing
 
 ## Input Validation

package/skills/gmgn-token/SKILL.md

@@ -46,9 +46,42 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
 
 ## Prerequisites
 
-- `.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`
+- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
+- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`
+
+## Rate Limit Handling
+
+All token routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.
+
+| Command | Route | Weight |
+|---------|-------|--------|
+| `token info` | `GET /v1/token/info` | 1 |
+| `token security` | `GET /v1/token/security` | 1 |
+| `token pool` | `GET /v1/token/pool_info` | 1 |
+| `token holders` | `GET /v1/market/token_top_holders` | 5 |
+| `token traders` | `GET /v1/market/token_top_traders` | 5 |
+
+When a request returns `429`:
+
+- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
+- The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
+- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.
+
+**First-time setup** (if `GMGN_API_KEY` is not configured):
+
+1. Generate key pair and show the public key to the user:
+   ```bash
+   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+   ```
+   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form, then send me the API Key value shown on the page."*
+
+2. Wait for the user's API key, then configure:
+   ```bash
+   mkdir -p ~/.config/gmgn
+   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
+   chmod 600 ~/.config/gmgn/.env
+   ```
 
 ## Parameters — `token info` / `token security` / `token pool`
 

package/skills/gmgn-track/SKILL.md

@@ -59,10 +59,45 @@ Use the `gmgn-cli` tool to query on-chain tracking data based on the user's requ
 
 ## Prerequisites
 
-- `.env` file with `GMGN_API_KEY` set
-- `GMGN_PRIVATE_KEY` required for `track follow-wallet` (signature auth); not needed for `track kol` / `track smartmoney`
-- 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`
+- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
+- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`
+- `GMGN_PRIVATE_KEY` required only for `track follow-wallet`; not needed for `track kol` / `track smartmoney`
+
+## Rate Limit Handling
+
+All tracking routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.
+
+| Command | Route | Weight |
+|---------|-------|--------|
+| `track follow-wallet` | `GET /v1/trade/follow_wallet` | 3 |
+| `track kol` | `GET /v1/user/kol` | 1 |
+| `track smartmoney` | `GET /v1/user/smartmoney` | 1 |
+
+When a request returns `429`:
+
+- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
+- The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact retry time instead of sending more requests.
+- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.
+
+**First-time setup** (if `GMGN_API_KEY` is not configured):
+
+1. Generate key pair and show the public key to the user:
+   ```bash
+   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
+     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
+   ```
+   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form, then send me the API Key value shown on the page."*
+
+2. Wait for the user's API key, then configure:
+   ```bash
+   mkdir -p ~/.config/gmgn
+   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
+   chmod 600 ~/.config/gmgn/.env
+   ```
+   If the user also needs `track follow-wallet`, append the private key:
+   ```bash
+   echo 'GMGN_PRIVATE_KEY="<pem_content_from_step_1>"' >> ~/.config/gmgn/.env
+   ```
 
 ## Usage Examples