gmgn-swap

SKILL.md

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 — all swap operations must go through the CLI. The CLI handles signing and submission automatically.

IMPORTANT: Do NOT guess field names or values. When a field's meaning is unclear, look it up in the Response Fields sections below before using it.

⚠️ 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 submit a token swap or query an existing order. GMGN_API_KEY is always required. GMGN_PRIVATE_KEY is required for critical-auth commands such as swap and order subcommands — except order quote, which only requires GMGN_API_KEY.

Core Concepts

Smallest unit — --amount is always in the token's smallest indivisible unit, not human-readable amounts. For SOL: 1 SOL = 1,000,000,000 lamports. For EVM tokens: depends on decimals (most ERC-20 tokens use 18 decimals). Always convert before passing to the command — do not pass human amounts directly.

slippage — Price tolerance as an integer 0–100, e.g. 30 = 30%. If the price moves beyond this threshold before the transaction confirms, the swap is rejected. Use --auto-slippage for volatile tokens to let GMGN set an appropriate value automatically.

--amount vs --percent — Mutually exclusive. --amount specifies an exact input quantity (in smallest unit). --percent sells a percentage of the current balance and is only valid when input_token is NOT a currency (SOL/BNB/ETH/USDC). Never use --percent to spend a fraction of SOL/BNB/ETH.

Currency tokens — Each chain has designated currency tokens (SOL, BNB, ETH, USDC). These are the base assets used to buy other tokens or receive swap proceeds. Their contract addresses are fixed — look them up in the Chain Currencies table, never guess them.