Back to Details

gmgn-swap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Use the 
gmgn-cli
tool to submit a token swap or query an existing order. Requires private key (
GMGN_PRIVATE_KEY
in 
.env
).
使用
gmgn-cli
工具提交代币兑换订单或查询现有订单状态。需配置私钥（在
.env
文件中设置
GMGN_PRIVATE_KEY
）。

Sub-commands

子命令

Sub-commandDescription
swap
Submit a token swap
order get
Query order status
子命令说明
swap
提交代币兑换订单
order get
查询订单状态

Supported Chains

支持的链

sol
/ 
bsc
/ 
base
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
)
链原生代币是各条链的基础资产，可用于购买其他代币或接收出售代币的收益。了解哪些代币是原生代币对于
--percent
参数的使用至关重要（见下方兑换参数）。
链原生代币
sol
SOL（原生代币，合约地址So11111111111111111111111111111111111111112）、USDC（合约地址
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
）
bsc
BNB（原生代币，合约地址0x0000000000000000000000000000000000000000）、USDC（合约地址
0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
）
base
ETH（原生代币，合约地址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.
必须在
.env
文件中设置
GMGN_API_KEY
和
GMGN_PRIVATE_KEY
，且私钥必须与API密钥绑定的钱包对应。

Swap Usage

兑换使用示例

bash
undefined
bash
undefined

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>
npx gmgn-cli swap
--chain sol
--from <钱包地址>
--input-token <输入代币合约地址>
--output-token <输出代币合约地址>
--amount <最小单位的输入数量>

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
npx gmgn-cli swap
--chain sol
--from <钱包地址>
--input-token <输入代币合约地址>
--output-token <输出代币合约地址>
--amount 1000000
--slippage 0.01

With anti-MEV (SOL)

开启反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
npx 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)

出售代币的50%（输入代币不能是原生代币）

npx gmgn-cli swap
--chain sol
--from <wallet_address>
--input-token <token_address>
--output-token <sol_or_usdc_address>
--percent 50
undefined
npx gmgn-cli swap
--chain sol
--from <钱包地址>
--input-token <代币合约地址>
--output-token <SOL或USDC合约地址>
--percent 50
undefined

Order Query

订单查询示例

bash
npx gmgn-cli order get --chain sol --order-id <order_id>
bash
npx gmgn-cli order get --chain sol --order-id <订单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)
参数是否必填说明
--chain
是
sol
/ 
bsc
/ 
base
--from
是钱包地址（必须与API密钥绑定的钱包一致）
--input-token
是输入代币的合约地址
--output-token
是输出代币的合约地址
--amount
否*最小单位的输入数量，除非使用
--percent
参数，否则为必填项
--percent <pct>
否*出售输入代币的百分比，例如
50
代表50%，
1
代表1%。会自动将
input_amount
设为
0
。仅当输入代币不是原生代币（SOL/BNB/ETH/USDC）时有效。
--slippage <n>
否滑点容忍度，例如
0.01
代表1%
--min-output <n>
否最小输出数量
--anti-mev
否开启反MEV保护（默认开启）
--priority-fee <sol>
否优先费用（以SOL为单位，≥0.00001，仅支持Sol链）
--tip-fee <n>
否小费（Sol链≥0.00001 SOL / BSC链≥0.000001 BNB）
--max-auto-fee <n>
否自动费用上限
--gas-price <gwei>
否燃气价格（以gwei为单位，BSC≥0.05 / BASE/ETH≥0.01）
--max-fee-per-gas <n>
否EIP-1559最大燃气单价（仅支持Base链）
--max-priority-fee-per-gas <n>
否EIP-1559最大优先燃气单价（仅支持Base链）

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
字段类型说明
order_id
字符串用于后续查询的订单ID
hash
字符串交易哈希
state
整数订单状态码
confirmation.state
字符串
processed
（处理中）/ 
confirmed
（已确认）/ 
failed
（失败）/ 
expired
（已过期）
confirmation.detail
字符串确认详情信息
error_code
字符串失败时的错误码
error_status
字符串失败时的错误描述
height
数字交易所在区块高度
order_height
数字订单提交时的区块高度
input_token
字符串输入代币的合约地址
output_token
字符串输出代币的合约地址
filled_input_amount
字符串实际消耗的输入数量（最小单位）；未完成时为空
filled_output_amount
字符串实际收到的输出数量（最小单位）；未完成时为空

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
  • 兑换使用严格认证（API密钥 + 签名）——CLI会自动处理签名，无需手动操作
  • 提交兑换订单后，可使用
    order get
    命令轮询确认状态
  • --amount
    参数使用最小单位（例如SOL的lamports单位）
  • 使用
    --raw
    参数可获取单行JSON格式的响应，便于后续处理

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>
  • 原生代币解析——当用户指定原生代币（SOL/BNB/ETH/USDC）而非合约地址时，需从“链原生代币”表中查找其地址并自动填充，切勿询问用户。
    • 买入操作（如“用X SOL买入TOKEN”、“花费0.5 USDC购买TOKEN”）→ 将原生代币解析为
      --input-token
      参数
    • 卖出操作（如“将TOKEN卖出换SOL”、“卖出50%的TOKEN换USDC”）→ 将原生代币解析为
      --output-token
      参数
  • 交易前确认——执行
    swap
    命令前，必须向用户展示关键参数（链、钱包地址、输入代币、输出代币、数量或百分比），并请求用户明确确认。
  • 百分比出售限制——
    --percent
    参数仅当输入代币不是原生代币时有效。当输入代币为SOL/BNB/ETH（原生）或USDC时，不得使用
    --percent
    参数。例如“卖出50%的SOL”、“用30%的BNB买入X”、“花费50%的USDC购买X”均不支持。需向用户说明限制，并请求用户提供明确的绝对数量。
  • 链与钱包兼容性——Sol链地址与EVM链（bsc/base）不兼容。若地址格式与所选链不匹配，需向用户发出警告并终止操作。
  • 凭证敏感性——
    GMGN_API_KEY
    和
    GMGN_PRIVATE_KEY
    可直接在绑定的钱包上执行交易。切勿记录、显示或泄露这些信息。
  • 订单轮询——提交兑换订单后，若
    confirmation.state
    尚未变为
    confirmed
    /
    failed
    /
    expired
    ，需使用
    order get
    命令最多轮询3次，每次间隔5秒，之后若仍未确认则报告超时。确认后，需使用
    filled_input_amount
    和
    filled_output_amount
    （通过代币小数位数转换为正常单位）展示交易结果，例如“花费0.1 SOL → 收到98.5 USDC”或“卖出1000 TOKEN → 收到0.08 SOL”。
  • 区块浏览器链接——兑换成功后，需展示交易哈希对应的可点击浏览器链接：
    链浏览器链接
    sol
    https://solscan.io/tx/<hash>
    bsc
    https://bscscan.com/tx/<hash>
    base
    https://basescan.org/tx/<hash>
    eth
    https://etherscan.io/tx/<hash>