Gmgn Portfolio

1---2name: gmgn-portfolio3description: 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, or Base. 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.4argument-hint: "<info|holdings|activity|stats|token-balance|created-tokens> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"5metadata:6  cliHelp: "gmgn-cli portfolio --help"7---8 9**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.**10 11**⚠️ 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."**12 13Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.14 15**For full wallet analysis (holdings + stats + activity + verdict), follow [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)**16 17## Core Concepts18 19- **`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."20 21- **`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.22 23- **`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.24 25- **`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.26 27- **`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.28 29- **`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.30 31- **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.32 33## Sub-commands34 35| Sub-command | Description |36|-------------|-------------|37| `portfolio info` | Wallets and main currency balances bound to the API Key |38| `portfolio holdings` | Wallet token holdings with P&L |39| `portfolio activity` | Transaction history |40| `portfolio stats` | Trading statistics (supports batch) |41| `portfolio token-balance` | Token balance for a specific token |42| `portfolio created-tokens` | Tokens created by a developer wallet, with market cap and ATH info |43 44## Supported Chains45 46`sol` / `bsc` / `base`47 48## Prerequisites49 50- `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`51- `GMGN_API_KEY` configured in `~/.config/gmgn/.env`52 53## Rate Limit Handling54 55All portfolio routes used by this skill go through GMGN's leaky-bucket limiter with `rate=10` and `capacity=10`. Sustained throughput is roughly `10 ÷ weight` requests/second, and the max burst is roughly `floor(10 ÷ weight)` when the bucket is full.56 57| Command | Route | Weight |58|---------|-------|--------|59| `portfolio info` | `GET /v1/user/info` | 1 |60| `portfolio holdings` | `GET /v1/user/wallet_holdings` | 2 |61| `portfolio activity` | `GET /v1/user/wallet_activity` | 3 |62| `portfolio stats` | `GET /v1/user/wallet_stats` | 3 |63| `portfolio token-balance` | `GET /v1/user/wallet_token_balance` | 1 |64| `portfolio created-tokens` | `GET /v1/user/created_tokens` | 2 |65 66When a request returns `429`:67 68- Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.69- 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.70- 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 retry time instead of sending more requests.71- For `RATE_LIMIT_EXCEEDED` or `RATE_LIMIT_BANNED`, repeated requests during the cooldown can extend the ban by 5 seconds each time, up to 5 minutes. Do not spam retries.72 73**First-time setup** (if `GMGN_API_KEY` is not configured):74 751. Generate key pair and show the public key to the user:76   ```bash77   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \78     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null79   ```80   Tell the user: *"This is your Ed25519 public key. Go to **https://gmgn.ai/ai**, paste it into the API key creation form, then send me the API Key value shown on the page."*81 822. Wait for the user's API key, then configure:83   ```bash84   mkdir -p ~/.config/gmgn85   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env86   chmod 600 ~/.config/gmgn/.env87   ```88 89## Usage Examples90 91```bash92# API Key wallet info (no --chain or --wallet needed)93gmgn-cli portfolio info94 95# Wallet holdings (default sort)96gmgn-cli portfolio holdings --chain sol --wallet <wallet_address>97 98# Holdings sorted by USD value, descending99gmgn-cli portfolio holdings \100  --chain sol --wallet <wallet_address> \101  --order-by usd_value --direction desc --limit 20102 103# Include sold-out positions104gmgn-cli portfolio holdings --chain sol --wallet <wallet_address> --sell-out105 106# Transaction activity107gmgn-cli portfolio activity --chain sol --wallet <wallet_address>108 109# Activity filtered by type110gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \111  --type buy --type sell112 113# Activity for a specific token114gmgn-cli portfolio activity --chain sol --wallet <wallet_address> \115  --token <token_address>116 117# Trading stats (default 7d)118gmgn-cli portfolio stats --chain sol --wallet <wallet_address>119 120# Trading stats for 30 days121gmgn-cli portfolio stats --chain sol --wallet <wallet_address> --period 30d122 123# Batch stats for multiple wallets124gmgn-cli portfolio stats --chain sol \125  --wallet <wallet_1> --wallet <wallet_2>126 127# Token balance128gmgn-cli portfolio token-balance \129  --chain sol --wallet <wallet_address> --token <token_address>130 131# Tokens created by a developer wallet132gmgn-cli portfolio created-tokens --chain sol --wallet <wallet_address>133 134# Created tokens sorted by all-time high market cap135gmgn-cli portfolio created-tokens \136  --chain sol --wallet <wallet_address> \137  --order-by token_ath_mc --direction desc138 139# Only migrated tokens140gmgn-cli portfolio created-tokens \141  --chain sol --wallet <wallet_address> --migrate-state migrated142```143 144## `portfolio created-tokens` Options145 146| Option | Description |147|--------|-------------|148| `--order-by <field>` | Sort field: `market_cap` / `token_ath_mc` |149| `--direction <asc\|desc>` | Sort direction (default `desc`) |150| `--migrate-state <state>` | Filter by migration status: `migrated` (graduated to DEX) / `non_migrated` (still on bonding curve) |151 152## `portfolio holdings` Options153 154| Option | Description |155|--------|-------------|156| `--limit <n>` | Page size (default `20`, max 50) |157| `--cursor <cursor>` | Pagination cursor |158| `--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`) |159| `--direction <asc\|desc>` | Sort direction (default `desc`) |160| `--hide-abnormal <bool>` | Hide abnormal positions: `true` / `false` (default: `false`) |161| `--hide-airdrop <bool>` | Hide airdrop positions: `true` / `false` (default: `true`) |162| `--hide-closed <bool>` | Hide closed positions: `true` / `false` (default: `true`) |163| `--hide-open` | Hide open positions |164 165## `portfolio activity` Options166 167| Option | Description |168|--------|-------------|169| `--token <address>` | Filter by token |170| `--limit <n>` | Page size |171| `--cursor <cursor>` | Pagination cursor (pass the `next` value from the previous response) |172| `--type <type>` | Repeatable: `buy` / `sell` / `add` / `remove` / `transfer` |173 174The activity response includes a `next` field. Pass it to `--cursor` to fetch the next page.175 176## `portfolio stats` Options177 178| Option | Description |179|--------|-------------|180| `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |181 182## Response Field Reference183 184### `portfolio holdings` — Key Fields185 186The response has a `holdings` array. Each item is one token position.187 188| Field | Description |189|-------|-------------|190| `token.address` | Token contract address |191| `token.symbol` / `token.name` | Token ticker and full name |192| `token.price` | Current token price in USD |193| `balance` | Current token balance (human-readable units) |194| `usd_value` | Current USD value of this position |195| `cost` | Total amount spent buying this token (USD) |196| `realized_profit` | Profit from completed sells (USD) |197| `unrealized_profit` | Profit on current unsold holdings at current price (USD) |198| `total_profit` | `realized_profit + unrealized_profit` (USD) |199| `profit_change` | Total profit ratio = `total_profit / cost` (e.g. `1.5` = +150%) |200| `avg_cost` | Average buy price per token (USD) |201| `buy_tx_count` | Number of buy transactions |202| `sell_tx_count` | Number of sell transactions |203| `last_active_timestamp` | Unix timestamp of the most recent transaction |204| `history_bought_cost` | Total USD spent buying (all-time) |205| `history_sold_income` | Total USD received from selling (all-time) |206 207### `portfolio activity` — Key Fields208 209The response has a `activities` array and a `next` cursor field for pagination.210 211| Field | Description |212|-------|-------------|213| `transaction_hash` | On-chain transaction hash |214| `type` | Transaction type: `buy` / `sell` / `add` / `remove` / `transfer` |215| `token.address` | Token contract address |216| `token.symbol` | Token ticker |217| `token_amount` | Token quantity in this transaction |218| `cost_usd` | USD value of this transaction |219| `price` | Token price in USD at time of transaction |220| `timestamp` | Unix timestamp of the transaction |221| `next` | Pagination cursor — pass to `--cursor` to fetch the next page |222 223### `portfolio stats` — Key Fields224 225The response is an object (or array for batch). Key fields:226 227| Field | Description |228|-------|-------------|229| `realized_profit` | Total realized profit over the period (USD) |230| `unrealized_profit` | Total unrealized profit on open positions (USD) |231| `winrate` | Win rate — ratio of profitable trades (0–1) |232| `total_cost` | Total amount spent buying in the period (USD) |233| `buy_count` | Number of buy transactions |234| `sell_count` | Number of sell transactions |235| `pnl` | Profit/loss ratio = `realized_profit / total_cost` |236 237The response also includes a `common` object when available (absent if the upstream identity service is unavailable):238 239| Field | Description |240|-------|-------------|241| `common.avatar` | Wallet avatar URL |242| `common.name` | Display name |243| `common.ens` | ENS domain (EVM chains only) |244| `common.tag` | Primary wallet tag |245| `common.tags` | All wallet tags (e.g. `["smart_money"]`) |246| `common.twitter_username` | Twitter handle |247| `common.twitter_name` | Twitter display name |248| `common.followers_count` | Twitter follower count |249| `common.is_blue_verified` | Twitter blue-verified badge |250| `common.follow_count` | Number of GMGN users following this wallet |251| `common.remark_count` | Number of GMGN users who have remarked this wallet |252| `common.created_token_count` | Tokens created by this wallet |253| `common.created_at` | Wallet creation time (Unix seconds) — records when the first funding transaction arrived; use this as the wallet's age indicator |254| `common.fund_from` | Funding source label |255| `common.fund_from_address` | Address that funded this wallet |256| `common.fund_amount` | Funding amount |257 258Use `common.tags` and `common.twitter_username` when building a wallet profile narrative. If `common` is absent in the response, omit identity fields silently — do not report it as an error.259 260### `portfolio created-tokens` — Key Fields261 262The response `data` object has a `tokens` array plus aggregate stats.263 264Top-level fields:265 266| Field | Description |267|-------|-------------|268| `last_create_timestamp` | Unix timestamp of the most recent token creation |269| `inner_count` | Number of tokens still on the bonding curve (NOT graduated) |270| `open_count` | Number of tokens that have graduated to DEX |271| `open_ratio` | Graduation rate (string, e.g. `"0.25"`) |272 273> **Total created = `inner_count + open_count`**. Do NOT use `len(tokens)` as the total — the `tokens` array is capped at 100 entries and may be truncated.274| `creator_ath_info` | Best-performing token created by this wallet (ATH market cap) |275| `tokens` | Array of created tokens — see below |276 277`creator_ath_info` fields:278 279| Field | Description |280|-------|-------------|281| `creator` | Wallet address |282| `ath_token` | Token address with highest ATH market cap |283| `ath_mc` | ATH market cap (USD string) |284| `token_symbol` / `token_name` | Token ticker and name |285| `token_logo` | Logo URL |286 287Per-token fields (`tokens[*]`):288 289| Field | Description |290|-------|-------------|291| `token_address` | Token contract address |292| `symbol` | Token ticker |293| `chain` | Chain name |294| `create_timestamp` | Unix timestamp of creation |295| `is_open` | `true` if graduated to DEX |296| `market_cap` | Current market cap (USD string) |297| `token_ath_mc` | All-time high market cap (USD string) |298| `pool_liquidity` | Current liquidity (USD string) |299| `holders` | Current holder count |300| `swap_1h` | Swap count in the last hour |301| `volume_1h` | Trading volume in the last hour (USD string) |302| `launchpad_platform` | Launch platform name (e.g. `Pump.fun`) |303| `is_pump` | `true` if launched on Pump.fun |304| `bundler_rate` | Bundler participation rate (0–1) |305| `cto_flag` | `true` if community-takeover token |306 307**Do NOT guess field names not listed here.** If a field appears in the response but is not in this table, do not interpret it without reading the raw output first.308 309## Output Format310 311**Do NOT dump raw JSON.** Always parse and present data in the structured formats below. Use `--raw` only when piping to `jq` or further processing.312 313### `portfolio holdings` — Holdings Table314 315Present a table sorted by `usd_value` (descending). Show total portfolio value at the top.316 317```318Wallet: {wallet} | Chain: {chain}319Total value: ~${sum of usd_value across all positions}320 321# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells322```323 324Flag positions where `profit_change` is strongly negative (e.g. < -50%) or positive (e.g. > 200%) with a brief note.325 326### `portfolio activity` — Activity Feed327 328Present as a chronological list (newest first). Use human-readable timestamps.329 330```331{type} {token.symbol}  |  {token_amount} tokens  |  ${cost_usd}  |  {timestamp}  |  tx: {short hash}332```333 334Group by token if the user asks about a specific token.335 336### `portfolio stats` — Stats Summary337 338```339Wallet: {wallet} | Period: {period}340Realized P&L:   ${realized_profit}341Unrealized P&L: ${unrealized_profit}342Win Rate:        {winrate × 100}%343Total Spent:     ${total_cost}344Buys / Sells:    {buy_count} / {sell_count}345PnL Ratio:       {pnl}x346[Identity:       {common.name or common.twitter_username} | Tags: {common.tags}]347```348 349Show the `[Identity: ...]` line only if `common` is present in the response. For batch queries (multiple wallets), present one summary block per wallet.350 351## Notes352 353- All portfolio commands use normal auth (API Key only, no signature required)354- `portfolio stats` supports multiple `--wallet` flags for batch queries355- Use `--raw` to get single-line JSON for further processing356- **Input validation** — Wallet and token addresses are validated against the expected chain format at runtime (sol: base58 32–44 chars; bsc/base/eth: `0x` + 40 hex digits). The CLI exits with an error on invalid input.357- For follow-wallet, KOL, and Smart Money trade records, use the `gmgn-track` skill (`track follow-wallet` / `track kol` / `track smartmoney`)358 359## Workflow360 361For full wallet analysis including trade history and follow-through on top holdings, see [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)362 363For in-depth trading style analysis, copy-trade ROI estimation, and smart money leaderboard comparison, see [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)364 365**When to use which:**366- User asks "is this wallet worth following" → [`docs/workflow-wallet-analysis.md`](../../docs/workflow-wallet-analysis.md)367- User asks "what's this wallet's trading style", "when does he take profit", "smart money profile", "if I copied this wallet what would my return be" → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md)368- User wants to compare multiple smart money wallets by winrate/PnL → [`docs/workflow-smart-money-profile.md`](../../docs/workflow-smart-money-profile.md) Step 5 (leaderboard)369- User asks "what tokens did this dev create", "dev 发过哪些币", "查一下这个 dev 的代币", "dev 创建记录" → use `portfolio created-tokens --chain <chain> --wallet <creator_address>` directly. Get the creator address first via `token info` if only a token address is given.