# Gmgn Swap

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

- Skill: `om-scogo/gmgn-swap` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add om-scogo/gmgn-swap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/om-scogo/gmgn-swap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: om-scogo (https://skillmd.com/u/om-scogo)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/om-scogo/gmgn-swap

---


**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` 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

| 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` / `robinhood`

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

| Command | Route | Weight |
|---------|-------|--------|
| `swap` | `POST /v1/trade/swap` | 5 |
| `multi-swap` | `POST /v1/trade/multi_swap` | 5 |
| `order quote` | `GET /v1/trade/quote` | 2 |
| `order get` | `GET /v1/trade/query_order` | 1 |
| `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`:

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

## `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` / `robinhood` |
| `--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 (≥ 0.00001). Required when using `--condition-orders` on SOL. |
| `--tip-fee <n>` | No | `sol` / `bsc` | Tip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB). Required when using `--condition-orders` on SOL. |
| `--gas-price <gwei>` | No | `bsc` / `base` / `eth` | Gas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01). 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. Clamped per chain minimums. 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. Clamped per chain minimums; capped to `--max-fee-per-gas`. |
| `--condition-orders <json>` | No | all | 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. 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

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

```bash
gmgn-cli order quote \
  --chain <chain> \
  --from <wallet> \
  --input-token <input_token> \
  --output-token <output_token> \
  --amount <amount> \
  --slippage <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`.

```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` / `robinhood` |
| `--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 (≥ 0.00001). Required when using `--condition-orders` on SOL. |
| `--tip-fee <amount>` | No | `sol` / `bsc` | Tip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB). Required when using `--condition-orders` on SOL. |
| `--gas-price <gwei>` | No | `bsc` / `base` / `eth` | Gas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01). 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. Clamped per chain minimums. 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. Clamped per chain minimums; capped to `--max-fee-per-gas`. |
| `--condition-orders <json>` | No | all | 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. |
| `--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`             | string  | High-priority raw origin value |
| `average_orign`          | string  | Average-priority raw origin value |
| `low_orign`              | string  | Low-priority raw origin value |

---

## `order strategy create` Usage

```bash
# Create a take-profit order: sell when price rises to target (limit_order)
gmgn-cli order strategy create \
  --chain sol \
  --from <wallet_address> \
  --base-token <token_address> \
  --quote-token <sol_address> \
  --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 <wallet_address> \
  --base-token <token_address> \
  --quote-token <sol_address> \
  --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 <wallet_address> \
  --base-token <token_address> \
  --quote-token <sol_address> \
  --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

| Parameter | Required | Chain | Description |
|-----------|----------|-------|-------------|
| `--chain` | Yes | all | `sol` / `bsc` / `base` / `eth` / `robinhood` |
| `--from` | Yes | all | Wallet address (must match API Key binding) |
| `--base-token` | Yes | all | Base token contract address |
| `--quote-token` | Yes | all | Quote token contract address |
| `--order-type` | Yes | all | Order type: `limit_order` / `smart_trade` |
| `--sub-order-type` | Yes | all | `limit_order`: `buy_low` / `buy_high` / `stop_loss` / `take_profit`; `smart_trade` with condition_orders: `mix_trade` |
| `--check-price` | No* | all | Trigger price — required for `limit_order`; omit for `smart_trade` (trigger is in the `buy_low` condition order) |
| `--open-price` | No | all | Open price of the position |
| `--amount-in` | No* | all | Input amount (smallest unit). Mutually exclusive with `--amount-in-percent` |
| `--amount-in-percent` | No* | all | Input as percentage (e.g. `50` = 50%). Mutually exclusive with `--amount-in` |
| `--limit-price-mode` | No | all | `exact` / `slippage` (default: `slippage`) |
| `--expire-in` | No | all | Order expiry in seconds |
| `--sell-ratio-type` | No | all | `buy_amount` (default) — when triggered, sells a fixed token amount stored at strategy creation time; `hold_amount` — when triggered, sells a fixed percentage of the position held at trigger time |
| `--quote-investment` | No | all | Quote token investment amount (`smart_trade`) |
| `--sell-param` | Yes (`smart_trade`) | all | JSON object of sell-side trade params (slippage, fee, gas, etc.) used when a TP/SL condition fires. **Required for `smart_trade`.** Same fields as the root TradeParam; `slippage` is 0–100 integer. |
| `--buy-param` | No | all | JSON object of buy-side trade params override for `smart_trade`. Same fields as root TradeParam; `slippage` is 0–100 integer. |
| `--slippage` | No | all | Slippage tolerance as an integer 0–100, e.g. `30` = 30%. Mutually exclusive with `--auto-slippage`. Defaults to auto-slippage if neither is set. |
| `--auto-slippage` | No | all | Enable automatic slippage |
| `--priority-fee` | No | `sol` | Priority fee in SOL (≥ 0.00001). **Required** for SOL. |
| `--tip-fee` | No | `sol` / `bsc` | Tip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB). **Required** for SOL. |
| `--auto-fee` | No | `eth` | Auto fee mode — GMGN automatically selects the optimal fee. |
| `--gas-price` | No | `bsc` / `base` / `eth` | Gas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01). **Required** for BSC. Mutually exclusive with `--gas-level`. |
| `--gas-level` | No | `eth` | Gas price tier: `low` / `average` / `high`. Mutually exclusive with `--gas-price`. |
| `--max-fee-per-gas` | No | `bsc` / `base` / `eth` | EIP-1559 max fee per gas. Clamped per chain minimums. |
| `--max-priority-fee-per-gas` | No | `bsc` / `base` / `eth` | EIP-1559 max priority fee per gas. Clamped per chain minimums; capped to `--max-fee-per-gas`. |
| `--anti-mev` | No | sol / bsc / eth | Enable anti-MEV protection. Not supported on `base`. |
| `--condition-orders` | No | all | JSON array of condition sub-orders for `smart_trade`. Must include one `buy_low` entry (with `check_price` lower than `open_price`) plus at least one TP/SL entry. |

### `order strategy create` Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `order_id` | string | Created strategy order ID |
| `is_update` | bool | `true` if an existing order was updated, `false` if newly created |

---

## `order strategy list` Usage

```bash
# 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 <token_address>
```

## `order strategy list` Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--chain` | Yes | `sol` / `bsc` / `base` / `eth` / `robinhood` |
| `--type` | No | `open` (default) / `history` |
| `--from` | No | Filter by wallet address |
| `--group-tag` | Yes | Filter by order group: `LimitOrder` (limit orders only) / `STMix` (mixed strategy orders: take-profit, stop-loss, trailing take-profit, trailing stop-loss) |
| `--base-token` | No | Filter by token address |
| `--page-token` | No | Pagination cursor from previous response |
| `--limit` | No | Results per page (default 10 for history) |

### `order strategy list` Response Fields

| Field             | Type   | Description |
| ----------------- | ------ | ---- |
| `next_page_token` | string | Cursor for next page; empty when no more data |
| `total`           | int    | Total count (only returned when `--type open`) |
| `list`            | array  | Array of strategy order objects; see fields below |

#### `list[]` — Strategy Order Object

| Field                      | Type   | Description |
| -------------------------- | ------ | ---- |
| `anti_mev_mode`            | string | Anti-MEV mode string; empty when not set |
| `auto_slippage`            | bool   | Whether auto slippage is enabled |
| `base_decimal`             | int    | Base token decimal places |
| `base_token`               | string | Base token contract address |
| `chain`                    | string | Chain: `sol` / `bsc` / `base` / `eth` / `robinhood` |
| `close_amount`             | string | Token amount sold on close; empty when order is open |
| `close_price`              | string | Token price at close; empty when order is open |
| `close_sell_model`         | string | Sell model used on close; empty when order is open |
| `close_sign_hash`          | string | Close transaction hash; empty when order is open |
| `close_time`               | int    | Close timestamp (ms); `0` when order is open |
| `condition_orders`         | array  | Condition sub-orders; each element is an object — see `condition_orders[]` below |
| `create_time`              | int    | Creation timestamp (ms) |
| `custom_rpc`               | string | Custom RPC endpoint; empty string when not set |
| `dev_sell_ratio`           | string | Dev sell trigger ratio; empty when not set |
| `drawdown_rate`            | string | Trailing drawdown rate for `profit_stop_trace` / `loss_stop_trace`; empty when not set |
| `expire_time`              | int    | Expiration timestamp (ms) |
| `fee`                      | string | Base transaction fee |
| `gas_price`                | string | Gas price |
| `is_anti_mev`              | bool   | Whether anti-MEV protection is active |
| `limit_price_mode`         | string | Limit price mode; empty when not set |
| `loss_stop`                | string | Stop-loss trigger price; empty when not set |
| `loss_stop_type`           | string | Stop-loss type; empty when not set |
| `max_fee_per_gas`          | string | EIP-1559 max fee per gas; EVM only; empty on SOL |
| `max_priority_fee_per_gas` | string | EIP-1559 max priority fee per gas; EVM only; empty on SOL |
| `open_amount`              | string | Token amount at open (smallest unit) |
| `open_price`               | string | Token price at open |
| `open_sign_hash`           | string | Open transaction hash; empty before confirmed |
| `order_id`                 | string | Unique order ID (UUID) |
| `order_statistic`          | object | Cumulative order statistics; see `order_statistic` Object below |
| `order_type`               | string | Order type: `smart_trade` / `limit_order` |
| `place_action`             | string | Placement action; empty when not applicable |
| `prepare_status`           | string | Preparation status; empty when not applicable |
| `priority_fee`             | string | Priority fee; SOL / BSC only |
| `profit_stop`              | string | Take-profit trigger price; empty when not set |
| `profit_stop_type`         | string | Take-profit type; empty when not set |
| `quote_decimal`            | int    | Quote token decimal places |
| `quote_investment`         | string | Quote token investment amount (smallest unit) |
| `quote_token`              | string | Quote token contract address |
| `reason_by`                | string | Entity that triggered the close; empty when open |
| `reason_code`              | string | Reason code for the close action; empty when open |
| `record_high_price`        | string | Highest recorded price since open; used for trailing stops |
| `sell_param`               | object | Sell transaction parameters; see `sell_param` Object below |
| `sell_ratio`               | string | Sell ratio; empty when not set |
| `sell_ratio_type`          | string | Sell ratio base: `buy_amount` / others |
| `slippage`                 | int    | Slippage tolerance (0 = auto) |
| `status`                   | string | Order lifecycle status: `open` / `closed` |
| `strategy_status`          | string | Strategy running status: `running` / `stopped` |
| `sub_order_type`           | string | Sub-order type: `mix_trade` / others |
| `tip_fee`                  | string | Tip fee; SOL only |
| `token_balance`            | string | Remaining token balance; empty when not available |
| `token_logo`               | string | Token logo URL |
| `token_name`               | string | Token display name |
| `token_price`              | string | Current token price; empty when not available |
| `total_supply`             | string | Token total supply |
| `version`                  | int    | Order schema version |
| `wallet_address`           | string | Wallet address that placed the order |

#### `condition_orders[]` — Condition Sub-Order Object

| Field         | Type   | Description |
| ------------- | ------ | ---- |
| `cid`         | string | Condition sub-order ID (UUID) |
| `order_type`  | string | Sub-order type: `profit_stop` / `loss_stop` / `profit_stop_trace` / `loss_stop_trace` |
| `side`        | string | Trade side: `sell` |
| `price_scale` | string | Price ratio relative to open price (string); `profit_stop` / `los

…(truncated)