GMGN Skill Swap

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 all order subcommands, including order quote.

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

• 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-readable using report.input_token_decimals / report.output_token_decimals before displaying to the user.

Financial Risk Notice

This skill executes REAL, IRREVERSIBLE blockchain transactions.

• Every swap and order strategy create command submits an on-chain transaction that moves real funds.
• Transactions cannot be undone once confirmed on-chain.
• The AI agent must never auto-execute a swap — explicit user confirmation is required every time, without exception.
• Only use this skill with funds you are willing to trade. Start with small amounts when testing.

Sub-commands

Supported Chains

sol / bsc / base / eth

Chain Currencies

Currency tokens are the base/native assets of each chain. They are used to buy other tokens or receive proceeds from selling. Knowing which tokens are currencies is critical for --percent usage (see Swap Parameters below).

⚠️ CRITICAL: Always copy currency addresses from this table — NEVER rely on memory or training data. A wrong address (e.g. So11111111111111111111111111111111111111111 instead of So11111111111111111111111111111111111111112) will cause silent failures or jupiter has no route errors with no clear indication of what went wrong.

Prerequisites

GMGN_API_KEY must be configured in ~/.config/gmgn/.env. GMGN_PRIVATE_KEY is additionally required for swap and all order subcommands. The private key must correspond to the wallet bound to the API Key.

• gmgn-cli installed globally — if missing, run: npm install -g gmgn-cli

Rate Limit Handling

All swap-related 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.

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.
• swap is a real transaction: never loop or auto-submit repeated swap attempts after a 429. Wait until the reset time, then ask for confirmation again before retrying.
• The CLI may wait and retry once automatically for short cooldowns on read-only commands such as order quote and order get. 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.
• POST /v1/trade/swap also has an error-count limiter. Repeatedly triggering the same business error, especially 40003701 (insufficient token balance), can return ERROR_RATE_LIMIT_BLOCKED. When this happens, do not retry until the reset time and fix the underlying request first.

First-time setup (if credentials are 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 (enable swap capability), then send me the API Key value shown on the page."

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

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

Credential Model

• Both GMGN_API_KEY and GMGN_PRIVATE_KEY are read from the .env file by the CLI at startup. They are never passed as command-line arguments and never appear in shell command strings.
• GMGN_PRIVATE_KEY is used exclusively for local message signing — the private key never leaves the machine. The CLI computes an Ed25519 or RSA-SHA256 signature in-process and transmits only the base64-encoded result in the X-Signature request header.
• GMGN_API_KEY is transmitted in the X-APIKEY request header to GMGN's servers over HTTPS.

---

swap Usage

# Basic swap
gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --amount 

# With slippage
gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --amount 1000000 \
  --slippage 30

# With automatic slippage
gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --amount 1000000 \
  --auto-slippage

# With anti-MEV (SOL)
gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --amount 1000000 \
  --anti-mev

# Sell 50% of a token (input_token must NOT be a currency)
gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --percent 50

swap Parameters

ConditionOrder Fields (for --condition-orders)

Each element in the --condition-orders JSON array supports:

Example — attach take-profit at 2× (+100%) and stop-loss at -60%:

[
  {"order_type": "profit_stop", "side": "sell", "price_scale": "100", "sell_ratio": "100"},
  {"order_type": "loss_stop",   "side": "sell", "price_scale": "60",  "sell_ratio": "100"}
]

Example — buy token A with 0.01 SOL, take-profit 50% at +100%, take-profit remaining 50% at +300%, stop-loss 100% at -65% (trigger at 35% entry price) (hold_amount mode):

gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token  \
  --amount 10000000 \
  --slippage 30 \
  --anti-mev \
  --condition-orders '[{"order_type":"profit_stop","side":"sell","price_scale":"100","sell_ratio":"50"},{"order_type":"profit_stop","side":"sell","price_scale":"300","sell_ratio":"100"},{"order_type":"loss_stop","side":"sell","price_scale":"65","sell_ratio":"100"}]' \
  --sell-ratio-type hold_amount

price_scale for profit_stop: gain % from entry ("100" = +100% / 2×, "300" = +300% / 4×). For loss_stop: drop % from entry ("65" = drops 65%, triggers at 35% of entry). hold_amount: the second take-profit fires on whatever is held at trigger time (the remaining 50%). If you added to your position in between, those additional tokens will be included as well.

Same strategy using buy_amount mode — fixed percentage of the original bought amount at each trigger:

gmgn-cli swap \
  --chain sol \
  --from  \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token  \
  --amount 10000000 \
  --slippage 30 \
  --anti-mev \
  --condition-orders '[{"order_type":"profit_stop","side":"sell","price_scale":"100","sell_ratio":"50"},{"order_type":"profit_stop","side":"sell","price_scale":"300","sell_ratio":"50"},{"order_type":"loss_stop","side":"sell","price_scale":"65","sell_ratio":"100"}]' \
  --sell-ratio-type buy_amount

buy_amount: each take-profit sells 50% of the original bought amount. Stop-loss sells 100% of the original bought amount.

swap / order get Response Fields

Report Fields (present only when status = "successful")

Output Format

Pre-swap Confirmation

Before displaying the confirmation, run order quote to get the estimated output (requires signed auth and GMGN_PRIVATE_KEY on every supported quote chain):

gmgn-cli order quote \
  --chain  \
  --from  \
  --input-token  \
  --output-token  \
  --amount  \
  --slippage 

Then display the confirmation summary using output_amount from the quote response:

⚠️ Swap Confirmation Required

Chain:        {chain}
Wallet:       {--from}
Sell:         {input amount in human units} {input token symbol}
Buy:          {output token symbol}
Slippage:     {slippage}% (or "auto")
Est. output:  ~{output_amount from quote} {output token symbol}
Risk Level:   🟢 Low / 🟡 Medium / 🔴 High  (based on rug_ratio from security check)

Reply "confirm" to proceed.

Note: Risk Level is derived from the required security check:

• 🟢 Low: rug_ratio < 0.1
• 🟡 Medium: rug_ratio 0.1–0.3
• 🔴 High: rug_ratio > 0.3 (requires re-confirmation)

If the user explicitly skipped the security check, omit the Risk Level line and add a note: "(Security check skipped by user)"

Post-swap Receipt

After a confirmed swap, display:

✅ Swap Confirmed

Spent:    {report.input_amount in human units} {input symbol}
Received: {report.output_amount in human units} {output symbol}
Tx:       {explorer link for hash}
Order ID: {order_id}

Convert report.input_amount and report.output_amount from smallest unit using report.input_token_decimals and report.output_token_decimals before displaying.

---

multi-swap Usage

Submit a token swap across multiple wallets concurrently. Each wallet executes independently — one wallet's failure does not affect others. Up to 100 wallets per request. All wallets must be bound to the API Key. Requires GMGN_PRIVATE_KEY.

# Basic multi-wallet swap
gmgn-cli multi-swap \
  --chain sol \
  --accounts , \
  --input-token  \
  --output-token  \
  --input-amount '{"":"1000000","":"2000000"}' \
  --slippage 30

# Sell a percentage of each wallet's balance (use --input-amount-bps)
gmgn-cli multi-swap \
  --chain sol \
  --accounts , \
  --input-token  \
  --output-token  \
  --input-amount-bps '{"":"5000","":"10000"}' \
  --slippage 30

# With per-wallet take-profit / stop-loss (condition_orders)
gmgn-cli multi-swap \
  --chain sol \
  --accounts , \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token  \
  --input-amount '{"":"1000000","":"2000000"}' \
  --slippage 30 \
  --priority-fee 0.00001 \
  --tip-fee 0.00001 \
  --condition-orders '[{"order_type":"profit_stop","side":"sell","price_scale":"100","sell_ratio":"100"},{"order_type":"loss_stop","side":"sell","price_scale":"50","sell_ratio":"100"}]'

# ETH multi-wallet swap (EIP-1559 gas)
gmgn-cli multi-swap \
  --chain eth \
  --accounts <0xaddr1>,<0xaddr2> \
  --input-token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  --output-token  \
  --input-amount '{"<0xaddr1>":"1000000","<0xaddr2>":"2000000"}' \
  --slippage 30 \
  --gas-price 5

multi-swap Parameters

multi-swap Response Fields

The response data is an array — one element per wallet:

---

order quote Usage

Get an estimated output amount before submitting a swap. All supported quote chains use signed auth and require GMGN_PRIVATE_KEY.

gmgn-cli order quote \
  --chain sol \
  --from  \
  --input-token  \
  --output-token  \
  --amount  \
  --slippage 30

order quote Response Fields

---

order get Usage

gmgn-cli order get --chain sol --order-id 

Response fields are shared with swap — see swap / order get Response Fields above.

---

gas-price Usage

Query recommended gas price tiers for any chain. API Key only — no signature or private key required.

gmgn-cli gas-price --chain eth
gmgn-cli gas-price --chain bsc
gmgn-cli gas-price --chain base
gmgn-cli gas-price --chain sol

gas-price Response Fields

All fields are omitempty — fields unsupported by a chain are omitted. Units are chain-native (wei for EVM chains; lamports / chain-native for SOL).

---

order strategy create Usage

# Create a take-profit order: sell when price rises to target (limit_order)
gmgn-cli order strategy create \
  --chain sol \
  --from  \
  --base-token  \
  --quote-token  \
  --order-type limit_order \
  --sub-order-type take_profit \
  --check-price 0.002 \
  --amount-in 1000000 \
  --slippage 30

# Create a stop-loss order: sell when price drops to target (limit_order)
gmgn-cli order strategy create \
  --chain sol \
  --from  \
  --base-token  \
  --quote-token  \
  --order-type limit_order \
  --sub-order-type stop_loss \
  --check-price 0.0005 \
  --amount-in-percent 100 \
  --slippage 30

# Create a smart_trade with buy_low entry + take-profit + stop-loss (smart_trade)
gmgn-cli order strategy create \
  --chain sol \
  --from  \
  --base-token  \
  --quote-token  \
  --order-type smart_trade \
  --sub-order-type mix_trade \
  --open-price 0.000082 \
  --amount-in 1000000 \
  --slippage 30 \
  --sell-param '{"slippage":30,"priority_fee":"0.00001","tip_fee":"0.00001"}' \
  --condition-orders '[{"order_type":"buy_low","side":"buy","check_price":"0.00008"},{"order_type":"profit_stop","side":"sell","price_scale":"100","sell_ratio":"50"},{"order_type":"loss_stop","side":"sell","price_scale":"50","sell_ratio":"100"}]'

order strategy create Parameters

order strategy create Response Fields

---

order strategy list Usage

# List open condition orders (profit_stop / loss_stop / trace types) — use STMix
gmgn-cli order strategy list --chain sol --group-tag STMix

# List open limit orders (buy_low / buy_high / stop_loss / take_profit) — use LimitOrder
gmgn-cli order strategy list --chain sol --group-tag LimitOrder

# List condition order history with pagination
gmgn-cli order strategy list --chain sol --group-tag STMix --type history --limit 20

# Filter by token
gmgn-cli order strategy list --chain sol --group-tag STMix --base-token 

order strategy list Parameters

order strategy list Response Fields

list[] — Strategy Order Object

condition_orders[] — Condition Sub-Order Object

order_statistic Object