gmgn-cli 1.1.9 → 1.1.10

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