mirror of
https://github.com/GMGNAI/gmgn-skills.git
synced 2026-07-27 16:57:44 +00:00
dev
70 lines
4.2 KiB
Markdown
70 lines
4.2 KiB
Markdown
# 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).
|