gavindiaz/gmgn-skills
1
0
Fork 0
mirror of https://github.com/GMGNAI/gmgn-skills.git synced 2026-07-27 16:57:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: enrich all SKILL.md files with response fields, usage examples, and AI-agent guidance

Browse Source 
- gmgn-token: full response field reference for all 5 sub-commands (token info nested objects pool/link/stat/wallet_tags_stat, security, pool, holders, traders); granular usage examples per scenario; full due diligence workflow with security threshold table; market cap calculation note; volume redirect to kline
- gmgn-market: verified kline/trending response fields from live API; trending + platform filter examples for SOL/BSC/Base major launchpads; interval selection guide; trenches intent→type mapping table; standardized section headings with sub-command names
- gmgn-portfolio/gmgn-swap: standardize section headings to include sub-command names
- CLAUDE.md: add newly-launched token triggers for gmgn-market skill routing
- Readme/Readme.zh: add missing portfolio sub-commands, kline examples, auto-slippage swap example; remove version pin; update install instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
gumponchain
2026-03-26 21:25:38 +08:00
committed by GMGN.AI
parent 12d3c358d8
commit 0239e42b50
7 changed files with 733 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -11,7 +11,7 @@ This is a **Claude Code plugin** — a collection of GMGN OpenAPI skills for on-
| 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-market` | K-line / candlestick market data + trending tokens + newly launched launchpad tokens | User asks for price history, chart data, OHLCV candles, trading volume over time; user wants to analyze price trends; 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"; **user asks about newly launched tokens, fresh tokens, latest tokens on launchpads** — e.g. "show me new tokens on pump.fun", "what tokens just launched on SOL", "find newly created tokens", "latest tokens on letsbonk" → use `market trenches --type new_creation` |
| `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`** |
Readme.md
+12 -3
View File
@@ -80,7 +80,7 @@ npx skills add GMGNAI/gmgn-skills
### 1.2 npm Global Install
```bash
npm install -g gmgn-cli@1.1.0
npm install -g gmgn-cli
```
### 1.3 Local Development
@@ -294,7 +294,7 @@ npx gmgn-cli portfolio holdings --chain sol --wallet <addr>
### Swap (requires private key)
```bash
# Submit swap
# Submit swap with fixed slippage
npx gmgn-cli swap \
--chain sol \
--from <wallet-address> \
@@ -303,6 +303,15 @@ npx gmgn-cli swap \
--amount 1000000 \
--slippage 0.01
# Submit swap with automatic slippage
npx gmgn-cli swap \
--chain sol \
--from <wallet-address> \
--input-token <input-token-addr> \
--output-token <output-token-addr> \
--amount 1000000 \
--auto-slippage
# Query order
npx gmgn-cli order get --chain sol --order-id <order-id>
```
@@ -327,7 +336,7 @@ npx gmgn-cli order get --chain sol --order-id <order-id>
- Restrict config file permissions: `chmod 600 ~/.config/gmgn/.env`
- Never commit your `.env` file to version control — add it to `.gitignore`
- Do not share `GMGN_API_KEY` or `GMGN_PRIVATE_KEY` in logs, screenshots, or chat messages
- Use a pinned install (`npm install -g gmgn-cli@1.1.0`) rather than `npx gmgn-cli` to avoid executing unintended package updates alongside your credentials
- Always use the latest version of gmgn-cli (`npm install -g gmgn-cli`). To check your current version: `gmgn-cli --version`
**Disclaimer**
Readme.zh.md
+92 -4
View File
@@ -80,7 +80,7 @@ npx skills add GMGNAI/gmgn-skills
### 1.2 npm 全局安装
```bash
npm install -g gmgn-cli@1.1.0
npm install -g gmgn-cli
```
### 1.3 本地开发
@@ -227,12 +227,23 @@ ln -s ~/.opencode/gmgn-cli/skills ~/.agents/skills/gmgn-cli
```
用 0.1 SOL 买入 <token_address>
卖出 BSC 上 <token_address> 的 50%
把我持有的 <token_address> 卖掉 30%
查询报价，我想用 1 SOL 换 <token_address>，能换多少
查询订单状态 <order_id>
solana 上的 <token_address> 安全吗，值得买入吗？
查看 <token_address> 的前十大持有者
查看 <token_address> 的聪明钱持仓，按买入量排序
查看 <token_address> 最近的 KOL 交易动态
查看我在 SOL 上的钱包持仓
查询 0x1234... 的代币详情
查看 <token_address> 过去 24 小时的 K 线和交易量
查看 BSC 上钱包 <wallet_address> 的交易统计
查看钱包 <wallet_address> 最近的交易记录
我的 API Key 绑定了哪些钱包，余额各是多少
查看 SOL 链上最新的聪明钱交易动态
查看 SOL 链上 KOL 最近在买什么
查询 Solana 上最新发布的代币
查询 Solana 1 分钟交易热门代币
```
### 典型使用场景
@@ -266,18 +277,46 @@ solana 上的 <token_address> 安全吗，值得买入吗？
### Token
```bash
# 基本信息 + 实时价格
npx gmgn-cli token info --chain sol --address <addr>
# 安全指标（蜜罐、税率、集中度、rug 风险）
npx gmgn-cli token security --chain sol --address <addr>
# 流动池信息（DEX、储备量、深度）
npx gmgn-cli token pool --chain sol --address <addr>
# 持仓大户（按持仓比例排序）
npx gmgn-cli token holders --chain sol --address <addr> --limit 50
# 聪明钱持仓大户（按买入量排序）
npx gmgn-cli token holders --chain sol --address <addr> \
--tag smart_degen --order-by buy_volume_cur --limit 20
# 交易大户（KOL，按已实现盈利排序）
npx gmgn-cli token traders --chain sol --address <addr> \
--tag renowned --order-by profit --limit 20
```
### Market
```bash
# K 线数据（1h 周期，最近 24 小时）
# macOS:
npx gmgn-cli market kline \
--chain sol --address <addr> \
--resolution 1h \
--from $(date -v-24H +%s) --to $(date +%s)
# Linux: $(date -d '24 hours ago' +%s)
# 热门代币榜（SOL，1h，按交易量排序）
npx gmgn-cli market trending \
--chain sol \
--interval 1h \
--order-by volume --limit 20 \
--filter not_risk --filter not_honeypot
# 战壕新币列表
npx gmgn-cli market trenches \
--chain sol \
--type new_creation --type near_completion --type completed \
@@ -288,13 +327,35 @@ npx gmgn-cli market trenches \
### Portfolio
```bash
# 钱包持仓
npx gmgn-cli portfolio holdings --chain sol --wallet <addr>
# 交易记录
npx gmgn-cli portfolio activity --chain sol --wallet <addr>
# 交易统计（支持多钱包）
npx gmgn-cli portfolio stats --chain sol --wallet <addr1> --wallet <addr2>
# API Key 绑定的钱包及主币余额
npx gmgn-cli portfolio info --chain sol
# 单个 token 余额
npx gmgn-cli portfolio token-balance --chain sol --wallet <addr> --token <token_addr>
# 跟单交易记录
npx gmgn-cli portfolio follow-wallet --chain sol
# KOL 交易记录（仅 SOL）
npx gmgn-cli portfolio kol
# 聪明钱交易记录（仅 SOL）
npx gmgn-cli portfolio smartmoney
```
### Swap（需要私钥）
```bash
# 提交兑换
# 提交兑换（固定滑点）
npx gmgn-cli swap \
--chain sol \
--from <wallet-address> \
@@ -303,7 +364,34 @@ npx gmgn-cli swap \
--amount 1000000 \
--slippage 0.01
# 查询订单
# 提交兑换（自动滑点）
npx gmgn-cli swap \
--chain sol \
--from <wallet-address> \
--input-token <input-token-addr> \
--output-token <output-token-addr> \
--amount 1000000 \
--auto-slippage
# 按持仓比例卖出（例：卖出 50%）
npx gmgn-cli swap \
--chain sol \
--from <wallet-address> \
--input-token <token-addr> \
--output-token <usdc-addr> \
--percent 50 \
--auto-slippage
# 获取报价（不提交交易）
npx gmgn-cli order quote \
--chain sol \
--from <wallet-address> \
--input-token <input-token-addr> \
--output-token <output-token-addr> \
--amount 1000000 \
--slippage 0.01
# 查询订单状态
npx gmgn-cli order get --chain sol --order-id <order-id>
```
@@ -327,7 +415,7 @@ npx gmgn-cli order get --chain sol --order-id <order-id>
- 限制配置文件权限：`chmod 600 ~/.config/gmgn/.env`
- 不要将 `.env` 文件提交到版本控制系统，请将其加入 `.gitignore`
- 不要在日志、截图或聊天中泄露 `GMGN_API_KEY` 或 `GMGN_PRIVATE_KEY`
- 使用固定版本安装（`npm install -g gmgn-cli@1.1.0`），而非 `npx gmgn-cli`，以避免在持有凭证的环境中执行未预期的包更新
- 请使用最新的 gmgn-cli（`npm install -g gmgn-cli`），查看当前版本请使用 `gmgn-cli --version`。
**免责声明**
skills/gmgn-market/SKILL.md
+245 -17
View File
@@ -10,9 +10,9 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
| Sub-command | Description |
|-------------|-------------|
| `market kline` | Token candlestick data |
| `market trending` | Trending token swap data |
| `market trenches` | Trenches token lists (new creation, near completion, completed) |
| `market kline` | Token candlestick / OHLCV data and trading volume over a time range |
| `market trending` | Trending tokens ranked by swap activity — use `--interval` to specify the time window (e.g. `1m` for 1-minute hottest, `1h` for 1-hour trending) |
| `market trenches` | Newly launched launchpad paltform tokens — **use this when the user asks for "new tokens", "just launched tokens", "latest tokens on pump.fun/letsbonk"**. Three categories: `new_creation` (just created), `near_completion` (bonding curve almost full), `completed` (graduated to open market / DEX) |
## Supported Chains
@@ -24,21 +24,50 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
- Run from the directory where your `.env` file is located, or set `GMGN_HOST` in your environment
- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
## Kline Parameters
## `market kline` Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `--chain` | Yes | `sol` / `bsc` / `base` |
| `--address` | Yes | Token contract address |
| `--resolution` | Yes | Candlestick resolution |
| `--resolution` | Yes | Candlestick resolution: `1m` / `5m` / `15m` / `1h` / `4h` / `1d` |
| `--from` | No | Start time (Unix seconds) |
| `--to` | No | End time (Unix seconds) |
## Resolutions
## `market kline` Response Fields
`1m` / `5m` / `15m` / `1h` / `4h` / `1d`
The response is an object with a `list` array. Each element in `list` is one candlestick:
## Trending Options
| Field | Type | Description |
|-------|------|-------------|
| `time` | number | Candle open time — Unix timestamp in **milliseconds** (divide by 1000 for seconds) |
| `open` | string | Opening price in USD at the start of the period |
| `close` | string | Closing price in USD at the end of the period |
| `high` | string | Highest price in USD during the period |
| `low` | string | Lowest price in USD during the period |
| `volume` | string | Trading volume in **USD** (dollar value of all trades in this period) |
| `amount` | string | Trading volume in **base token units** (number of tokens traded) |
**Important distinctions (naming is counterintuitive — do not guess):**
- `volume` = USD dollar value (e.g. `1214` means ~$1,214 traded) — use this for "how much was traded in USD"
- `amount` = token count (e.g. `5379110` means ~5.38M tokens changed hands) — use this for "how many tokens were traded"
- For tokens not priced at $1, `volume` and `amount` will differ by orders of magnitude (e.g. a $0.0002 token: $1,214 volume = 5,379,110 tokens)
- To get **total USD volume over a time range**, sum `volume` across all candles in the range
- To get **price trend**, read `close` values in chronological order (`time` ascending)
- To detect **volatility**, compare `high` vs `low` within each candle
- Candles are returned in chronological order (oldest first)
## `market trending` Options
**`--interval` selection guide — always match to the user's stated time window:**
| User says | `--interval` |
|-----------|-------------|
| "1分钟热门" / "1m trending" / "hottest right now" | `1m` |
| "5分钟" / "5m" | `5m` |
| "1小时" / "1h" / no time specified (default) | `1h` |
| "6小时" / "6h" | `6h` |
| "24小时" / "今日" / "daily" | `24h` |
| Option | Description |
|--------|-------------|
@@ -52,6 +81,8 @@ Use the `gmgn-cli` tool to query K-line data for a token, browse trending tokens
## Usage Examples
### Kline
```bash
# Last 1 hour of 1-minute candles
# macOS:
@@ -73,22 +104,210 @@ gmgn-cli market kline \
--to $(date +%s)
# Linux: use $(date -d '24 hours ago' +%s) instead of $(date -v-24H +%s)
# Raw output for further processing
gmgn-cli market kline --chain sol --address <addr> \
--resolution 5m --from <ts> --to <ts> --raw | jq '.[]'
```
### Trending — General
```bash
# Top 20 hot tokens on SOL in the last 1 hour, sorted by volume
gmgn-cli market trending --chain sol --interval 1h --order-by volume --limit 20
# Top 50 tokens on SOL, 5m window, sorted by volume
gmgn-cli market trending --chain sol --interval 5m --order-by volume --limit 50
# Hot tokens with social links only, verified and not honeypot, on BSC over 24h
gmgn-cli market trending \
--chain bsc --interval 24h \
--filter has_social --filter not_honeypot --filter verified
# Pump.fun platform tokens on SOL, last 6 hours
gmgn-cli market trending --chain sol --interval 6h --platform Pump.fun
# Raw output for further processing
gmgn-cli market kline --chain sol --address <addr> \
--resolution 5m --from <ts> --to <ts> --raw | jq '.[]'
```
### Trending — SOL by Launchpad Platform
Use `--platform` to filter trending results to tokens from specific launchpads only.
```bash
# SOL 1m hottest — Pump.fun + letsbonk only (most active launchpads), sorted by volume
gmgn-cli market trending \
--chain sol --interval 1m \
--platform Pump.fun --platform letsbonk \
--order-by volume --limit 50 --raw
# SOL 5m hottest — Pump.fun + letsbonk + Moonshot, sorted by volume
gmgn-cli market trending \
--chain sol --interval 5m \
--platform Pump.fun --platform letsbonk --platform moonshot_app \
--order-by volume --limit 50 --raw
# SOL 1h trending — Pump.fun only, with safety filters
gmgn-cli market trending \
--chain sol --interval 1h \
--platform Pump.fun \
--filter renounced --filter frozen --filter not_wash_trading \
--order-by volume --limit 20 --raw
# SOL 1h trending — all major launchpads combined
gmgn-cli market trending \
--chain sol --interval 1h \
--platform Pump.fun --platform letsbonk --platform moonshot_app \
--platform pump_mayhem --platform pump_mayhem_agent --platform bonkers \
--order-by volume --limit 50 --raw
```
### Trending — BSC by Launchpad Platform
```bash
# BSC 1m hottest — fourmeme (main BSC launchpad), sorted by volume
gmgn-cli market trending \
--chain bsc --interval 1m \
--platform fourmeme --platform four_xmode_agent \
--order-by volume --limit 50 --raw
# BSC 5m hottest — fourmeme family, sorted by volume
gmgn-cli market trending \
--chain bsc --interval 5m \
--platform fourmeme --platform fourmeme_agent --platform bn_fourmeme --platform four_xmode_agent \
--order-by volume --limit 50 --raw
# BSC 1h trending — fourmeme with safety filters
gmgn-cli market trending \
--chain bsc --interval 1h \
--platform fourmeme --platform fourmeme_agent --platform bn_fourmeme --platform four_xmode_agent \
--filter not_honeypot --filter verified \
--order-by volume --limit 20 --raw
```
### Trending — Base by Launchpad Platform
```bash
# Base 1m hottest — clanker + zora (main Base launchpads), sorted by volume
gmgn-cli market trending \
--chain base --interval 1m \
--platform clanker --platform zora --platform zora_creator \
--order-by volume --limit 50 --raw
# Base 5m hottest — clanker + zora + virtuals_v2 + flaunch, sorted by volume
gmgn-cli market trending \
--chain base --interval 5m \
--platform clanker --platform zora --platform zora_creator \
--platform virtuals_v2 --platform flaunch \
--order-by volume --limit 50 --raw
# Base 1h trending — all major launchpads with safety filters
gmgn-cli market trending \
--chain base --interval 1h \
--platform clanker --platform zora --platform zora_creator \
--platform virtuals_v2 --platform flaunch --platform baseapp \
--filter not_honeypot --filter verified \
--order-by volume --limit 20 --raw
```
## `market trending` Response Fields
The response is `data.rank` — an array of rank items. Each item represents one token.
**Basic Info**
| Field | Description |
|-------|-------------|
| `address` | Token contract address |
| `symbol` / `name` | Token ticker and full name |
| `logo` | Token logo image URL |
| `chain` | Chain identifier |
| `total_supply` | Total token supply |
| `creator` | Creator wallet address |
| `launchpad_platform` | Launch/pool platform (e.g. `Pump.fun`, `letsbonk`, `pool_meteora`, `fourmeme`) |
| `exchange` | Current DEX (e.g. `meteora_damm_v2`, `raydium`, `pump_amm`) |
| `open_timestamp` | Open market listing time (Unix seconds) |
| `creation_timestamp` | Token creation time (Unix seconds) |
| `rank` | Position in this trending list (lower = hotter) |
| `hot_level` | Trending intensity level (higher = hotter) |
**Price & Market**
| Field | Description |
|-------|-------------|
| `price` | Current price in USD |
| `market_cap` | Market cap in USD (directly available — no calculation needed) |
| `liquidity` | Current liquidity in USD |
| `volume` | Trading volume in USD for the queried interval |
| `history_highest_market_cap` | All-time highest market cap in USD |
| `initial_liquidity` | Initial liquidity at token launch |
| `price_change_percent` | Price change % for the queried interval |
| `price_change_percent1m` | Price change % in last 1 minute |
| `price_change_percent5m` | Price change % in last 5 minutes |
| `price_change_percent1h` | Price change % in last 1 hour |
**Trading Activity**
| Field | Description |
|-------|-------------|
| `swaps` | Total swap count in the queried interval |
| `buys` / `sells` | Buy / sell count in the interval |
| `holder_count` | Number of unique token holders |
| `gas_fee` | Average gas fee per transaction |
**Security & Risk**
| Field | Chains | Description |
|-------|--------|-------------|
| `renounced_mint` | SOL | Mint authority renounced (`1` = yes, `0` = no) |
| `renounced_freeze_account` | SOL | Freeze authority renounced (`1` = yes, `0` = no) |
| `is_honeypot` | BSC / Base | Honeypot flag (`1` = yes, `0` = no) |
| `is_open_source` | all | Contract verified (`1` = yes, `0` = no) |
| `is_renounced` | all | Ownership renounced (`1` = yes, `0` = no) |
| `buy_tax` / `sell_tax` | all | Tax rate — empty string means `0` (no tax) |
| `burn_status` | all | Liquidity burn status (e.g. `"none"`, `"burn"`) |
| `top_10_holder_rate` | all | Top 10 wallets concentration (0–1) |
| `rug_ratio` | all | Rug pull risk score (0–1) |
| `is_wash_trading` | all | Wash trading detected (`true` / `false`) |
| `rat_trader_amount_rate` | all | Ratio of insider/sneak trading volume |
| `bundler_rate` | all | Ratio of bundle bot trading volume |
| `entrapment_ratio` | all | Entrapment trading ratio |
| `sniper_count` | all | Number of sniper wallets at launch |
| `bot_degen_count` / `bot_degen_rate` | all | Bot degen wallet count / ratio |
| `dev_team_hold_rate` | all | Dev team holding ratio |
| `top70_sniper_hold_rate` | all | Top 70 sniper current holding ratio |
| `lock_percent` | all | Liquidity lock percentage |
**Dev Status**
| Field | Description |
|-------|-------------|
| `creator_token_status` | Dev holding status: `creator_hold` (still holding) / `creator_close` (sold/closed) |
| `creator_close` | Boolean shorthand for `creator_token_status == creator_close` |
| `dev_token_burn_ratio` | Ratio of dev's tokens that have been burned |
**Smart Money**
| Field | Description |
|-------|-------------|
| `smart_degen_count` | Number of smart money wallets holding the token |
| `renowned_count` | Number of renowned / KOL wallets holding the token |
| `bluechip_owner_percentage` | Ratio of holders that are bluechip wallets (0–1) |
**Social**
| Field | Description |
|-------|-------------|
| `twitter_username` | Twitter / X username (not a full URL — prepend `https://x.com/` to get the link) |
| `website` | Project website URL |
| `telegram` | Telegram URL |
| `cto_flag` | Community takeover flag (`1` = CTO has occurred) |
**Dexscreener Marketing**
| Field | Description |
|-------|-------------|
| `dexscr_ad` | Dexscreener ad placed (`1` = yes) |
| `dexscr_update_link` | Social links updated on Dexscreener (`1` = yes) |
| `dexscr_trending_bar` | Paid for Dexscreener trending bar (`1` = yes) |
| `dexscr_boost_fee` | Dexscreener boost amount paid (0 = none) |
---
## Workflow: Discover Trading Opportunities via Trending
### Step 1 — Fetch trending data
@@ -136,7 +355,16 @@ For each token, offer:
- **Deep dive**: `token info` + `token security` for full due diligence
- **Swap**: execute directly if the user is satisfied with the trending data alone
## Trenches Parameters
## `market trenches` Parameters
**Intent → `--type` mapping (always specify `--type` explicitly):**
| User intent | `--type` value |
|-------------|----------------|
| "new tokens", "just launched", "newly created", "latest tokens" | `new_creation` |
| "about to graduate", "near completion", "bonding curve almost full" | `near_completion` |
| "graduated tokens", "already on DEX", "open market tokens" | `completed` |
| No specific stage mentioned | omit `--type` (returns all three) |
| Parameter | Required | Description |
|-----------|----------|-------------|
@@ -147,7 +375,7 @@ For each token, offer:
Response fields: `data.new_creation`, `data.pump`, `data.completed` — each is an array of `RankItem` (same fields as `market trending` rank items). **Important: `data.pump` in the response corresponds to `--type near_completion` in the request. The API always returns this category under the key `pump`, not `near_completion`.**
### Response Item Key Reference
## `market trenches` Response Fields
**Basic Info**
skills/gmgn-portfolio/SKILL.md
+5 -5
View File
@@ -72,7 +72,7 @@ gmgn-cli portfolio token-balance \
--chain sol --wallet <wallet_address> --token <token_address>
```
## Holdings Options
## `portfolio holdings` Options
| Option | Description |
|--------|-------------|
@@ -87,7 +87,7 @@ gmgn-cli portfolio token-balance \
| `--hide-closed` | Hide closed positions |
| `--hide-open` | Hide open positions |
## Activity Options
## `portfolio activity` Options
| Option | Description |
|--------|-------------|
@@ -98,13 +98,13 @@ gmgn-cli portfolio token-balance \
The activity response includes a `next` field. Pass it to `--cursor` to fetch the next page.
## Stats Options
## `portfolio stats` Options
| Option | Description |
|--------|-------------|
| `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |
## Follow-Wallet Options
## `portfolio follow-wallet` Options
| Option | Description |
|--------|-------------|
@@ -122,7 +122,7 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
| `--max-amount-usd <n>` | Maximum trade amount (USD) |
| `--is-gray` | Gray mode filter |
## KOL / Smart Money Options
## `portfolio kol` / `portfolio smartmoney` Options
| Option | Description |
|--------|-------------|
skills/gmgn-swap/SKILL.md
+6 -6
View File
@@ -55,7 +55,7 @@ npm install -g gmgn-cli@1.1.0
- `GMGN_PRIVATE_KEY` is used exclusively for **local message signing** — the private key never leaves the machine. The CLI computes an Ed25519 or RSA-SHA256 signature in-process and transmits only the base64-encoded result in the `X-Signature` request header.
- `GMGN_API_KEY` is transmitted in the `X-APIKEY` request header to GMGN's servers over HTTPS.
## Swap Usage
## `swap` Usage
```bash
# Basic swap
@@ -102,7 +102,7 @@ gmgn-cli swap \
--percent 50
```
## Quote Usage
## `order quote` Usage
Get an estimated output amount before submitting a swap. Uses normal auth — no private key required.
@@ -116,7 +116,7 @@ gmgn-cli order quote \
--slippage 0.01
```
### Quote Response Fields
### `order quote` Response Fields
| Field | Type | Description |
|-------|------|-------------|
@@ -127,13 +127,13 @@ gmgn-cli order quote \
| `min_output_amount` | string | Minimum output after slippage |
| `slippage` | number | Actual slippage percentage |
## Order Query
## `order get` Usage
```bash
gmgn-cli order get --chain sol --order-id <order_id>
```
## Swap Parameters
## `swap` Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
@@ -154,7 +154,7 @@ gmgn-cli order get --chain sol --order-id <order_id>
| `--max-fee-per-gas <n>` | No | EIP-1559 max fee per gas (Base only) |
| `--max-priority-fee-per-gas <n>` | No | EIP-1559 max priority fee per gas (Base only) |
## Swap Response Fields
## `swap` Response Fields
| Field | Type | Description |
|-------|------|-------------|
skills/gmgn-token/SKILL.md
+372 -32
View File
@@ -1,7 +1,7 @@
---
name: gmgn-token
description: Query GMGN token information — basic info, security, pool, top holders and top traders. Supports sol / bsc / base.
argument-hint: <sub-command> --chain <sol|bsc|base> --address <token_address>
argument-hint: "<sub-command> --chain <sol|bsc|base> --address <token_address>"
---
Use the `gmgn-cli` tool to query token information based on the user's request.
@@ -10,11 +10,11 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
| Sub-command | Description |
|-------------|-------------|
| `token info` | Basic info + realtime price |
| `token security` | Security metrics (holder concentration, contract risks) |
| `token pool` | Liquidity pool info |
| `token holders` | Top token holders list |
| `token traders` | Top token traders list |
| `token info` | Basic info + realtime price, liquidity, supply, holder count, social links (market cap = price × circulating_supply) |
| `token security` | Security metrics (honeypot, taxes, holder concentration, contract risks) |
| `token pool` | Liquidity pool info (DEX, reserves, liquidity depth) |
| `token holders` | Top token holders list with profit/loss breakdown |
| `token traders` | Top token traders list with profit/loss breakdown |
## Supported Chains
@@ -26,48 +26,388 @@ Use the `gmgn-cli` tool to query token information based on the user's request.
- Run from the directory where your `.env` file is located, or set `GMGN_HOST` in your environment
- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
## Info / Security / Pool Options
## Parameters — `token info` / `token security` / `token pool`
| Option | Description |
|--------|-------------|
| `--chain` | Required. `sol` / `bsc` / `base` |
| `--address` | Required. Token contract address |
| Parameter | Required | Description |
|-----------|----------|-------------|
| `--chain` | Yes | `sol` / `bsc` / `base` |
| `--address` | Yes | Token contract address |
| `--raw` | No | Output raw single-line JSON (for piping or further processing) |
## Holders / Traders Options
## Parameters — `token holders` / `token traders`
| Option | Description |
|--------|-------------|
| `--chain` | Required. `sol` / `bsc` / `base` |
| `--address` | Required. Token contract address |
| `--limit <n>` | Number of results (default `20`, max `100`) |
| `--order-by <field>` | Sort field: `amount_percentage` / `profit` / `unrealized_profit` / `buy_volume_cur` / `sell_volume_cur` (default `amount_percentage`) |
| `--direction <asc\|desc>` | Sort direction (default `desc`) |
| `--tag <tag>` | Wallet tag filter: `renowned` / `smart_degen` (default `renowned`) |
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--chain` | Yes | — | `sol` / `bsc` / `base` |
| `--address` | Yes | — | Token contract address |
| `--limit` | No | `20` | Number of results, max `100` |
| `--order-by` | No | `amount_percentage` | Sort field — see table below |
| `--direction` | No | `desc` | Sort direction: `asc` / `desc` |
| `--tag` | No | `renowned` | Wallet filter: `renowned` (KOL wallets) / `smart_degen` (smart money) |
| `--raw` | No | — | Output raw single-line JSON |
### `--order-by` Values
| Value | Description |
|-------|-------------|
| `amount_percentage` | Sort by percentage of total supply held (default) |
| `profit` | Sort by realized profit in USD |
| `unrealized_profit` | Sort by unrealized profit in USD |
| `buy_volume_cur` | Sort by buy volume |
| `sell_volume_cur` | Sort by sell volume |
### `--tag` Values
| Value | Description |
|-------|-------------|
| `renowned` | KOL / well-known wallets (influencers, funds, public figures) |
| `smart_degen` | Smart money wallets (historically high-performing traders) |
## Response Field Reference
### `token info` — Key Fields
The response has four nested objects: `pool`, `link`, `stat`, `wallet_tags_stat`. Access fields with dot notation when parsing (e.g. `link.website`, `stat.top_10_holder_rate`).
**Top-level Fields**
| Field | Description |
|-------|-------------|
| `address` | Token contract address |
| `symbol` / `name` | Token ticker and full name |
| `decimals` | Token decimal places |
| `total_supply` | Total token supply (same as `circulating_supply` for most tokens) |
| `circulating_supply` | Circulating supply |
| `max_supply` | Maximum supply |
| `price` | Current price in USD |
| `liquidity` | Total liquidity in USD (from biggest pool) |
| `holder_count` | Number of unique token holders |
| `logo` | Token logo image URL |
| `creation_timestamp` | Token creation time (Unix seconds) |
| `open_timestamp` | Time the token opened for trading (Unix seconds) |
| `biggest_pool_address` | Address of the main liquidity pool |
| `og` | Whether the token is flagged as an OG token (`true` / `false`) |
**`pool` Object** — Main liquidity pool details
| Field | Description |
|-------|-------------|
| `pool.pool_address` | Pool contract address |
| `pool.quote_address` | Quote token address (e.g. USDC, SOL, WETH) |
| `pool.quote_symbol` | Quote token symbol (e.g. `USDC`, `SOL`) |
| `pool.exchange` | DEX name (e.g. `meteora_dlmm`, `raydium`, `pump_amm`, `uniswap_v3`) |
| `pool.liquidity` | Pool liquidity in USD |
| `pool.base_reserve` | Base token reserve amount |
| `pool.quote_reserve` | Quote token reserve amount |
| `pool.base_reserve_value` | Base reserve USD value |
| `pool.quote_reserve_value` | Quote reserve USD value |
| `pool.fee_ratio` | Pool trading fee ratio (e.g. `0.1` = 0.1%) |
| `pool.creation_timestamp` | Pool creation time (Unix seconds) |
**`link` Object** — Social and explorer links
| Field | Description |
|-------|-------------|
| `link.twitter_username` | Twitter / X username (not full URL) |
| `link.website` | Project website URL |
| `link.telegram` | Telegram URL |
| `link.discord` | Discord URL |
| `link.instagram` | Instagram URL |
| `link.tiktok` | TikTok URL |
| `link.youtube` | YouTube URL |
| `link.description` | Token description text |
| `link.gmgn` | GMGN token page URL |
| `link.geckoterminal` | GeckoTerminal page URL |
| `link.verify_status` | Social verification status (integer) |
**`stat` Object** — On-chain statistics
| Field | Description |
|-------|-------------|
| `stat.holder_count` | Number of holders (same as top-level `holder_count`) |
| `stat.bluechip_owner_count` | Number of bluechip wallet holders |
| `stat.bluechip_owner_percentage` | Ratio of holders that are bluechip wallets (0–1) |
| `stat.top_10_holder_rate` | Ratio of supply held by top 10 wallets (0–1) |
| `stat.dev_team_hold_rate` | Ratio held by dev team wallets |
| `stat.creator_hold_rate` | Ratio held by creator wallet |
| `stat.creator_token_balance` | Raw creator token balance |
| `stat.top_rat_trader_percentage` | Ratio of volume from rat/insider traders |
| `stat.top_bundler_trader_percentage` | Ratio of volume from bundler bots |
| `stat.top_entrapment_trader_percentage` | Ratio of volume from entrapment traders |
| `stat.bot_degen_count` | Number of bot degen wallets |
| `stat.bot_degen_rate` | Ratio of bot degen wallets |
| `stat.fresh_wallet_rate` | Ratio of fresh/new wallets among holders |
**`wallet_tags_stat` Object** — Wallet type breakdown
| Field | Description |
|-------|-------------|
| `wallet_tags_stat.smart_wallets` | Number of smart money wallets holding the token |
| `wallet_tags_stat.renowned_wallets` | Number of renowned / KOL wallets holding the token |
| `wallet_tags_stat.sniper_wallets` | Number of sniper wallets |
| `wallet_tags_stat.rat_trader_wallets` | Number of rat trader wallets |
| `wallet_tags_stat.bundler_wallets` | Number of bundler bot wallets |
| `wallet_tags_stat.whale_wallets` | Number of whale wallets |
| `wallet_tags_stat.fresh_wallets` | Number of fresh wallets |
| `wallet_tags_stat.top_wallets` | Number of top-ranked wallets |
---
### `token security` — Key Fields
**Contract Safety**
| Field | Chains | Description |
|-------|--------|-------------|
| `is_honeypot` | BSC / Base | Whether token is a honeypot (`"yes"` / `"no"`); empty string on SOL |
| `open_source` | all | Contract source code verified: `"yes"` / `"no"` / `"unknown"` |
| `owner_renounced` | all | Contract ownership renounced: `"yes"` / `"no"` / `"unknown"` |
| `renounced_mint` | SOL | Mint authority renounced (SOL-specific; always `false` on EVM) |
| `renounced_freeze_account` | SOL | Freeze authority renounced (SOL-specific; always `false` on EVM) |
| `buy_tax` / `sell_tax` | all | Tax ratio — e.g. `0.03` = 3%; `0` = no tax |
**Holder Concentration & Risk**
| Field | Description |
|-------|-------------|
| `top_10_holder_rate` | Ratio of supply held by top 10 wallets (0–1); higher = more concentrated |
| `dev_team_hold_rate` | Ratio held by dev team wallets |
| `creator_balance_rate` | Ratio held by the token creator wallet |
| `creator_token_status` | Dev holding status: `creator_hold` (still holding) / `creator_close` (sold/closed) |
| `suspected_insider_hold_rate` | Ratio held by suspected insider wallets |
**Trading Risk**
| Field | Description |
|-------|-------------|
| `rug_ratio` | Rug pull risk score (0–1); higher = more risky |
| `is_wash_trading` | Whether wash trading activity is detected (`true` / `false`) |
| `rat_trader_amount_rate` | Ratio of volume from sneak/insider trading |
| `bundler_trader_amount_rate` | Ratio of volume from bundle trading (bot-driven) |
| `sniper_count` | Number of sniper wallets that bought at launch |
| `burn_status` | Liquidity pool burn status (e.g. `"burn"` = burned, `""` = not burned) |
---
### `token pool` — Key Fields
| Field | Description |
|-------|-------------|
| `address` | Pool contract address |
| `base_address` | Base token address (the queried token) |
| `quote_address` | Quote token address (e.g. SOL, USDC, WETH) |
| `exchange` | DEX name (e.g. `raydium`, `pump_amm`, `uniswap_v3`, `pancakeswap`) |
| `liquidity` | Pool liquidity in USD |
| `base_reserve` | Base token reserve amount |
| `quote_reserve` | Quote token reserve amount |
| `price` | Current price in USD derived from pool reserves |
| `creation_timestamp` | Pool creation time (Unix seconds) |
---
### `token holders` / `token traders` — Item Fields
Each item in the result array:
| Field | Description |
|-------|-------------|
| `address` | Wallet address |
| `name` | Wallet label or alias (if known) |
| `tags` | Wallet tags (e.g. `["renowned"]`, `["smart_degen"]`) |
| `amount_percentage` | Percentage of total supply held (0–1); e.g. `0.05` = 5% |
| `amount` | Raw token amount held |
| `value` | USD value of holdings |
| `profit` | Realized profit in USD (positive = profit, negative = loss) |
| `unrealized_profit` | Unrealized profit in USD based on current price |
| `buy_volume_cur` | Total buy volume in USD for the current period |
| `sell_volume_cur` | Total sell volume in USD for the current period |
| `profit_change` | Profit change ratio |
---
## Usage Examples
### `token info` — Fetch Basic Info and Price
```bash
# Basic token info
gmgn-cli token info --chain sol --address <token_address>
# Get current price and market cap for a SOL token
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Security metrics
gmgn-cli token security --chain sol --address <token_address>
# Get basic info for a BSC token
gmgn-cli token info --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8
# Liquidity pool
gmgn-cli token pool --chain sol --address <token_address>
# Get basic info for a Base token
gmgn-cli token info --chain base --address 0x4200000000000000000000000000000000000006
# Top holders
gmgn-cli token holders --chain sol --address <token_address> --limit 50
# Raw JSON output for downstream processing
gmgn-cli token info --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --raw
```
# Top traders
gmgn-cli token traders --chain sol --address <token_address> --limit 50
### `token security` — Check Safety Before Buying
# Raw JSON output (for piping)
```bash
# Check if a SOL token has renounced mint + freeze authority
gmgn-cli token security --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Check if a BSC token is honeypot and whether contract is verified
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8
# Check a Base token for tax, rug ratio, and insider concentration
gmgn-cli token security --chain base --address 0x4200000000000000000000000000000000000006
# Raw output for parsing key fields (e.g. is_honeypot, buy_tax, rug_ratio)
gmgn-cli token security --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 --raw
```
### `token pool` — Check Liquidity Depth
```bash
# Get pool info for a SOL token (liquidity, reserves, DEX)
gmgn-cli token pool --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Get pool info for a BSC token
gmgn-cli token pool --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8
```
### `token holders` — Analyze Holder Distribution
```bash
# Top 20 holders by supply percentage (default)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Top 50 holders sorted by percentage held
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--limit 50 --order-by amount_percentage --direction desc
# Top 50 smart money holders (highest conviction wallets)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--limit 50 --tag smart_degen --order-by amount_percentage
# Top KOL wallets ranked by realized profit (who has already taken profit)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag renowned --order-by profit --direction desc --limit 20
# Smart money with most unrealized profit (who is sitting on biggest gains)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag smart_degen --order-by unrealized_profit --direction desc --limit 20
# Holders who have been buying the most recently (buy momentum signal)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag smart_degen --order-by buy_volume_cur --direction desc --limit 20
# Holders who are selling the most (exit signal / distribution warning)
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag renowned --order-by sell_volume_cur --direction desc --limit 20
# BSC token holders — KOL wallets by profit
gmgn-cli token holders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
--tag renowned --order-by profit --direction desc --limit 50
# Raw output for downstream analysis
gmgn-cli token holders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--limit 100 --raw
```
### `token traders` — Find Active Traders
```bash
# Top 20 active traders by supply held (default)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Smart money traders ranked by realized profit
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag smart_degen --order-by profit --direction desc --limit 50
# KOL traders ranked by unrealized profit (still holding with paper gains)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag renowned --order-by unrealized_profit --direction desc --limit 20
# Smart money traders with highest buy volume (aggressive accumulation)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag smart_degen --order-by buy_volume_cur --direction desc --limit 20
# Smart money traders ranked by sell volume (who is distributing)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag smart_degen --order-by sell_volume_cur --direction desc --limit 20
# Worst performing KOL traders (who lost the most — contrarian signal)
gmgn-cli token traders --chain sol --address EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--tag renowned --order-by profit --direction asc --limit 20
# BSC token traders by profit
gmgn-cli token traders --chain bsc --address 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 \
--tag smart_degen --order-by profit --direction desc --limit 50
```
---
## Workflow: Full Token Due Diligence
Use this workflow before deciding to buy a token.
### Step 1 — Get basic info
```bash
gmgn-cli token info --chain sol --address <token_address> --raw
```
Check: `price`, `liquidity`, `holder_count`, `wallet_tags_stat.smart_wallets`, `wallet_tags_stat.renowned_wallets`, `link.website` / `link.twitter_username` / `link.telegram`.
**Red flags**: all `link.*` social fields empty, very low liquidity (<$10k), zero `wallet_tags_stat.smart_wallets` and `renowned_wallets`.
### Step 2 — Check security
```bash
gmgn-cli token security --chain sol --address <token_address> --raw
```
Check these fields and their safe thresholds:
| Field | Safe | Warning | Danger |
|-------|------|---------|--------|
| `is_honeypot` | `"no"` | — | `"yes"` → Do not buy |
| `open_source` | `"yes"` | `"unknown"` | `"no"` |
| `owner_renounced` | `"yes"` | `"unknown"` | `"no"` |
| `renounced_mint` (SOL) | `true` | — | `false` → mint risk |
| `renounced_freeze_account` (SOL) | `true` | — | `false` → freeze risk |
| `buy_tax` / `sell_tax` | `0` | `0.01–0.05` | `>0.10` → high tax |
| `top_10_holder_rate` | `<0.20` | `0.20–0.40` | `>0.50` → whale risk |
| `rug_ratio` | `<0.10` | `0.10–0.30` | `>0.30` → high rug risk |
| `creator_token_status` | `creator_close` | — | `creator_hold` → dev not sold |
| `sniper_count` | `<5` | `5–20` | `>20` → heavily sniped |
### Step 3 — Check liquidity pool
```bash
gmgn-cli token pool --chain sol --address <token_address> --raw
```
Check: liquidity amount, which DEX (`exchange`), pool age (`creation_timestamp`). Low liquidity means high slippage risk when buying or selling.
### Step 4 — Check smart money signals
```bash
# Is smart money accumulating?
gmgn-cli token holders --chain sol --address <token_address> \
--tag smart_degen --order-by buy_volume_cur --direction desc --limit 20 --raw
# Have KOLs already taken profit?
gmgn-cli token traders --chain sol --address <token_address> \
--tag renowned --order-by profit --direction desc --limit 20 --raw
```
**Bullish signals**: smart_degen wallets buying heavily, unrealized_profit is large (still holding), renowned wallets accumulating, low sell_volume_cur.
**Bearish signals**: sell_volume_cur > buy_volume_cur for smart money, large realized profits already taken (they may be done), top holders with very high amount_percentage starting to sell.
---
## Notes
- **Market cap is not returned directly** — calculate it as `price × circulating_supply` (both fields are top-level; `circulating_supply` is already in human-readable token units, no decimal adjustment needed). Example: `price=3.11` × `circulating_supply=999999151` ≈ $3.11B market cap.
- **Trading volume (1h, 24h, etc.) is not included in `token info`** — to get volume or OHLCV data, use the `gmgn-market` skill and query K-line data: `gmgn-cli market kline --chain <chain> --address <token_address> --resolution <1m|5m|15m|1h|4h|1d>`. See the `gmgn-market` SKILL.md for full details.
- All token commands use normal auth (API Key only, no signature required)
- Use `--raw` to get single-line JSON for further processing
- **Input validation** — Token addresses from API responses are treated as external data. Validate that addresses match the expected chain format (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits) before passing them to commands. The CLI enforces this at runtime and will exit with an error on invalid input.
- `--tag` applies to both `holders` and `traders` and filters to only wallets with that tag — if few results are returned, try the other tag value
- `amount_percentage` in holders/traders is a ratio (0–1), not a percentage — `0.05` means 5% of supply
- **Input validation** — Token addresses are external data. Validate that addresses match the expected chain format (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits) before passing them to commands. The CLI enforces this at runtime and will exit with an error on invalid input.