gmgn-swap — Claude Code skill: swaps and installation

---
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. 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-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`, `multi-swap` and `order strategy create` command submits an on-chain transaction that moves real funds; `order strategy cancel` changes a live order.
- Transactions cannot be undone once confirmed on-chain.
- Only use this skill with funds you are willing to trade. Start with small amounts when testing.

## Sub-commands

| Sub-command | Description |
|-------------|-------------|
| `swap` | Submit a token swap |
| `multi-swap` | Submit token swaps across multiple wallets concurrently (up to 100) |
| `order quote` | Get a swap quote (no transaction submitted; exist auth — API Key only, no private key needed) |
| `order get` | Query order status |
| `gas-price` | Query recommended gas price (low / average / high tiers) for any chain; exist auth (API Key only) |
| `order strategy create` | Create a limit/strategy order (requires private key) |
| `order strategy list` | List strategy orders (requires private key) |
| `order strategy cancel` | Cancel a strategy order (requires private key) |

## Supported Chains

`sol` / `bsc` / `base` / `eth` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable`

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

| Chain  | Currency tokens |
| ------ | --------------- |
| `sol`  | SOL (native, `So11111111111111111111111111111111111111112`), USDC (`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) |
| `bsc`  | BNB (native, `0x0000000000000000000000000000000000000000`), USDC (`0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d`) |
| `base` | ETH (native, `0x0000000000000000000000000000000000000000`), USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) |
| `eth`  | ETH (native, `0x0000000000000000000000000000000000000000`) |

## Prerequisites

`GMGN_API_KEY` must be configured in `~/.config/gmgn/.env`. `GMGN_PRIVATE_KEY` is additionally required for `swap` and `order` subcommands other than `order quote`. 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 use GMGN's plan-based leaky bucket: Free `5/5`, Plus `20/20`, Pro `50/50` (rate/capacity). Sustained throughput is roughly `tier rate ÷ weight` requests/second, and the max burst is roughly `floor(tier capacity ÷ weight)`.

| Command | Route | Weight |
|---------|-------|--------|
| `swap` | `POST /v1/trade/swap` | 10 |
| `multi-swap` | `POST /v1/trade/multi_swap` | 10 |
| `order quote` | `GET /v1/trade/quote` | 10 |
| `order get` | `GET /v1/trade/query_order` | 5 |
| `order strategy create` | `POST /v1/trade/strategy/create` | 5 |
| `order strategy cancel` | `POST /v1/trade/strategy/cancel` | 2 |
| `order strategy list` | `GET /v1/trade/strategy/orders` | 1 |
| `gas-price` | `GET /v1/trade/gas_price` | 1 |

When a request returns `429`:

- On `RATE_LIMIT_EXCEEDED`, tell the user exactly: `已达到当前套餐的限频上限，点击 https://gmgn.ai/ai?chain=bsc&tab=paid_plans 升级套餐，获得更高速率限制`. Show this upgrade guidance at most once per user task. Do not repeat it for subsequent `RATE_LIMIT_BANNED` responses during the same cooldown.

- 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 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.
- On `RATE_LIMIT_BANNED_MAX`, the ban has hit the 5-minute ceiling because requests kept arriving during the cooldown. Stop **all** GMGN calls for this task (not just the failing one) and tell the user the exact reset time; any request before `reset_at` resets the ban to 5 minutes again.
- On `403 PLAN_UPGRADE_REQUIRED`, the endpoint costs more rate-limit weight than the user's plan capacity, so it can never succeed on this plan — do not retry or wait. Tell the user the endpoint is unavailable on their current plan and show the `upgrade_message` from the response (it contains the upgrade link `https://gmgn.ai/ai?chain=bsc&tab=paid_plans`).
- `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.

## `swap` Usage

```bash
# Basic swap
gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --amount <input_amount_smallest_unit>

# With slippage
gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --amount 1000000 \
  --slippage 30

# With automatic slippage
gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --amount 1000000 \
  --auto-slippage

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

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

## `swap` Parameters

| Parameter | Required | Chain | Description |
|-----------|----------|-------|-------------|
| `--chain` | Yes | all | `sol` / `bsc` / `base` / `eth` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable` |
| `--from` | Yes | all | Wallet address (must match API Key binding) |
| `--input-token` | Yes | all | Input token contract address |
| `--output-token` | Yes | all | Output token contract address |
| `--amount` | No* | all | Input amount in smallest unit. **Mutually exclusive with `--percent`** — provide one or the other, never both. Required unless `--percent` is used. |
| `--percent <pct>` | No* | all | Sell percentage of `input_token`, e.g. `50` = 50%, `1` = 1%. Sets `input_amount` to `0` automatically. **Mutually exclusive with `--amount`. Only valid when `input_token` is NOT a currency (SOL/BNB/ETH/USDC).** |
| `--slippage <n>` | No | all | Slippage tolerance as an integer 0–100, e.g. `30` = 30%. **Mutually exclusive with `--auto-slippage`** — use one or the other. |
| `--auto-slippage` | No | all | Enable automatic slippage. **Mutually exclusive with `--slippage`.** |
| `--min-output <n>` | No | all | Minimum output amount |
| `--anti-mev` | No | sol / bsc / eth | Enable anti-MEV protection — **recommended**; protects against frontrunning and sandwich attacks. Default: on. **Not supported on `base`.** |
| `--priority-fee <sol>` | No | `sol` | Priority fee in SOL. Required when using `--condition-orders` on SOL. |
| `--tip-fee <n>` | No | `sol` / `bsc` | Tip fee (SOL in SOL / BSC in BNB). Required when using `--condition-orders` on SOL. |
| `--gas-price <gwei>` | No | `bsc` / `base` / `eth` | Gas price in gwei. Required when using `--condition-orders` on BSC. Mutually exclusive with `--gas-level`. |
| `--gas-level <level>` | No | `eth` | Gas price tier: `low` / `average` / `high`. Mutually exclusive with `--gas-price`. |
| `--auto-fee` | No | `eth` | **Only with `--condition-orders`.** GMGN automatically selects the optimal fee. |
| `--max-fee-per-gas <n>` | No | `bsc` / `base` / `eth` | EIP-1559 max fee per gas. Defaults to `--gas-price` if omitted (BASE/ETH). |
| `--max-priority-fee-per-gas <n>` | No | `bsc` / `base` / `eth` | EIP-1559 max priority fee per gas. Capped to `--max-fee-per-gas`. |
| `--condition-orders <json>` | No | sol / bsc / base / eth / robinhood | JSON array of condition sub-orders (take-profit / stop-loss) to attach after a successful swap. **Max 10 sub-orders.** Strategy creation is best-effort: if the swap succeeds but strategy creation fails, the swap result is still returned. **Not supported on `arc` / `stable`.** See ConditionOrder fields below. |
| `--sell-ratio-type <type>` | No | all | **Only with `--condition-orders`.** Sell ratio basis: `buy_amount` (default) — sells a fixed token amount stored at strategy creation time; `hold_amount` — sells a fixed percentage of the position held at trigger time |

### ConditionOrder Fields (for `--condition-orders`)

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

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `order_type` | Yes | string | Sub-order type: `profit_stop` (fixed take-profit), `loss_stop` (fixed stop-loss), `profit_stop_trace` (trailing take-profit), `loss_stop_trace` (trailing stop-loss) |
| `side` | Yes | string | Always `"sell"` |
| `price_scale` | Conditional | string | Gain/drop % from entry. Required for `profit_stop` / `loss_stop` / `profit_stop_trace`; optional for `loss_stop_trace`. For `profit_stop` / `profit_stop_trace`: gain % (e.g. `"100"` = +100% / 2× entry). For `loss_stop` / `loss_stop_trace`: drop % (e.g. `"65"` = drops 65%, triggers at 35% of entry). |
| `sell_ratio` | Yes | string | Percentage of position to sell when triggered, e.g. `"100"` = 100% |
| `drawdown_rate` | Conditional | string | Required for `profit_stop_trace` and `loss_stop_trace`. Trailing callback %: after price peaks, how far it must fall before the order fires. E.g. `"50"` = 50% drawdown from peak. |

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

```json
[
  {"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):**

```bash
gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token <token_A_address> \
  --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:**

```bash
gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token <token_A_address> \
  --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

| Field               | Type   | Description |
| ------------------- | ------ | ---- |
| `order_id`          | string | Order ID for follow-up queries |
| `hash`              | string | Transaction hash |
| `status`            | string | Order status: `pending` / `processed` / `confirmed` / `failed` / `expired` |
| `error_code`        | string | Error code on failure |
| `error_status`      | string | Error description on failure |
| `strategy_order_id` | string | Strategy order ID; only present when `--condition-orders` was passed and strategy creation succeeded (best-effort) |
| `report`            | object | Execution report; only present when `state = 30` and `status = "successful"`. See Report Fields below. |

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

| Field                   | Type    | Description |
| ----------------------- | ------- | ---- |
| `input_token`           | string  | Input token contract address |
| `input_token_decimals`  | integer | Input token decimal places |
| `swap_mode`             | string  | Swap mode: `ExactIn` / `ExactOut` |
| `input_amount`          | string  | Actual input consumed (smallest unit) |
| `output_token`          | string  | Output token contract address |
| `output_token_decimals` | integer | Output token decimal places |
| `output_amount`         | string  | Actual output received (smallest unit) |
| `quote_token`           | string  | Quote token contract address |
| `quote_decimals`        | integer | Quote token decimal places |
| `quote_amount`          | string  | Quote amount (smallest unit) |
| `base_token`            | string  | Base token contract address |
| `base_decimals`         | integer | Base token decimal places |
| `base_amount`           | string  | Base token amount (smallest unit) |
| `price`                 | string  | Execution price (quote/base token) |
| `price_usd`             | string  | Execution price in USD |
| `height`                | integer | Block height of execution |
| `order_height`          | integer | Block height when order was placed |
| `gas_native`            | string  | Gas fee in native token |
| `gas_usd`               | string  | Gas fee in USD |

## Output Format

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

```bash
# Basic multi-wallet swap
gmgn-cli multi-swap \
  --chain sol \
  --accounts <addr1>,<addr2> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --input-amount '{"<addr1>":"1000000","<addr2>":"2000000"}' \
  --slippage 30

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

# With per-wallet take-profit / stop-loss (condition_orders)
gmgn-cli multi-swap \
  --chain sol \
  --accounts <addr1>,<addr2> \
  --input-token So11111111111111111111111111111111111111112 \
  --output-token <token_address> \
  --input-amount '{"<addr1>":"1000000","<addr2>":"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 <token_address> \
  --input-amount '{"<0xaddr1>":"1000000","<0xaddr2>":"2000000"}' \
  --slippage 30 \
  --gas-price 5
```

## `multi-swap` Parameters

| Parameter | Required | Chain | Description |
|-----------|----------|-------|-------------|
| `--chain` | Yes | all | `sol` / `bsc` / `base` / `eth` / `arbitrum` / `hyperevm` / `robinhood` / `arc` / `stable` |
| `--accounts` | Yes | all | Comma-separated wallet addresses (1–100, all must be bound to the API Key) |
| `--input-token` | Yes | all | Input token contract address |
| `--output-token` | Yes | all | Output token contract address |
| `--input-amount` | No* | all | JSON map of `wallet_address → input amount` (smallest unit). One of `--input-amount`, `--input-amount-bps`, or `--output-amount` is required. |
| `--input-amount-bps` | No* | all | JSON map of `wallet_address → percent in bps` (1–10000; 5000 = 50%). Only valid when `input_token` is NOT a currency. |
| `--output-amount` | No* | all | JSON map of `wallet_address → target output amount` (smallest unit). |
| `--slippage <n>` | No | all | Slippage tolerance as an integer 0–100, e.g. `30` = 30%. Mutually exclusive with `--auto-slippage`. |
| `--auto-slippage` | No | all | Enable automatic slippage. |
| `--anti-mev` | No | sol / bsc / eth | Enable anti-MEV protection. Not supported on `base`. |
| `--priority-fee <sol>` | No | `sol` | Priority fee in SOL. Required when using `--condition-orders` on SOL. |
| `--tip-fee <amount>` | No | `sol` / `bsc` | Tip fee (SOL in SOL / BSC in BNB). Required when using `--condition-orders` on SOL. |
| `--gas-price <gwei>` | No | `bsc` / `base` / `eth` | Gas price in gwei. Required when using `--condition-orders` on BSC. Mutually exclusive with `--gas-level`. |
| `--gas-level <level>` | No | `eth` | Gas price tier: `low` / `average` / `high`. Mutually exclusive with `--gas-price`. |
| `--auto-fee` | No | `eth` | **Only with `--condition-orders`.** GMGN automatically selects the optimal fee. |
| `--max-fee-per-gas <amount>` | No | `bsc` / `base` / `eth` | EIP-1559 max fee per gas. Defaults to `--gas-price` if omitted (BASE/ETH). |
| `--max-priority-fee-per-gas <amount>` | No | `bsc` / `base` / `eth` | EIP-1559 max priority fee per gas. Capped to `--max-fee-per-gas`. |
| `--condition-orders <json>` | No | sol / bsc / base / eth / robinhood | JSON array of condition sub-orders (take-profit / stop-loss) attached to each successful wallet's swap. Same structure as `swap --condition-orders`. Strategy creation is best-effort per wallet. **Not supported on `arc` / `stable`.** |
| `--sell-ratio-type <type>` | No | all | **Only with `--condition-orders`.** Sell ratio base: `buy_amount` (default) / `hold_amount`. |

## `multi-swap` Response Fields

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

| Field | Type | Description |
|-------|------|-------------|
| `account` | string | Wallet address |
| `success` | bool | Whether this wallet's swap succeeded |
| `error` | string | Error message on failure; absent on success |
| `error_code` | string | Error code on failure; absent on success |
| `result` | object | On success: OrderResponse (same fields as `swap` response). On failure: absent. |
| `result.strategy_order_id` | string | Strategy order ID; only present when `--condition-orders` was passed and strategy creation succeeded (best-effort) |

---

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

---

## `order quote` Usage

Get an estimated output amount before submitting a swap. Uses normal auth — only `GMGN_API_KEY` required, no `GMGN_PRIVATE_KEY` needed.

```bash
gmgn-cli order quote \
  --chain sol \
  --from <wallet_address> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --amount <input_amount_smallest_unit> \
  --slippage 30
```

### `order quote` Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `input_token` | string | Input token contract address |
| `output_token` | string | Output token contract address |
| `input_amount` | string | Input amount (smallest unit) |
| `output_amount` | string | Expected output amount (smallest unit) |
| `min_output_amount` | string | Minimum output after slippage |
| `slippage` | number | Actual slippage percentage |

---

## `order get` Usage

```bash
gmgn-cli order get --chain sol --order-id <order_id>
```

Response fields are shared with `swap` — see [`swap` / `order get` Response Fields](#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.

```bash
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).

| Field                    | Type    | Description |
| ------------------------ | ------- | ----------- |
| `chain`                  | string  | Chain identifier |
| `auto`                   | string  | Automatic gas price |
| `auto_mev`               | string  | Anti-MEV automatic gas price |
| `last_block`             | int64   | Latest block number |
| `high`                   | string  | High-priority gas price |
| `average`                | string  | Average-priority gas price |
| `low`                    | string  | Low-priority gas price |
| `suggest_base_fee`       | string  | Suggested base fee |
| `high_prio_fee`          | string  | High-priority fee |
| `average_prio_fee`       | string  | Average-priority fee |
| `low_prio_fee`           | string  | Low-priority fee |
| `high_prio_fee_mixed`    | string  | High mixed priority fee |
| `average_prio_fee_mixed` | string  | Average mixed priority fee |
| `low_prio_fee_mixed`     | string  | Low mixed priority fee |
| `native_token_usd_price` | float32 | Native token USD price |
| `high_estimate_time`     | int64   | Estimated confirmation time for high tier (seconds) |
| `average_estimate_time`  | int64   | Estimated confirmation time for average tier (seconds) |
| `low_estimate_time`      | int64   | Estimated confirmation time for low tier (seconds) |
| `high_orign`             | strin...