gmgn-cli 1.1.6 → 1.1.8

package/skills/gmgn-portfolio/SKILL.md

@@ -2,14 +2,34 @@
 name: gmgn-portfolio
 description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, and token balance. Supports sol / bsc / base.
 argument-hint: "<info|holdings|activity|stats|token-balance> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
+metadata:
+  cliHelp: "gmgn-cli portfolio --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."**
 
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
 
+**For full wallet analysis (holdings + stats + activity + verdict), follow [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)**
+
+## Core Concepts
+
+- **`realized_profit` vs `unrealized_profit`** — `realized_profit` = profit locked in from completed sells (cash in hand). `unrealized_profit` = paper gains on positions still held, calculated at current price. These are separate numbers — do not add them unless answering "total P&L including open positions."
+
+- **`profit_change`** — A multiplier ratio, not a dollar amount. `1.5` = +150% return. `0` = break-even. `-0.5` = -50% loss. Computed as `total_profit / cost`. Do not display this as a raw decimal — convert to percentage for user-facing output.
+
+- **`pnl`** — Profit/loss ratio from `portfolio stats`: `realized_profit / total_cost`. Same multiplier format as `profit_change`. A `pnl` of `2.0` means the wallet doubled its money on completed trades over the period.
+
+- **`winrate`** — Ratio of profitable trades over the period (0–1). `0.6` = 60% of trades were profitable. Does not reflect the size of wins vs losses — a wallet can have high winrate but net negative if losses are large.
+
+- **`cost` vs `usd_value`** — In holdings: `cost` is the historical amount spent buying this token (your cost basis); `usd_value` is the current market value of the position. The difference is unrealized P&L.
+
+- **`history_bought_cost` vs `cost`** — `history_bought_cost` is the all-time cumulative spend on this token (including positions already sold). `cost` is the cost basis of the current open position only.
+
+- **Pagination (`cursor`)** — Activity results are paginated. The response includes a `next` field; pass it as `--cursor` to fetch the next page. An empty or missing `next` means you are on the last page.
+
 ## Sub-commands
 
 | Sub-command | Description |
@@ -81,11 +101,9 @@ gmgn-cli portfolio token-balance \
 | `--cursor <cursor>` | Pagination cursor |
 | `--order-by <field>` | Sort field: `usd_value` / `last_active_timestamp` / `realized_profit` / `unrealized_profit` / `total_profit` / `history_bought_cost` / `history_sold_income` (default `usd_value`) |
 | `--direction <asc\|desc>` | Sort direction (default `desc`) |
-| `--sell-out` | Include sold-out positions |
-| `--show-small` | Include small-value positions |
-| `--hide-abnormal` | Hide abnormal positions |
-| `--hide-airdrop` | Hide airdrop positions |
-| `--hide-closed` | Hide closed positions |
+| `--hide-abnormal <bool>` | Hide abnormal positions: `true` / `false` (default: `false`) |
+| `--hide-airdrop <bool>` | Hide airdrop positions: `true` / `false` (default: `true`) |
+| `--hide-closed <bool>` | Hide closed positions: `true` / `false` (default: `true`) |
 | `--hide-open` | Hide open positions |
 
 ## `portfolio activity` Options
@@ -105,6 +123,104 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 |--------|-------------|
 | `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |
 
+## Response Field Reference
+
+### `portfolio holdings` — Key Fields
+
+The response has a `holdings` array. Each item is one token position.
+
+| Field | Description |
+|-------|-------------|
+| `token.address` | Token contract address |
+| `token.symbol` / `token.name` | Token ticker and full name |
+| `token.price` | Current token price in USD |
+| `balance` | Current token balance (human-readable units) |
+| `usd_value` | Current USD value of this position |
+| `cost` | Total amount spent buying this token (USD) |
+| `realized_profit` | Profit from completed sells (USD) |
+| `unrealized_profit` | Profit on current unsold holdings at current price (USD) |
+| `total_profit` | `realized_profit + unrealized_profit` (USD) |
+| `profit_change` | Total profit ratio = `total_profit / cost` (e.g. `1.5` = +150%) |
+| `avg_cost` | Average buy price per token (USD) |
+| `buy_tx_count` | Number of buy transactions |
+| `sell_tx_count` | Number of sell transactions |
+| `last_active_timestamp` | Unix timestamp of the most recent transaction |
+| `history_bought_cost` | Total USD spent buying (all-time) |
+| `history_sold_income` | Total USD received from selling (all-time) |
+
+### `portfolio activity` — Key Fields
+
+The response has a `activities` array and a `next` cursor field for pagination.
+
+| Field | Description |
+|-------|-------------|
+| `transaction_hash` | On-chain transaction hash |
+| `type` | Transaction type: `buy` / `sell` / `add` / `remove` / `transfer` |
+| `token.address` | Token contract address |
+| `token.symbol` | Token ticker |
+| `token_amount` | Token quantity in this transaction |
+| `cost_usd` | USD value of this transaction |
+| `price` | Token price in USD at time of transaction |
+| `timestamp` | Unix timestamp of the transaction |
+| `next` | Pagination cursor — pass to `--cursor` to fetch the next page |
+
+### `portfolio stats` — Key Fields
+
+The response is an object (or array for batch). Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `realized_profit` | Total realized profit over the period (USD) |
+| `unrealized_profit` | Total unrealized profit on open positions (USD) |
+| `winrate` | Win rate — ratio of profitable trades (0–1) |
+| `total_cost` | Total amount spent buying in the period (USD) |
+| `buy_count` | Number of buy transactions |
+| `sell_count` | Number of sell transactions |
+| `pnl` | Profit/loss ratio = `realized_profit / total_cost` |
+
+**Do NOT guess field names not listed here.** If a field appears in the response but is not in this table, do not interpret it without reading the raw output first.
+
+## Output Format
+
+**Do NOT dump raw JSON.** Always parse and present data in the structured formats below. Use `--raw` only when piping to `jq` or further processing.
+
+### `portfolio holdings` — Holdings Table
+
+Present a table sorted by `usd_value` (descending). Show total portfolio value at the top.
+
+```
+Wallet: {wallet} | Chain: {chain}
+Total value: ~${sum of usd_value across all positions}
+
+# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells
+```
+
+Flag positions where `profit_change` is strongly negative (e.g. < -50%) or positive (e.g. > 200%) with a brief note.
+
+### `portfolio activity` — Activity Feed
+
+Present as a chronological list (newest first). Use human-readable timestamps.
+
+```
+{type} {token.symbol}  |  {token_amount} tokens  |  ${cost_usd}  |  {timestamp}  |  tx: {short hash}
+```
+
+Group by token if the user asks about a specific token.
+
+### `portfolio stats` — Stats Summary
+
+```
+Wallet: {wallet} | Period: {period}
+Realized P&L:   ${realized_profit}
+Unrealized P&L: ${unrealized_profit}
+Win Rate:        {winrate × 100}%
+Total Spent:     ${total_cost}
+Buys / Sells:    {buy_count} / {sell_count}
+PnL Ratio:       {pnl}x
+```
+
+For batch queries (multiple wallets), present one summary block per wallet.
+
 ## Notes
 
 - All portfolio commands use normal auth (API Key only, no signature required)
@@ -112,3 +228,14 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 - Use `--raw` to get single-line JSON for further processing
 - **Input validation** — Wallet and token addresses are validated against the expected chain format at runtime (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits). The CLI exits with an error on invalid input.
 - For follow-wallet, KOL, and Smart Money trade records, use the `gmgn-track` skill (`track follow-wallet` / `track kol` / `track smartmoney`)
+
+## Workflow
+
+For full wallet analysis including trade history and follow-through on top holdings, see [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)
+
+For in-depth trading style analysis, copy-trade ROI estimation, and smart money leaderboard comparison, see [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)
+
+**When to use which:**
+- User asks "is this wallet worth following" → [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)
+- User asks "what's this wallet's trading style", "when does he take profit", "smart money profile", "if I copied this wallet what would my return be" → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)
+- User wants to compare multiple smart money wallets by winrate/PnL → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md) Step 5 (leaderboard)

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`