initial import

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the gmgn-cli plugin.
+
+## Project Overview
+
+This is a **Claude Code plugin** — a collection of GMGN OpenAPI skills for on-chain operations. It provides CLI tools and skills for token queries, market data, wallet portfolio analysis, and swap execution across sol / bsc / base.
+
+## Available Skills
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| `gmgn-token` | Token info, security, pool, holders, traders | User asks about a token's price, market cap, security risk, liquidity pool, top holders, or top traders; user wants to research a token before buying; user asks "is this token safe", "who holds this token", "what's the liquidity" |
+| `gmgn-market` | K-line / candlestick market data + trending tokens | User asks for price history, chart data, OHLCV candles; user wants to analyze price trends over time; user asks "show me the 1h chart", "what was the price last week", "give me kline data for this token"; user wants to discover hot or trending tokens; user asks "what tokens are trending", "show me top tokens by volume", "find hot tokens on SOL" |
+| `gmgn-portfolio` | Wallet holdings, activity, trading stats, token balance | User asks about a wallet's holdings, P&L, transaction history, trading statistics, or token balance; user wants to analyze a wallet; user asks "what tokens does this wallet hold", "show me recent trades", "what's the win rate of this wallet" |
+| `gmgn-swap` | Token swap execution + order status query | User wants to swap tokens, execute a trade, or check an order status; user asks "swap SOL for USDC", "buy this token", "check my order"; **requires private key configured in `.env`** |
+
+## Architecture
+
+- **`src/`** — TypeScript source (CLI commands, API client, signer)
+- **`skills/`** — 4 SKILL.md files for Claude Code skill definitions
+- **`dist/`** — Compiled output (generated by `npm run build`)
+- **`.claude-plugin/`** — Plugin metadata for Claude Code
+
+## Prerequisites
+
+Config lookup order (project overrides global):
+1. `~/.config/gmgn/.env` — global config, set once for all projects
+2. `.env` in the current working directory — project-level override (takes precedence)
+
+Required variables:
+- `GMGN_API_KEY` — apply at https://gmgn.ai/ai
+- `GMGN_PRIVATE_KEY` — PEM content, required for swap/order commands only
+
+If the user has not configured credentials or commands fail with a missing key error, guide them to create `~/.config/gmgn/.env`:
+
+```bash
+mkdir -p ~/.config/gmgn
+cat > ~/.config/gmgn/.env << 'EOF'
+GMGN_API_KEY=your_api_key_here
+EOF
+```
+
+## Auth Modes
+
+| Mode | Commands | Requirements |
+|------|----------|--------------|
+| Normal | token / market / portfolio | `GMGN_API_KEY` only, no signature |
+| Critical | swap / order | `GMGN_API_KEY` + `GMGN_PRIVATE_KEY` — CLI handles signing automatically |
+
+## SKILL.md Authoring Rules
+
+When creating or updating any file in `skills/`:
+
+- **Language**: English only — no bilingual content. SKILL.md files are read by AI, not humans.
+- **Package runner**: Always use the pre-installed `gmgn-cli` binary (e.g. `gmgn-cli token info ...`). Never use `npx gmgn-cli` or `npx gmgn-cli@<version>` — npx downloads the package at runtime alongside live credentials. The package must be installed once with `npm install -g gmgn-cli@1.0.1`.
+- **Section order**: Sub-commands → Supported Chains → Prerequisites → Parameters/Options (if needed) → Usage Examples → Notes
+- **`--raw` flag**: All commands support `--raw` for single-line JSON output. Always document it in the Notes section.
+- **YAML frontmatter**: Quote `argument-hint` values that contain `|` characters to avoid YAML parsing errors.
+
+## Keeping Docs in Sync
+
+`src/commands/*.ts` is the single source of truth for all commands, sub-commands, and options.
+
+**When any file in `src/commands/` is modified**, you MUST also update:
+
+1. **`skills/gmgn-{command}/SKILL.md`** — Sub-commands table and Options tables must exactly reflect the current command definitions.
+2. **`Readme.md`** — The `## Commands` section bash examples must reflect added/removed commands or options.
+3. **`Readme.zh.md`** — Same as Readme.md for the bash examples (Chinese descriptions are maintained separately).