2026-03-13 18:57:50 +08:00
---
name: gmgn-portfolio
2026-03-25 22:20:56 +08:00
description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, token balance, follow-wallet trades, KOL trades, and Smart Money trades. Supports sol / bsc / base.
argument-hint: "<info|holdings|activity|stats|token-balance|follow-wallet|kol|smartmoney> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
2026-03-13 18:57:50 +08:00
---
Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
## Sub-commands
| Sub-command | Description |
|-------------|-------------|
| `portfolio info` | Wallets and main currency balances bound to the API Key |
| `portfolio holdings` | Wallet token holdings with P&L |
| `portfolio activity` | Transaction history |
| `portfolio stats` | Trading statistics (supports batch) |
| `portfolio token-balance` | Token balance for a specific token |
2026-03-25 22:20:56 +08:00
| `portfolio follow-wallet` | Follow-wallet trade records |
| `portfolio kol` | KOL trade records (SOL chain) |
| `portfolio smartmoney` | Smart Money trade records (SOL chain) |
2026-03-13 18:57:50 +08:00
## Supported Chains
`sol` / `bsc` / `base`
## Prerequisites
- `.env` file with `GMGN_API_KEY` set
- Run from the directory where your `.env` file is located, or set `GMGN_HOST` in your environment
2026-03-25 22:20:56 +08:00
- `gmgn-cli` installed globally: `npm install -g gmgn-cli@1.1.0`
2026-03-13 18:57:50 +08:00
## Usage Examples
```bash
# API Key wallet info (no --chain or --wallet needed)
gmgn-cli portfolio info
# Wallet holdings (default sort)
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address>
# Holdings sorted by USD value, descending
gmgn-cli portfolio holdings \
--chain sol --wallet <wallet_address> \
--order-by usd_value --direction desc --limit 20
# Include sold-out positions
gmgn-cli portfolio holdings --chain sol --wallet <wallet_address> --sell-out
# Transaction activity
gmgn-cli portfolio activity --chain sol --wallet <wallet_address>
# Activity filtered by type
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
--type buy --type sell
# Activity for a specific token
gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \
--token <token_address>
# Trading stats (default 7d)
gmgn-cli portfolio stats --chain sol --wallet <wallet_address>
# Trading stats for 30 days
gmgn-cli portfolio stats --chain sol --wallet <wallet_address> --period 30d
# Batch stats for multiple wallets
gmgn-cli portfolio stats --chain sol \
--wallet <wallet_1> --wallet <wallet_2>
# Token balance
gmgn-cli portfolio token-balance \
--chain sol --wallet <wallet_address> --token <token_address>
```
## Holdings Options
| Option | Description |
|--------|-------------|
| `--limit <n>` | Page size (default `20` , max 50) |
| `--cursor <cursor>` | Pagination cursor |
2026-03-17 14:44:24 +08:00
| `--order-by <field>` | Sort field: `usd_value` / `last_active_timestamp` / `realized_profit` / `unrealized_profit` / `total_profit` / `history_bought_cost` / `history_sold_income` (default `usd_value` ) |
2026-03-13 18:57:50 +08:00
| `--direction <asc\|desc>` | Sort direction (default `desc` ) |
| `--sell-out` | Include sold-out positions |
| `--show-small` | Include small-value positions |
| `--hide-abnormal` | Hide abnormal positions |
| `--hide-airdrop` | Hide airdrop positions |
| `--hide-closed` | Hide closed positions |
| `--hide-open` | Hide open positions |
## Activity Options
| Option | Description |
|--------|-------------|
| `--token <address>` | Filter by token |
| `--limit <n>` | Page size |
2026-03-17 14:44:24 +08:00
| `--cursor <cursor>` | Pagination cursor (pass the `next` value from the previous response) |
2026-03-13 18:57:50 +08:00
| `--type <type>` | Repeatable: `buy` / `sell` / `add` / `remove` / `transfer` |
2026-03-17 14:44:24 +08:00
The activity response includes a `next` field. Pass it to `--cursor` to fetch the next page.
2026-03-13 18:57:50 +08:00
## Stats Options
| Option | Description |
|--------|-------------|
| `--period <period>` | Stats period: `7d` / `30d` (default `7d` ) |
2026-03-25 22:20:56 +08:00
## Follow-Wallet Options
| Option | Description |
|--------|-------------|
| `--chain` | Required. `sol` / `bsc` / `base` / `eth` |
| `--wallet <address>` | Filter by wallet address |
| `--base-token <address>` | Filter by base token address |
| `--page-token <cursor>` | Pagination cursor |
| `--limit <n>` | Page size (1–
| `--side <side>` | Trade direction filter |
| `--cost <cost>` | Cost filter |
| `--filter <tag...>` | Repeatable filter conditions |
| `--with-balance` | Include balance in response |
| `--with-security` | Include security info in response |
| `--min-amount-usd <n>` | Minimum trade amount (USD) |
| `--max-amount-usd <n>` | Maximum trade amount (USD) |
| `--is-gray` | Gray mode filter |
## KOL / Smart Money Options
| Option | Description |
|--------|-------------|
| `--limit <n>` | Page size (1–
Both `kol` and `smartmoney` return SOL chain data only — no `--chain` flag needed.
```bash
# Follow-wallet trades filtered by wallet
gmgn-cli portfolio follow-wallet --chain sol --wallet <wallet_address>
# Follow-wallet with balance info
gmgn-cli portfolio follow-wallet --chain sol --with-balance --limit 20
# KOL trade records
gmgn-cli portfolio kol --limit 10 --raw
# Smart Money trade records
gmgn-cli portfolio smartmoney --limit 10 --raw
```
2026-03-13 18:57:50 +08:00
## Notes
- All portfolio commands use normal auth (API Key only, no signature required)
- `portfolio stats` supports multiple `--wallet` flags for batch queries
- Use `--raw` to get single-line JSON for further processing
- **Input validation** — Wallet and token addresses are validated against the expected chain format at runtime (sol: base58 32– `0x` + 40 hex digits). The CLI exits with an error on invalid input.
