sunpump-meme-token-toolkit

# SunPump Meme Token Skill ## Quick Start This skill enables AI agents to interact with **SunPump** — the meme-token launchpad on the TRON blockchain — through `sun-cli`. It covers the eight core flows an end user needs: 1. **Create (launch) a new meme token** (`sun sunpump launch`) — server-side creation, no wallet needed 2. **Trade post-launch tokens** through SunSwap (`sun swap`) 3. **Trade pre-launch tokens** on the SunPump bonding curve (`sun sunpump buy` / `sun sunpump sell`) 4. **Check a wallet's positions** (`sun sunpump portfolio`) 5. **View a wallet's trade history** (`sun sunpump tx user`) 6. **Look up token info** (`sun sunpump token get`) 7. **See token rankings** (`sun sunpump token ranking`) 8. **List a token's top holders** (`sun sunpump token holders`) **Pre-launch vs post-launch decision** — choose the right trade command: | Token state | `tokenLaunchedInstant` | `swapPoolAddress` | Trade with | |---|---|---|---| | Pre-launch (bonding curve) | `null` | `null` | `sun sunpump buy` / `sun sunpump sell` | | Post-launch (migrated to DEX) | non-null | non-null | `sun swap` | Always call `sun sunpump state <addr>` or `sun sunpump token get <addr>` first to determine which path to use. ### Prerequisites > **Wallet required for trading only:** Configure a supported sun-cli wallet source locally, > then verify the public address with `sun wallet address` before trading. The retired wallet > and onboarding Skills are not prerequisites; wallet-cli accounts are not automatically > available to sun-cli. Never request or display secret values in chat. > All read-only SunPump queries (portfolio, tx history, token info, ranking, holders) work without a wallet. > Token creation (`sun sunpump launch`) is server-side and also needs **no wallet**. > `--dry-run` previews do not need wallet credentials on `@sun-protocol/sun-cli@1.2.2`. 1. **Install this skill** (once, picked up by Claude Code / Cursor / Codex): ```bash npx skills add BofAI/skills ``` 2. **Verify sun-cli**: ```bash sun --version ``` The required version is exactly `1.2.2`; it includes `sunpump launch`, bonding-curve trading, and wallet-free `--dry-run` previews. If it is missing or another version is installed, obtain approval before changing the global package: ```bash npm install -g @sun-protocol/sun-cli@1.2.2 ``` 3. **Configure wallet** (required for write commands — `sun swap`, `sun sunpump buy`, `sun sunpump sell`): ```bash export TRON_PRIVATE_KEY="your_private_key_here" ``` Alternative wallet sources: `TRON_MNEMONIC` or `AGENT_WALLET_PASSWORD`. 4. **Optional environment variables:** ```bash export TRON_NETWORK=mainnet # SunPump is mainnet only export TRONGRID_API_KEY=your_key export SUNPUMP_API_BASE_URL=... # override the API host if needed ``` --- ## AI Agent Flags Always use these flags when calling `sun` from an AI agent: | Flag | Purpose | |------|---------| | `--json` | Machine-readable JSON output to stdout | | `--yes` | Skip interactive confirmation prompts (write commands only) | | `--dry-run` | Simulate write operations without sending transactions | | `--fields` | Limit output to specific comma-separated fields | | `--network` | Must be `mainnet` for SunPump — any other value is rejected fast | Standard agent invocation pattern (read-only): ```bash sun --json sunpump token get TXYZ... ``` Write operation (swap) with explicit confirmation skip: ```bash sun --json --yes swap TRX TXYZ... 100000000 ``` > **WARNING: SunPump is mainnet only.** > Endpoint: `https://api-v2.sunpump.meme/pump-api`. The CLI throws > `SunPump is only available on mainnet (got "...")` for any other `--network` value > (including `nile` and `shasta`). Drop `--network` or pass `--network mainnet`. --- ## Command Reference ### 1. Post-launch Trading — `sun swap` Once a SunPump token migrates to SunSwap (`tokenLaunchedInstant` non-null, `swapPoolAddress` set), it trades through the SunSwap Universal Router. Use the same `sun swap` and `sun swap:quote` commands as for any TRC20 pair. **Parameters:** `tokenIn` and `tokenOut` accept symbols (TRX, USDT) or TRC20 contract addresses. `amountIn` is in sun (smallest unit — for TRX, 1 TRX = 1_000_000). `--slippage` is a decimal (default `0.005` = 0.5%). #### Step A — Get a quote (read-only, no wallet) ```bash sun --json swap:quote TRX TXYZ1234567890abcdefghijklmnopqrstuv 100000000 ``` Show the user: `amountOut`, price impact, and route. #### Step B — Buy (TRX → meme token) ```bash sun --json --yes swap TRX TXYZ1234567890abcdefghijklmnopqrstuv 100000000 --slippage 0.01 ``` #### Step C — Sell (meme token → TRX) ```bash sun --json --yes swap TXYZ1234567890abcdefghijklmnopqrstuv TRX 1000000000000000000 --slippage 0.01 ``` > **NOTE:** Meme-token decimals vary. Resolve the token's `decimals` via `sun sunpump token get <address>` before computing `amountIn`. #### Dry-run first for large trades ```bash sun --json --yes --dry-run swap TRX TXYZ... 1000000000 ``` > **WARNING: `--dry-run` only previews the transaction structure.** > It does NOT check balances, validate that the pool exists, or reject same-token swaps. > See [Agent Pre-Validation Checklist](#agent-pre-validation-checklist). #### Pre-launch tokens (bonding curve, not yet on SunSwap) A token whose `tokenLaunchedInstant` is null is still on the SunPump bonding curve and **cannot** be traded through `sun swap`. Use the pre-launch trading commands in [Section 2](#2-pre-launch-trading--sun-sunpump-buy--sun-sunpump-sell) instead. Higher slippage (1–5%) is often required for low-liquidity meme pools. --- ### 2. Pre-launch Trading — `sun sunpump buy` / `sun sunpump sell` For tokens still on the SunPump bonding curve (`tokenLaunchedInstant == null`, or on-chain state `TRADING`/`READY_TO_LAUNCH`), trade directly through the SunPump router contract. These commands handle TRC20 approval automatically on first sell, and accept human-readable decimal inputs (CLI scales TRX × 1e6 and tokens × 10^decimals before calling the contract). #### Step A — Verify the token is still on the bonding curve ```bash sun --json sunpump state TXYZ1234567890abcdefghijklmnopqrstuv ``` Returns `{state, info: {tokenAddress, launched, price, trxReserve, tokenReserve}}` where `state` is one of: | Value | Label | Tradeable via `sun sunpump buy/sell`? | |---|---|---| | `0` | `NOT_EXIST` | No (token unknown to SunPump) | | `1` | `TRADING` | Yes | | `2` | `READY_TO_LAUNCH` | Yes (bonding curve full, about to migrate) | | `3` | `LAUNCHED` | No — use `sun swap` | > **IMPORTANT:** `sun-kit`'s TypeScript enum lists only 0–2, but the on-chain contract returns 3 for fully-launched tokens. The CLI maps 3 → `LAUNCHED`; trust the printed label, not the raw number. #### Step B — Get a quote (read-only, no wallet) ```bash sun --json sunpump quote-buy TXYZ... --trx 10 sun --json sunpump quote-sell TXYZ... --amount 1000 ``` Buy returns `{tokenAmount, fee}` in base units. Sell returns `{trxAmount, fee}` in Sun. Both ignore on-chain state — a quote succeeding does **not** mean a trade will succeed. Always check `state` first. #### Step C — Buy (TRX → meme token) ```bash sun --json --yes sunpump buy TXYZ... --trx 10 sun --json --yes sunpump buy TXYZ... --trx 10 --slippage 0.1 # 10% slippage sun --json --yes sunpump buy TXYZ... --trx 10 --min-out 27955000000000000000000 # exact floor in raw units ``` | Flag | Description | |------|-------------| | `--trx <amount>` | TRX to spend, **decimal** (e.g. `10` or `1.5`) — CLI scales to Sun internally | | `--slippage <n>` | Slippage tolerance as decimal (default `0.05` = 5%; meme tokens are volatile) | | `--min-out <raw>` | Minimum tokens out in raw base units, overrides slippage | Returns: `{txResult, tokenAddress, trxSpent, expectedTokens, minTokenOut, tronscanUrl}`. #### Step D — Sell (meme token → TRX) ```bash sun --json --yes sunpump sell TXYZ... --amount 1000 sun --json --yes sunpump sell TXYZ... --amount 1000 --decimals 6 # non-18-decimal token sun --json --yes sunpump sell TXYZ... --amount 1000 --slippage 0.1 ``` | Flag | Description | |------|-------------| | `--amount <amount>` | Tokens to sell, **decimal** (e.g. `1000` or `12.5`) | | `--decimals <n>` | Token decimals (default `18`; resolve from `sun sunpump token get` if unsure) | | `--slippage <n>` | Slippage tolerance as decimal (default `0.05` = 5%) | | `--min-out <raw>` | Minimum TRX out in Sun, overrides slippage | Returns: `{txResult, tokenAddress, tokensSold, expectedTrx, minTrxOut, tronscanUrl}`. **First-time sell**: the SDK auto-sends a TRC20 `approve(SunPump, 2^256-1)` before the actual sell tx if allowance is insufficient. Only the final sell tx hash is returned in `tronscanUrl`. #### Dry-run before execution ```bash sun --json --yes --dry-run sunpump buy TXYZ... --trx 10 sun --json --yes --dry-run sunpump sell TXYZ... --amount 1000 ``` Prints the resolved parameters (TRX/Sun scaling, computed `minOut`, slippage, network) without broadcasting. Useful for showing the user exactly what will be sent. #### Network SunPump is **mainnet only**. The CLI rejects any non-mainnet `--network` value with `SunPump is only available on mainnet (got "...")`. Router contract: `TTfvyrAz86hbZk5iDpKD78pqLGgi8C7AAw`. --- ### 3. User Position Check — `sun sunpump portfolio` List all SunPump-tracked tokens held by a wallet, including TRX-denominated value and portfolio weight. ```bash sun --json sunpump portfolio TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW ``` Options: | Flag | Description | |------|-------------| | `--include-zero` | Include zero-balance tokens | | `--min-trx <amount>` | Minimum TRX-equivalent value to include | | `--page <n>` / `--size <n>` | Pagination | | `--sort <field>` | Sort field (e.g. `valueInTrx,desc`) | #### Common patterns Top 20 positions worth at least 100 TRX: ```bash sun --json sunpump portfolio TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --min-trx 100 --size 20 --sort valueInTrx,desc ``` Default table columns: `Symbol | Address | Balance | Price (TRX) | Value (TRX) | Percent`. --- ### 4. Trade History — `sun sunpump tx user` List a wallet's SunPump swap activity. Each row is one buy or sell on the SunPump bonding curve or its SunSwap pool. ```bash sun --json sunpump tx user TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --size 20 ``` Filter options: | Flag | Description | |------|-------------| | `--swap-type <BUY\|SELL>` | Direction filter | | `--pool <address>` | Specific swap pool | | `--tx-hash <hash>` | Single transaction lookup | | `--block <n>` | Filter by block number | | `--start-time <epoch>` / `--end-time <epoch>` | Time range (epoch **seconds**) | | `--page <n>` / `--size <n>` | Pagination | | `--sort <field>` | Sort field (e.g. `txDateTime,desc`) | #### Common patterns Last 20 buys only: ```bash sun --json sunpump tx user TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --swap-type BUY --size 20 ``` Trades for one wallet in a window: ```bash sun --json sunpump tx user TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --start-time 1747699200 --end-time 1747785600 --size 50 ``` > **NOTE:** `--start-time` / `--end-time` are epoch **seconds**, not milliseconds. Convert ISO dates with `date -j -f "%Y-%m-%d" "2026-05-20" +%s` (macOS) or `date -d "2026-05-20" +%s` (Linux). Default table columns: `Time | Type | From → To | Volume | TxHash`. --- ### 5. Token Info — `sun sunpump token get`