/gmgn-swap

name: gmgn-swap
description: >-
  [FINANCIAL EXECUTION] Buy and sell meme coins and crypto tokens on Solana,
  BSC, Base, or Ethereum — single swap, multi-wallet batch trading, limit
  orders, stop loss, take profit, trailing stop loss, trailing take profit via
  GMGN API. Requires explicit user confirmation. Use when user asks to buy,
  sell, or swap a token, trade from multiple wallets, set a limit order, stop
  loss, take profit, or check order status. This skill SUBMITS the trade — it
  is the only skill holding a private key, and every buy still ends here. It
  is not the entry point for a buy that has not been vetted yet: 「帮我买 200u 的
  PENGU」, "buy me $500 of BONK", 「帮我买点 dogwifhat」, 「XX 能不能买」 start at
  gmgn-token-buy, which resolves the name to the one right contract among its
  copycats, gates volume / depth / security, sizes slippage and gas, then
  hands the confirmed parameters back here to execute. Come straight here for
  a buy only once the contract is settled AND the user says they do not want a
  pre-buy check ("skip the security check", "I already checked", 「直接买」,
  「不用尽调」, 「我很急」). Two facts make the split unavoidable rather than a
  preference: the pre-swap check here reads only `is_honeypot` and
  `rug_ratio`, and there is no name resolution at all — `--output-token` takes
  a contract address and the only names resolved here are the SOL/BNB/ETH/USDC
  currencies — so a same-name copycat is a total loss this skill has no way to
  catch. Everything else is unchanged and unconditionally this skill's:
  selling, percentage sells, swaps, multi-wallet batch trading, limit orders,
  stop loss, take profit, trailing orders, order status, gas prices.
argument-hint: "[--chain <chain> --from <wallet> --input-token <addr> --output-token <addr> --amount <n>] | [order get --chain <chain> --order-id <id>] | [gas-price --chain <eth|bsc|base|sol>] | [order strategy list --chain <chain> --group-tag <LimitOrder|STMix>] | [order strategy create --chain <chain> --order-type <limit_order|smart_trade> --sub-order-type <buy_low|buy_high|stop_loss|take_profit|mix_trade> ...]"
metadata:
  cliHelp: "gmgn-cli swap --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 — 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.

• **Anti-MEV** — MEV (Miner/Maximal Extractable Value) refers to frontrunning and sandwich attacks where bots exploit pending transactions. `--anti-mev` routes the transaction through protected channels to reduce this risk. **Recommended: always enable.** Default: on. **Not supported on `base` chain.**

• **Signed auth** — `swap` and most `order` subcommands require both `GMGN_API_KEY` and `GMGN_PRIVATE_KEY`. The private key never leaves the machine — the CLI uses it only for local signing and sends only the resulting signature. Exception: `order quote` only requires `GMGN_API_KEY`.

• **`order_id` / `status`** — After submitting a swap, the response includes an `order_id`. Use `order get --order-id` to poll for final status. Possible values: `pending` → `processed` → `confirmed` (success) or `failed` / `expired`. Do not report success until status is `confirmed`.

• **`report.input_amount` / `report.output_amount`** — Actual amounts consumed/received, in smallest unit. Only present when `state = 30` and `status = "successful"`. Convert to human-readabl