GMGN Plugin
[!IMPORTANT] Complete the Base MCP onboarding flow defined inSKILL.mdbefore calling any GMGN endpoint. The user’s wallet address — passed asfrom_addressin every quote call — is fetched lazily when needed.
Overview
GMGN is a trading platform providing token swap routing and on-chain market intelligence for Base mainnet. This plugin calls the GMGN HTTP API viaweb_request to obtain full unsigned transaction calldata from the quote endpoint, then submits it through send_calls — no server-side key binding or additional MCP server required.
Shell requirement: Every request requires a Unix timestamp (±5 s accuracy) and a fresh UUID v4 as auth parameters. These must be generated via shell commands (date +%s and uuidgen) to guarantee correctness. This plugin only runs on CLI harnesses (Claude Code, Codex) where shell access is available.
Three capabilities are exposed:
- Swap quotes — returns complete unsigned calldata (
data.tx.to/value/data) and ERC-20 approval transactions (data.tx.approve_txs) ready forsend_calls - Gas prices — current low/average/high fee tiers for Base
- Trending tokens — top tokens ranked by swap activity, volume, and holder count
8453)
Auth
All requests require theX-APIKEY header and two query parameters generated via shell:
Generate before every request:
Surface Routing
All HTTP calls go to
openapi.gmgn.ai (in the allowlist). Shell is required for auth parameter generation.
Endpoints
Base URL:https://openapi.gmgn.ai
1. GET /v1/trade/quote — Swap Quote + Calldata
Returns the full unsigned transaction ready for send_calls. This is the primary endpoint for executing swaps.
Query parameters:
Example request (swap 0.00001 ETH → token):
data fields:
Top-level summary fields:
data.tx fields (the full unsigned transaction for send_calls):
Example response:
data.tx.amount_out / 10^data.tx.amount_out_decimals, data.tx.amount_min_out / 10^data.tx.amount_out_decimals.
2. GET /v1/trade/gas_price — Gas Price
Returns current recommended gas price tiers for Base.
Query parameters:
Key response fields under
data:
3. GET /v1/market/rank — Trending Tokens
Returns top trending tokens on Base ranked by swap activity.
Query parameters:
Response:
data.rank array with token address, symbol, price (USD), market cap, 1h/24h price change, swap count, volume, holder count, and liquidity.
Orchestration
Swap flow: “Swap 0.00001 ETH for token X on Base”
Market discovery flow: “What tokens are trending on Base?”
Submission
Build thesend_calls payload from the quote response:
data.tx.approve_txs is empty (native ETH input), omit the approval call and send only the swap call.
send_calls("base", calls), then get_request_status only after the user acts on the approval link.
Example Prompts
Swap 0.00001 ETH for a token on Baseget_wallets→ address.web_request GET /v1/trade/quotewithinput_token=0x000...000(native ETH),input_amount=10000000000000, target token asoutput_token,slippage=5.- Display expected and minimum output, USD values.
- Build approval + swap calls from
data.tx.approve_txsanddata.tx.to/value/data. send_calls("base", [...approvalCalls, swapCall]).
get_wallets→ address.web_request GET /v1/trade/quotewithinput_token=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913(USDC),input_amount=100000000(100 × 1e6),output_token=0x0000000000000000000000000000000000000000.- USDC requires an ERC-20 approval — include
data.tx.approve_txs[0]before the swap call. send_calls("base", calls).
web_request GET /v1/market/rank?chain=base&interval=1h&limit=10&order_by=volume.- Present token list with price, change, and volume.
get_wallets→ address.web_request GET /v1/trade/quotewith USDC as input, target token as output,input_amount=50000000.- Show
data.tx.amount_out_usd, effective price (data.tx.amount_in_usd / (data.tx.amount_out / 10^data.tx.amount_out_decimals)), and slippage impact.
Risks & Warnings
Slippage
Low Liquidity
For meme tokens with low liquidity, higher slippage (10–20%) is common. Always warn the user and require explicit confirmation before proceeding. Thin markets increase the risk of severe price impact and sandwich attacks.Quote Expiry
Quotes expire atdata.tx.deadline (Unix timestamp). If the user has not confirmed within ~30 seconds, re-fetch the quote before submitting. Submitting an expired quote will cause the transaction to revert on-chain.
Notes
- Native ETH address:
0x0000000000000000000000000000000000000000 - USDC on Base:
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - WETH on Base:
0x4200000000000000000000000000000000000006 - Token amounts are in base units. Use
data.tx.amount_in_decimals/data.tx.amount_out_decimalsfrom the quote response to convert to human-readable values. data.tx.datais unsigned calldata — pass it directly tosend_calls; never sign or modify it.data.tx.approve_txshandles ERC-20 allowances. It is empty when the input is native ETH or when a sufficient allowance already exists.timestampmust be within ±5 seconds of server time.client_idmust be a fresh UUID per request.- Use
chain: "base"(not numeric chain ID) withsend_calls.