/gmgn-portfolio

name: gmgn-portfolio
description: Analyze any crypto wallet by address — holdings, realized/unrealized P&L, win rate, trading history, performance stats, specific token balance, and tokens created by a developer wallet (with ATH market cap and DEX graduation status) via GMGN API on Solana, BSC, Base, or Ethereum. Use when user asks about a wallet's holdings, P&L, win rate, what tokens a dev has launched, the highest ATH token a dev ever created, or wants a wallet report to decide whether to copy-trade or follow.
argument-hint: "<info|holdings|activity|stats|token-balance|created-tokens> [--chain <sol|bsc|base|eth|robinhood|arc|stable>] [--wallet <wallet_address>]"
metadata:
  cliHelp: "gmgn-cli portfolio --help"

**BEFORE RUNNING ANY COMMAND: Run `gmgn-cli config --check`. If exit code is 0, proceed normally. If exit code is 1, (1) run `gmgn-cli config` and show the output to the user; (2) once the user sends the API Key, run `gmgn-cli config --apply <KEY>` to complete configuration and verification, then show the output to the user. If `--check` returns an error (unknown option or command not found), tell the user to run `npm install -g gmgn-cli` to update, then retry.**

**IMPORTANT: Always use `gmgn-cli` commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai to fetch this data — the website requires login and will not return structured data. The CLI is the only correct method.**

**⚠️ IPv6 NOT SUPPORTED: If you get a `401` or `403` error and credentials look correct, check for IPv6 immediately: (1) list all network interfaces and their IPv6 addresses — run `ifconfig | grep inet6` (macOS) or `ip addr show | grep inet6` (Linux); (2) send a test request to `https://ipv6.icanhazip.com` — if the response is an IPv6 address, outbound traffic is going via IPv6. Tell the user immediately: "Please disable IPv6 on your network interface — gmgn-cli commands only work over IPv4."**

Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.

**For full wallet analysis (holdings + stats + activity + verdict), follow [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)**

Core Concepts

• **`realized_profit` vs `unrealized_profit`** — `realized_profit` = profit locked in from completed sells (cash in hand). `unrealized_profit` = paper gains on positions still held, calculated at current price. These are separate numbers — do not add them unless answering "total P&L including open positions."

• **`profit_change`** — A multiplier ratio, not a dollar amount. `1.5` = +150% return. `0` = break-even. `-0.5` = -50% loss. Computed as `total_profit / cost`. Do not display this as a raw decimal — convert to percentage for user-facing output.

• **`pnl`** — Profit/loss ratio from `portfolio stats`: `realized_profit / total_cost`. Same multiplier format as `profit_change`. A `pnl` of `2.0` means the wallet doubled its money on completed trades over the period.

• **`winrate`** — Ratio of profitable trades over the period (0–1). `0.6` = 60% of trades were profitable. Does not reflect the size of wins vs losses — a wallet can have high winrate but net negative if losses are large.

• **`cost` vs `usd_value`** — In holdings: `cost` is the historical amount spent buying this token (your cost basis); `usd_value` is the current market value of the position. The difference is unrealized P&L.

• **`history_bought_cost` vs `cost`** — `history_bought_cost` is the all-time cumulative spend on this token (including positions already sold). `cost` is the cost basis of the current open position only.

• **Pagination (`cursor`)** — Activity results are paginated. The response includes a `next` field; pass it as `--cursor` to fetch the next page. An empty or missing `next` means you are on the last page.

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 | | `portfolio created-tokens` | Tokens created by a developer wallet, with market cap and ATH info |

Supported Chains

`sol` / `bsc` / `base` / `eth` / `robinhood` / `arc` / `stable`

Prerequisites

• `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
• `GMGN_API_KEY` configured in `~/.config/gmgn/.env`

Rate Limit Handling

All portfolio routes used by this skill go through GMGN's leaky-bucket limiter with `rate=20` and `capacity=20`. Sustained throughput is roughly `20 ÷ weight` requests/second, and the max burst is roughly `floor(20 ÷ weight)` when the bucket is full.

**Critical auth** (`GMGN_API_KEY` + `GMGN_PRIVATE_KEY` required):

| Command | Route | Weight | |---------|-------|--------| | `portfolio holdings` | `GET /v1/user/wallet_holdings` | 5 |

**Exist auth** (`GMGN_API_KEY` only):

| Command | Route | Weight | |---------|-------|--------| | `portfolio info` | `GET /v1/user/info` | 1 | | `portfolio activity` | `GET /v1/user/wallet_activity` | 3 | | `portfolio stats` | `GET /v1/user/wallet_stats` | 3 | | `portfolio token-balance` | `GET /v1/user/wallet_token_balance` | 1 | | `portfolio created-tokens` | `GET /v1/user/created_tokens` | 2 |

When a request returns `429`:

• Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
• If the response body contains `reset_at` (e.g., `{"code":429,"error":"RATE_LIMIT_BANNED","message":"...","reset_at":1775184222}`), extract `reset_at` — it is the Unix timestamp when the ban lifts (typically 5 minutes). Convert to local time and tell the user exactly when they can retry.
• The CLI may wait and retry once automatically when the remaining cooldown is short. If it still fails, stop and tell the user the exact r