gmgn-cli 1.0.0

package/skills/gmgn-swap/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: gmgn-swap
+description: Submit a GMGN token swap or query order status. Requires private key configured. Supports sol / bsc / base.
+argument-hint: "[--chain <chain> --from <wallet> --input-token <addr> --output-token <addr> --amount <n>] | [order get --chain <chain> --order-id <id>]"
+---
+
+Use the `gmgn-cli` tool to submit a token swap or query an existing order. **Requires private key** (`GMGN_PRIVATE_KEY` in `.env`).
+
+## Sub-commands
+
+| Sub-command | Description |
+|-------------|-------------|
+| `swap` | Submit a token swap |
+| `order get` | Query order status |
+
+## 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`) |
+| `bsc` | BNB (native, 0x0000000000000000000000000000000000000000), USDC (`0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d`) |
+| `base` | ETH (native, 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.
+
+## Swap Usage
+
+```bash
+# 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>
+
+# 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
+
+# With anti-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
+
+# Sell 50% of a token (input_token must NOT be a currency)
+npx gmgn-cli swap \
+  --chain sol \
+  --from <wallet_address> \
+  --input-token <token_address> \
+  --output-token <sol_or_usdc_address> \
+  --percent 50
+```
+
+## Order Query
+
+```bash
+npx 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. 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>` | No | Slippage tolerance, e.g. `0.01` = 1% |
+| `--min-output <n>` | No | Minimum output amount |
+| `--anti-mev` | No | Enable anti-MEV protection (default true) |
+| `--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) |
+
+## Swap Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `order_id` | string | Order ID for follow-up queries |
+| `hash` | string | Transaction hash |
+| `state` | int | Order state code |
+| `confirmation.state` | string | `processed` / `confirmed` / `failed` / `expired` |
+| `confirmation.detail` | string | Confirmation detail message |
+| `error_code` | string | Error code on failure |
+| `error_status` | string | Error description on failure |
+| `height` | number | Block height of the transaction |
+| `order_height` | number | Block height when the order was placed |
+| `input_token` | string | Input token contract address |
+| `output_token` | string | Output token contract address |
+| `filled_input_amount` | string | Actual input consumed (smallest unit); empty if not filled |
+| `filled_output_amount` | string | Actual output received (smallest unit); empty if not filled |
+
+## 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
+
+## 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`:
+
+  | Chain | Explorer |
+  |-------|----------|
+  | sol   | `https://solscan.io/tx/<hash>` |
+  | bsc   | `https://bscscan.com/tx/<hash>` |
+  | base  | `https://basescan.org/tx/<hash>` |
+  | eth   | `https://etherscan.io/tx/<hash>` |

package/skills/gmgn-token/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: gmgn-token
+description: Query GMGN token information — basic info, security, pool, top holders and top traders. Supports sol / bsc / base.
+argument-hint: <sub-command> --chain <sol|bsc|base> --address <token_address>
+---
+
+Use the `gmgn-cli` tool to query token information based on the user's request.
+
+## Sub-commands
+
+| Sub-command | Description |
+|-------------|-------------|
+| `token info` | Basic info + realtime price |
+| `token security` | Security metrics (holder concentration, contract risks) |
+| `token pool` | Liquidity pool info |
+| `token holders` | Top token holders list |
+| `token traders` | Top token traders list |
+
+## Supported Chains
+
+`sol` / `bsc` / `base`
+
+## Prerequisites
+
+- `.env` file with `GMGN_API_KEY` set
+- Run from the directory where your `.env` file is located, or set `GMGN_HOST` in your environment
+
+## Usage Examples
+
+```bash
+# Basic token info
+npx gmgn-cli token info --chain sol --address <token_address>
+
+# Security metrics
+npx gmgn-cli token security --chain sol --address <token_address>
+
+# Liquidity pool
+npx gmgn-cli token pool --chain sol --address <token_address>
+
+# Top holders
+npx gmgn-cli token holders --chain sol --address <token_address>
+npx gmgn-cli token holders --chain sol --address <token_address> --limit 50
+
+# Top traders
+npx gmgn-cli token traders --chain sol --address <token_address>
+npx gmgn-cli token traders --chain sol --address <token_address> --limit 50
+
+# Raw JSON output (for piping)
+npx gmgn-cli token info --chain sol --address <token_address> --raw
+```
+
+## Notes
+
+- All token commands use normal auth (API Key only, no signature required)
+- Use `--raw` to get single-line JSON for further processing