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, se
By gmgnai · 12,730 installs
npx skills add gmgnai/gmgn-skills --skill gmgn-swap
Source repository · Upstream listing
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 / avalanche
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
swap Parameters
Parameter Required Chain Description
chain Yes all sol / bsc / base / eth / arbitrum / hyperevm / robinhood / arc / stable / avalanche
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