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:

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).