gmgn-swap

Original：🇺🇸 English
Translated

Submit a GMGN token swap or query order status. Requires private key configured. Supports sol / bsc / base.

10installs
Sourcegmgnai/gmgn-skills
Added on

NPX Install

npx skill4agent add gmgnai/gmgn-skills gmgn-swap

Tags

Translated version includes tags in frontmatter
gmgn-clitoken-swaporder-querymulti-chain-toolsblockchain-trading

SKILL.md Content

View Translation Comparison →
Use the 
gmgn-cli
tool to submit a token swap or query an existing order. Requires private key (
GMGN_PRIVATE_KEY
in 
.env
).

Sub-commands

Sub-commandDescription
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).
ChainCurrency 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

ParameterRequiredDescription
--chain
Yes
sol
/ 
bsc
/ 
base
--from
YesWallet address (must match API Key binding)
--input-token
YesInput token contract address
--output-token
YesOutput 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>
NoSlippage tolerance, e.g. 
0.01
= 1%
--min-output <n>
NoMinimum output amount
--anti-mev
NoEnable anti-MEV protection (default true)
--priority-fee <sol>
NoPriority fee in SOL (≥ 0.00001, SOL only)
--tip-fee <n>
NoTip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB)
--max-auto-fee <n>
NoMax automatic fee cap
--gas-price <gwei>
NoGas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01)
--max-fee-per-gas <n>
NoEIP-1559 max fee per gas (Base only)
--max-priority-fee-per-gas <n>
NoEIP-1559 max priority fee per gas (Base only)

Swap Response Fields

FieldTypeDescription
order_id
stringOrder ID for follow-up queries
hash
stringTransaction hash
state
intOrder state code
confirmation.state
string
processed
/ 
confirmed
/ 
failed
/ 
expired
confirmation.detail
stringConfirmation detail message
error_code
stringError code on failure
error_status
stringError description on failure
height
numberBlock height of the transaction
order_height
numberBlock height when the order was placed
input_token
stringInput token contract address
output_token
stringOutput token contract address
filled_input_amount
stringActual input consumed (smallest unit); empty if not filled
filled_output_amount
stringActual 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
    :
    ChainExplorer
    sol
    https://solscan.io/tx/<hash>
    bsc
    https://bscscan.com/tx/<hash>
    base
    https://basescan.org/tx/<hash>
    eth
    https://etherscan.io/tx/<hash>