/wallet-mcp

GMGN Plugin

[!IMPORTANT] Complete the Wallet MCP onboarding flow defined in SKILL.md before calling any GMGN endpoint. The user's wallet address — passed as from_address in 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 via web_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 for send_calls
• Gas prices — current low/average/high fee tiers for Base
• Trending tokens — top tokens ranked by swap activity, volume, and holder count

Chain: Base mainnet (chainId 8453)

Auth

All requests require the X-APIKEY header and two query parameters generated via shell:

Generate before every request:

TS=$(date +%s)
CID=$(uuidgen | tr '[:upper:]' '[:lower:]')

A public API key is available for all read-only operations:

X-APIKEY: gmgn_basesolbscethmonadtron

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

GET https://openapi.gmgn.ai/v1/trade/quote?chain=base&from_address=0xc76d...&input_token=0x0000000000000000000000000000000000000000&output_token=0xc2c1e0b7c401e6217193732272444d928646eba3&input_amount=10000000000000&slippage=5&timestamp=<ts>&client_id=<uuid>
X-APIKEY: gmgn_basesolbscethmonadtron

Response data fields:

Top-level summary fields:

data.tx fields (the full unsigned transaction for send_calls):

Example response:

{
  "code": 0,
  "data": {
    "input_token": "0x0000000000000000000000000000000000000000",
    "output_token": "0xc2c1e0b7c401e6217193732272444d928646eba3",
    "input_amount": "10000000000000",
    "output_amount": "18500572860253689774247",
    "min_output_amount": "17575544217241005285535",
    "slippage": 5,
    "tx": {
      "chain_id": 8453,
      "to": "0xd8Ba9D1a99Fc21f0ECA24e9b85737c28A194a4E2",
      "from_address": "0xc76d1aabf25142f15010e992cb07bb81a8b5ae63",
      "slippage": 5,
      "value": "10000000000000",
      "amount_in": "10000000000000",
      "amount_out": "18500572860253689774247",
      "amount_min_out": "17575544217241005285535",
      "input_token_address": "0x0000000000000000000000000000000000000000",
      "output_token_address": "0xc2c1e0b7c401e6217193732272444d928646eba3",
      "token_in_usd_price": "1671.39",
      "token_out_usd_price": "0.00000088214833000000",
      "amount_in_usd": "0.0167139",
      "amount_out_usd": "0.01632024945271611581069006805751",
      "amount_in_decimals": 18,
      "amount_out_decimals": 18,
      "gas_limit": "922086",
      "data": "0xeffbec13...",
      "approve_txs": [],
      "deadline": 1781266225
    }
  }
}

Convert to human-readable: 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"

1. get_wallets -> user address (from_address)

2. shell: TS=$(date +%s) && CID=$(uuidgen | tr '[:upper:]' '[:lower:]')

3. web_request GET /v1/trade/quote
     ?chain=base
     &from_address=<address>
     &input_token=0x0000000000000000000000000000000000000000   (native ETH)
     &output_token=<token_address>
     &input_amount=<amount_in_wei>
     &slippage=5
     &timestamp=$TS&client_id=$CID
   Headers: X-APIKEY: gmgn_basesolbscethmonadtron

4. Present quote to user:
     Input:           data.tx.amount_in / 10^data.tx.amount_in_decimals  (+ data.tx.amount_in_usd)
     Expected output: data.tx.amount_out / 10^data.tx.amount_out_decimals (+ data.tx.amount_out_usd)
     Minimum output:  data.tx.amount_min_out / 10^data.tx.amount_out_decimals
     Check slippage against Risks & Warnings before proceeding.

5. Confirm with user before submitting.

6. See Submission section to build and send the calls.

Market discovery flow: "What tokens are trending on Base?"

1. shell: TS=$(date +%s) && CID=$(uuidgen | tr '[:upper:]' '[:lower:]')
2. web_request GET /v1/market/rank?chain=base&interval=1h&limit=10&order_by=volume&timestamp=$TS&client_id=$CID
   Headers: X-APIKEY: gmgn_basesolbscethmonadtron
3. Present the top tokens: name, symbol, price, 1h change, volume, holder count
4. Optionally follow up with GET /v1/trade/quote for any token the user wants to buy

Submission

Build the send_calls payload from the quote response:

approvalCalls = data.tx.approve_txs.map(t => ({ to: t.to, value: t.value ?? "0x0", data: t.data }))
swapCall      = { to: data.tx.to, value: data.tx.value, data: data.tx.data }
calls         = [...approvalCalls, swapCall]

If data.tx.approve_txs is empty (native ETH input), omit the approval call and send only the swap call.

{
  "chain": "base",
  "calls": [
    { "to": "<approve_tx.to>", "value": "0x0", "data": "<approve_tx.data>" },
    { "to": "<data.tx.to>", "value": "<data.tx.value>", "data": "<data.tx.data>" }
  ]
}

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 Base

1. get_wallets → address.
2. web_request GET /v1/trade/quote with input_token=0x000...000 (native ETH), input_amount=10000000000000, target token as output_token, slippage=5.
3. Display expected and minimum output, USD values.
4. Build approval + swap calls from data.tx.approve_txs and data.tx.to/value/data.
5. send_calls("base", [...approvalCalls, swapCall]).

Swap 100 USDC for ETH on Base

1. get_wallets → address.
2. web_request GET /v1/trade/quote with input_token=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC), input_amount=100000000 (100 × 1e6), output_token=0x0000000000000000000000000000000000000000.
3. USDC requires an ERC-20 approval — include data.tx.approve_txs[0] before the swap call.
4. send_calls("base", calls).

Show trending tokens on Base

1. web_request GET /v1/market/rank?chain=base&interval=1h&limit=10&order_by=volume.
2. Present token list with price, change, and volume.

What's the price to buy token X with 50 USDC?

1. get_wallets → address.
2. web_request GET /v1/trade/quote with USDC as input, target token as output, input_amount=50000000.
3. 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 at data.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_decimals from the quote response to convert to human-readable values.
• data.tx.data is unsigned calldata — pass it directly to send_calls; never sign or modify it.
• data.tx.approve_txs handles ERC-20 allowances. It is empty when the input is native ETH or when a sufficient allowance already exists.
• timestamp must be within ±5 seconds of server time. client_id must be a fresh UUID per request.
• Use chain: "base" (not numeric chain ID) with send_calls.