gmgn-portfolio

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

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

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

Command	Route	Weight
portfolio info	GET /v1/user/info	1
portfolio holdings	GET /v1/user/wallet_holdings	2
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 retry time instead of sending more requests.
• 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.

First-time setup (if GMGN_API_KEY is not configured):

1. Generate key pair and show the public key to the user:

   openssl genpkey -algorithm ed25519 -out /tmp/gmgn_private.pem 2>/dev/null && \
     openssl pkey -in /tmp/gmgn_private.pem -pubout 2>/dev/null
   

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

2. Wait for the user's API key, then configure:

   mkdir -p ~/.config/gmgn
   echo 'GMGN_API_KEY=<key_from_user>' > ~/.config/gmgn/.env
   chmod 600 ~/.config/gmgn/.env
   

Usage Examples

# 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>

# Tokens created by a developer wallet
gmgn-cli portfolio created-tokens --chain sol --wallet <wallet_address>

# Created tokens sorted by all-time high market cap
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> \
  --order-by token_ath_mc --direction desc

# Only migrated tokens
gmgn-cli portfolio created-tokens \
  --chain sol --wallet <wallet_address> --migrate-state migrated

portfolio created-tokens Options

Option	Description
--order-by <field>	Sort field: market_cap / token_ath_mc
--direction <asc|desc>	Sort direction (default desc)
--migrate-state <state>	Filter by migration status: migrated (graduated to DEX) / non_migrated (still on bonding curve)

portfolio holdings Options