gmgn-swap

Use the

gmgn-cli

tool to submit a token swap or query an existing order. Requires private key (

GMGN_PRIVATE_KEY

.env

Sub-commands

Sub-command	Description
`swap`	Submit a token swap
`order get`	Query order status

Supported Chains

sol

bsc

base

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

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

Prerequisites

Both

GMGN_API_KEY

and

GMGN_PRIVATE_KEY

must be set in

.env

. The private key must correspond to the wallet bound to the API Key.

Swap Usage

bash

# Basic swap
npx 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
npx gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token <input_token_address> \
  --output-token <output_token_address> \
  --amount 1000000 \
  --slippage 0.01

# With anti-MEV (SOL)
npx 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)
npx gmgn-cli swap \
  --chain sol \
  --from <wallet_address> \
  --input-token <token_address> \
  --output-token <sol_or_usdc_address> \
  --percent 50

Order Query

bash

npx gmgn-cli order get --chain sol --order-id <order_id>

Swap Parameters

Parameter	Required	Description
`--chain`	Yes	`sol` / `bsc` / `base`
`--from`	Yes	Wallet address (must match API Key binding)
`--input-token`	Yes	Input token contract address
`--output-token`	Yes	Output token contract address
`--amount`	No*	Input amount in smallest unit. Required unless `--percent` is used.
`--percent <pct>`	No*	Sell percentage of `input_token` , e.g. `50` = 50%, `1` = 1%. Sets `input_amount` to `0` automatically. Only valid when `input_token` is NOT a currency (SOL/BNB/ETH/USDC).
`--slippage <n>`	No	Slippage tolerance, e.g. `0.01` = 1%
`--min-output <n>`	No	Minimum output amount
`--anti-mev`	No	Enable anti-MEV protection (default true)
`--priority-fee <sol>`	No	Priority fee in SOL (≥ 0.00001, SOL only)
`--tip-fee <n>`	No	Tip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB)
`--max-auto-fee <n>`	No	Max automatic fee cap
`--gas-price <gwei>`	No	Gas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01)
`--max-fee-per-gas <n>`	No	EIP-1559 max fee per gas (Base only)
`--max-priority-fee-per-gas <n>`	No	EIP-1559 max priority fee per gas (Base only)

Swap Response Fields

Field	Type	Description
`order_id`	string	Order ID for follow-up queries
`hash`	string	Transaction hash
`state`	int	Order state code
`confirmation.state`	string	`processed` / `confirmed` / `failed` / `expired`
`confirmation.detail`	string	Confirmation detail message
`error_code`	string	Error code on failure
`error_status`	string	Error description on failure
`height`	number	Block height of the transaction
`order_height`	number	Block height when the order was placed
`input_token`	string	Input token contract address
`output_token`	string	Output token contract address
`filled_input_amount`	string	Actual input consumed (smallest unit); empty if not filled
`filled_output_amount`	string	Actual output received (smallest unit); empty if not filled

Notes

Swap uses critical auth (API Key + signature) — CLI handles signing automatically, no manual processing needed
After submitting a swap, use
```
order get
```
to poll for confirmation
```
--amount
```
is in the smallest unit (e.g., lamports for SOL)
Use
```
--raw
```
to get single-line JSON for further processing

Execution Guidelines

Currency resolution — When the user names a currency (SOL/BNB/ETH/USDC) instead of providing an address, look up its address in the Chain Currencies table and apply it automatically — never ask the user for it.
- Buy ("buy X SOL of TOKEN", "spend 0.5 USDC on TOKEN") → resolve currency to
```
--input-token
```
- Sell ("sell TOKEN for SOL", "sell 50% of TOKEN to USDC") → resolve currency to
```
--output-token
```
Pre-trade confirmation — Before executing
```
swap
```
, always present the key parameters (chain, from, input-token, output-token, amount or percent) to the user and ask for explicit confirmation.
Percentage sell restriction —
```
--percent
```
is ONLY valid when
```
input_token
```
is NOT a currency. Do NOT use
```
--percent
```
when
```
input_token
```
is SOL/BNB/ETH (native) or USDC. This includes: "sell 50% of my SOL", "use 30% of my BNB to buy X", "spend 50% of my USDC on X" — all unsupported. Explain the restriction to the user and ask for an explicit absolute amount instead.
Chain-wallet compatibility — SOL addresses are incompatible with EVM chains (bsc/base). Warn the user and abort if the address format does not match the chain.
Credential sensitivity —
```
GMGN_API_KEY
```
and
```
GMGN_PRIVATE_KEY
```
can directly execute trades on the linked wallet. Never log, display, or expose these values.
Order polling — After a swap, if
```
confirmation.state
```
is not yet
```
confirmed
```
/
```
failed
```
/
```
expired
```
, poll with
```
order get
```
up to 3 times at 5-second intervals before reporting a timeout. Once confirmed, display the trade result using
```
filled_input_amount
```
and
```
filled_output_amount
```
(convert from smallest unit using token decimals), e.g. "Spent 0.1 SOL → received 98.5 USDC" or "Sold 1000 TOKEN → received 0.08 SOL".
Block explorer links — After a successful swap, display a clickable explorer link for the returned
```
hash
```
:
Chain Explorer
sol
https://solscan.io/tx/<hash>
bsc
https://bscscan.com/tx/<hash>
base
https://basescan.org/tx/<hash>
eth
https://etherscan.io/tx/<hash>