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.
Fetches gmgn-swap from gmgnai/gmgn-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/gmgn-swap
Restart Cursor to activate gmgn-swap. Access via /gmgn-swap in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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. Requires private key (GMGN_PRIVATE_KEY in .env).
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 expressed as a decimal, not a percentage. 0.01 = 1% slippage. 0.5 = 50% slippage. 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.
Critical auth — swap requires 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. Normal commands (like order quote) use API Key alone.
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.
filled_input_amount / filled_output_amount — Actual amounts consumed/received, in smallest unit. Convert to human-readable using token decimals before displaying to the user.
Financial Risk Notice
This skill executes REAL, IRREVERSIBLE blockchain transactions.
Every swap and order strategy create command submits an on-chain transaction that moves real funds.
Transactions cannot be undone once confirmed on-chain.
The AI agent must never auto-execute a swap — explicit user confirmation is required every time, without exception.
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
order quote
Get a swap quote (no transaction submitted)
order get
Query order status
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
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).
Chain
Currency tokens
sol
SOL (native, So11111111111111111111111111111111111111112), USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
All swap-related routes used by this skill go through GMGN's leaky-bucket limiter with rate=10 and capacity=10. Sustained throughput is roughly 10 ÷ weight requests/second, and the max burst is roughly floor(10 ÷ weight) when the bucket is full.
Command
Route
Weight
swap
POST /v1/trade/swap
5
order quote
GET /v1/trade/quote
2
order get
GET /v1/trade/query_order
1
When a request returns 429:
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, then ask for confirmation again 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.
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.
First-time setup (if credentials are not configured):
Generate key pair and show the public key to the user:
Tell the user: "This is your Ed25519 public key. Go to https://gmgn.ai/ai, paste it into the API key creation form (enable swap capability), then send me the API Key value shown on the page."
Wait for the user's API key, then configure both credentials:
Both GMGN_API_KEY and GMGN_PRIVATE_KEY are read from the .env file by the CLI at startup. They are never passed as command-line arguments and never appear in shell command strings.
GMGN_PRIVATE_KEY is used exclusively for local message signing — the private key never leaves the machine. The CLI computes an Ed25519 or RSA-SHA256 signature in-process and transmits only the base64-encoded result in the X-Signature request header.
GMGN_API_KEY is transmitted in the X-APIKEY request header to GMGN's servers over HTTPS.
swap Usage
# Basic swapgmgn-cli swap \--chain sol \--from<wallet_address>\ --input-token <input_token_address>\ --output-token <output_token_address>\--amount<input_amount_smallest_unit># With slippagegmgn-cli swap \--chain sol \--from<wallet_address>\ --input-token <input_token_address>\ --output-token <output_token_address>\--amount1000000\--slippage0.01# With automatic slippagegmgn-cli swap \--chain sol \--from<wallet_address>\ --input-token <input_token_address>\ --output-token <output_token_address>\--amount1000000\ --auto-slippage
# With anti-MEV (SOL)gmgn-cli swap \--chain sol \--from<wallet_address>\ --input-token <input_token_address>\ --output-token <output_token_address>\--amount1000000\ --anti-mev
# Sell 50% of a token (input_token must NOT be a currency)gmgn-cli swap \--chain sol \--from<wallet_address>\ --input-token <token_address>\ --output-token <sol_or_usdc_address>\--percent50
order quote Usage
Get an estimated output amount before submitting a swap. Uses normal auth — no private key required.
gmgn-cli order quote \--chain sol \--from<wallet_address>\ --input-token <input_token_address>\ --output-token <output_token_address>\--amount<input_amount_smallest_unit>\--slippage0.01
order quote Response Fields
Field
Type
Description
input_token
string
Input token contract address
output_token
string
Output token contract address
input_amount
string
Input amount (smallest unit)
output_amount
string
Expected output amount (smallest unit)
min_output_amount
string
Minimum output after slippage
slippage
number
Actual slippage percentage
order get Usage
gmgn-cli order get --chain sol --order-id <order_id>
swap Parameters
Parameter
Required
Description
--chain
Yes
sol / bsc / base
--from
Yes
Wallet address (must match API Key binding)
--input-token
Yes
Input token contract address
--output-token
Yes
Output token contract address
--amount
No*
Input amount in smallest unit. Mutually exclusive with --percent — provide one or the other, never both. 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. Mutually exclusive with --amount. Only valid when input_token is NOT a currency (SOL/BNB/ETH/USDC).
--slippage <n>
No
Slippage tolerance, e.g. 0.01 = 1%. Mutually exclusive with --auto-slippage — use one or the other.
--auto-slippage
No
Enable automatic slippage. Mutually exclusive with --slippage.
--min-output <n>
No
Minimum output amount
--anti-mev
No
Enable anti-MEV protection — recommended; protects against frontrunning and sandwich attacks. Default: on
--priority-fee <sol>
No
Priority fee in SOL (≥ 0.00001, SOL only)
--tip-fee <n>
No
Tip fee (SOL ≥ 0.00001 / BSC ≥ 0.000001 BNB)
--max-auto-fee <n>
No
Max automatic fee cap
--gas-price <gwei>
No
Gas price in gwei (BSC ≥ 0.05 / BASE/ETH ≥ 0.01)
--max-fee-per-gas <n>
No
EIP-1559 max fee per gas (Base only)
--max-priority-fee-per-gas <n>
No
EIP-1559 max priority fee per gas (Base only)
--condition-orders <json>
No
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. See ConditionOrder fields below.
--sell-ratio-type <type>
No
Sell ratio basis for --condition-orders: buy_amount (default) — when triggered, sells a fixed token amount stored at strategy creation time; hold_amount — when triggered, sells a fixed percentage of the position held at trigger time
ConditionOrder Fields (for --condition-orders)
Each element in the --condition-orders JSON array supports:
›Access to product documentation and roadmap tools (Jira, Notion, etc.)
›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
›Stakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
⚠Not validating competitive research—verify facts before sharing
⚠Accepting user stories without involving engineering team
⚠Over-relying on frameworks without qualitative judgment
⚠Not customizing outputs to company culture and communication style
⚠Skipping stakeholder validation of generated requirements
Best Practices
✓ Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
✗ Don't
−Don't publish competitive analysis without fact-checking
−Don't finalize user stories without engineering review
−Don't make prioritization decisions solely on AI scoring
−Don't skip customer validation of generated requirements
−Don't ignore company-specific context and culture
💡 Pro Tips
★Provide context: company goals, constraints, customer feedback
★Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
★Use skill for 70% generation + 30% customization to company needs
When to Use This
✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates
