gmgn-skills/CLAUDE.md

# 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.2`.
- **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).