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: Run agent-wallet list first. If no wallets exist, invoke bankofai-guide (Section C — Wallet Guard) before proceeding. 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 ```

1. Install sun-cli (≥ 1.2.2 required — includes sunpump launch, bonding-curve trading, and wallet-free --dry-run previews): ```bash npm install -g @sun-protocol/sun-cli@^1.2.2 ```

1. 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.

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

sun --json sunpump token get TXYZ...

Write operation (swap) with explicit confirmation skip:

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)

sun --json swap:quote TRX TXYZ1234567890abcdefghijklmnopqrstuv 100000000

Show the user: amountOut, price impact, and route.

Step B — Buy (TRX → meme token)

sun --json --yes swap TRX TXYZ1234567890abcdefghijklmnopqrstuv 100000000 --slippage 0.01

Step C — Sell (meme token → TRX)

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

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

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)

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)

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)

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

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.

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:

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.

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:

sun --json sunpump tx user TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --swap-type BUY --size 20

Trades for one wallet in a window:

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

Fetch full metadata for a SunPump token by its contract address. Returns price, market cap, 24h volume, holder count, total supply, owner, swap pool address, social links, and launch state.

sun --json sunpump token get TXYZ1234567890abcdefghijklmnopqrstuv

In human-readable mode (without --json), the CLI prints a labelled detail view; in JSON mode it returns the raw token object.

Fields to read

| Field | Meaning | |-------|---------| | contractAddress | TRC20 address of the meme token | | symbol, name, description | Display metadata | | priceInTrx, priceInUsd | Current price | | marketCap, volume24Hr | Market metrics (USD) | | priceChange24Hr | 24h price change (decimal, e.g. 0.18 = +18%) | | holders, totalSupply | Distribution stats | | tokenCreatedInstant | Bonding-curve creation time | | tokenLaunchedInstant | SunSwap launch time (null if not yet launched) | | swapPoolAddress | Pool to trade through (null pre-launch) | | pumpPercentage | Bonding curve fill % (pre-launch only) | | ownerAddress | Creator's wallet | | websiteUrl, twitterUrl, telegramUrl, listOn | Social and CEX listings |

Limit output for low-context responses

sun --json --fields symbol,priceInUsd,marketCap,volume24Hr,priceChange24Hr sunpump token get TXYZ...

---

6. Ranking — sun sunpump token ranking

Get the top SunPump tokens by a chosen metric. --type is required.

sun --json sunpump token ranking --type MARKET_CAP --size 10

Valid --type values (case-sensitive):

| Value | Meaning | |-------|---------| | MARKET_CAP | Largest tokens by market capitalization | | VOLUME_24H | Highest 24-hour trading volume | | PRICE_CHANGE_24H | Top 24-hour price gainers |

IMPORTANT: Other type values are rejected by the API. Always validate --type before calling.

Options:

| Flag | Description | |------|-------------| | --size <n> | Number of entries (default depends on server, typical max 50) |

Common patterns

Top 10 by market cap:

sun --json sunpump token ranking --type MARKET_CAP --size 10

Top 10 by 24h volume:

sun --json sunpump token ranking --type VOLUME_24H --size 10

Top 10 24h gainers:

sun --json sunpump token ranking --type PRICE_CHANGE_24H --size 10

Default table columns: Symbol | Name | Address | Price | MCap | Volume24h.

---

7. Top Holders — sun sunpump token holders

List the top wallets holding a given SunPump token, with balance and percentage.

sun --json sunpump token holders TXYZ1234567890abcdefghijklmnopqrstuv --size 20

Options:

| Flag | Description | |------|-------------| | --include-zero | Include zero-balance wallets | | --page <n> / --size <n> | Pagination | | --sort <field> | Sort field (default: balance descending) |

Default table columns: Holder | Type | Balance | Percent.

NOTE: The percent field on the holders endpoint is already a percent value (e.g. 38.51 = 38.51%), whereas the token-list endpoint returns it as a fraction (e.g. 0.3851 = 38.51%). The CLI auto-detects which form it is — but if you read the raw JSON, check the magnitude before interpreting.

If holders results look thin, also call sunpump token get <address> and read the holders field for the total count.

---

8. Token Creation — sun sunpump launch

Create a new meme token on SunPump through the agent endpoint (POST /ai/agentTokenLaunch). Creation is server-side: the platform signs and broadcasts the creation transaction, so no wallet is required. The new token starts on the bonding curve (state 1 TRADING) and is immediately buyable via sun sunpump buy.

sun --json --yes sunpump launch \
  --name "My Meme" \
  --symbol MEME \
  --description "The dankest meme on TRON" \
  --image ./logo.png \
  --twitter-url https://x.com/mymeme \
  --telegram-url https://t.me/mymeme \
  --website-url https://mymeme.example

| Flag | Required | Description | |------|----------|-------------| | --name <name> | ✓ | Token name | | --symbol <symbol> | ✓ | Token symbol (ticker) | | --description <text> | ✓ | Token description | | --image <path> | strongly recommended | Logo image file — read locally and sent as base64 | | --image-base64 <data> | | Logo as a raw base64 string (no data-URI prefix; overrides --image) | | --twitter-url <url> | | Twitter/X URL | | --telegram-url <url> | | Telegram URL | | --website-url <url> | | Website URL | | --tweet-username <name> | | Tweet username to associate with the launch |

Returns the full token object including contractAddress, createTxHash, and logoUrl.

WARNING: Provide a logo. Launching without --image / --image-base64 has been seen to fail with the opaque server error Invoke third part error. Always attach a logo image; if you hit that error, retry with --image <path>.

NOTE: timestamp quirk in --json mode. Unlike the GET endpoints (epoch seconds), the launch endpoint serializes tokenCreatedInstant / tokenLaunchedInstant / firstReachHillInstant as epoch-millis ÷ 1e6 (e.g. 1780476.327). The CLI normalizes these only for the human-readable view — in --json mode you get the raw values. Multiply by 1000 to get epoch seconds.

WARNING: mainnet only. Like every sunpump subcommand, launch is mainnet-only. The sunpump command group runs a preAction guard that throws SunPump is only available on mainnet (got "...") for any non-mainnet --network — before the action runs, so it fires even on --dry-run. Drop --network or pass --network mainnet.

Dry-run first

sun --json --yes --dry-run sunpump launch --name "My Meme" --symbol MEME --description "..." --image ./logo.png

Prints the resolved parameters (including the image size) without calling the API — use this to show the user exactly what will be created. The mainnet guard still applies (--dry-run --network nile errors out before previewing).

Verify after creation

sun --json sunpump token get <contractAddress>     # metadata is live
sun --json sunpump state <contractAddress>         # expect state 1 (TRADING)

---

Agent Pre-Validation Checklist

Before executing any write operation (sun swap, sun sunpump buy, sun sunpump sell, sun sunpump launch), the AI agent must perform these checks:

Step 0 — Decide which trade path to use

sun --json sunpump state <memeTokenAddress>

• state == 0 (NOT_EXIST) → abort: token unknown to SunPump
• state == 1 (TRADING) or 2 (READY_TO_LAUNCH) → use sun sunpump buy/sell
• state == 3 (LAUNCHED) → use sun swap

Before sun sunpump buy / sun sunpump sell (pre-launch path)

1. Check TRX balance is sufficient for --trx plus gas reserve (≥1 TRX recommended): ```bash sun --json wallet balances ```

1. For sells, confirm token balance ≥ --amount. The SunPump portfolio API may not yet include the token; query the TRC20 balance directly: ```bash sun --json contract read <tokenAddress> balanceOf --args "[\"<walletAddress>\"]" ```

1. Resolve token decimals before passing --amount for sell. Decimals default to 18 but can differ: ```bash sun --json sunpump token get <memeTokenAddress> # read decimals sun --json --yes sunpump sell <token> --amount 1000 --decimals <n> ```

1. Validate slippage is in range 0.005–0.10 (0.5%–10%). Default is 5%, which suits meme tokens; reject anything outside this band without user confirmation.

1. --network must be mainnet. The CLI throws immediately on any other value.

Before sun swap (post-launch path)

1. Check balance is sufficient: ```bash sun --json wallet balances ``` Compare the token balance against amountIn. Abort if insufficient.

1. Verify the token is launched: ```bash sun --json sunpump token get <memeTokenAddress> ``` tokenLaunchedInstant must be non-null and swapPoolAddress must be set. If pre-launch, route to the sun sunpump buy/sell path instead.

1. Verify tokenIn ≠ tokenOut. Same-token swaps are not rejected by --dry-run.

1. Validate slippage is reasonable. Meme tokens often need 1–5% slippage; flag anything outside 0.001 (0.1%) – 0.10 (10%) for review.

1. Validate --network. sun swap accepts mainnet / nile / shasta for general TRC20 pairs, but SunPump-migrated tokens are still mainnet-only — check the migration target before quoting on a non-mainnet network.

Before sun sunpump launch (token creation)

1. Confirm all three required fields with the user: --name, --symbol, --description. Never invent or autofill these — they are permanent on-chain metadata.

1. Require a logo image. Launching without one often fails with Invoke third part error. Ask the user for an image file path (or base64 data) before proceeding; verify the file exists and is a reasonable image (PNG/JPG, < 1 MB recommended).

1. Check for an existing token with the same symbol to avoid confusing duplicates: ```bash sun --json sunpump token search <symbol> ``` If close matches exist, surface them to the user and confirm intent.

1. Dry-run and show the user the exact payload before the real call: ```bash sun --json --yes --dry-run sunpump launch --name "..." --symbol ... --description "..." --image ./logo.png ```

1. --network must be mainnet. SunPump launch is mainnet-only; the sunpump group's preAction guard throws on any other value, including under --dry-run. Drop --network or pass --network mainnet.

1. Get explicit user confirmation, then launch once. Token creation is irreversible — never retry a launch that may have succeeded; verify with sun sunpump token search <symbol> first.

Before Read-Only Calls

• Validate --type for token ranking is MARKET_CAP, VOLUME_24H, or PRICE_CHANGE_24H.
• Convert any user-provided dates to epoch seconds (not ms) before passing to tx user --start-time / --end-time.
• Verify the address is a TRON base58 (T..., 34 chars). Bad addresses return empty results or an opaque API error.

---

Recommended Workflows

Pattern 1 — Buy a Meme Token (auto-routes pre/post-launch)

Step 1 — Determine the trade path:

sun --json sunpump state TXYZ...

• state == 3 (LAUNCHED) → follow [Pattern 1a](#pattern-1a--post-launch-buy-via-sun-swap)
• state == 1 or 2 (still bonding) → follow [Pattern 1b](#pattern-1b--pre-launch-buy-via-sun-sunpump-buy)
• state == 0 (NOT_EXIST) → abort

Also pull metadata for the user-facing preview:

sun --json sunpump token get TXYZ...

Show the user: price, 24h change, market cap, holders, plus the top-5-holder concentration warning if applicable.

Pattern 1a — Post-launch buy via sun swap

sun --json swap:quote TRX TXYZ... 100000000             # quote (no wallet)
sun --json wallet balances                              # check funds
sun --json --yes swap TRX TXYZ... 100000000 --slippage 0.01

Pattern 1b — Pre-launch buy via sun sunpump buy

sun --json sunpump quote-buy TXYZ... --trx 10           # quote (no wallet)
sun --json wallet balances                              # check funds
sun --json --yes sunpump buy TXYZ... --trx 10           # default 5% slippage

Inputs are decimal: --trx 10 means 10 TRX, not 10 Sun. Default slippage is 0.05 (5%) — meme bonding-curve trades move fast. Use --slippage 0.005 to tighten, or --min-out <raw> to lock a floor in base units.

---

Pattern 2 — Sell a Position (auto-routes pre/post-launch)

Step 1 — List the user's positions:

sun --json sunpump portfolio TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --min-trx 1 --size 50

Step 2 — User picks a token. Determine path:

sun --json sunpump state TXYZ...
sun --json sunpump token get TXYZ...        # also read `decimals` for sell amount scaling

Pattern 2a — Post-launch sell via sun swap

sun --json swap:quote TXYZ... TRX <amountInSmallestUnits>
sun --json --yes swap TXYZ... TRX <amount> --slippage 0.02

Pattern 2b — Pre-launch sell via sun sunpump sell

sun --json sunpump quote-sell TXYZ... --amount 1000 --decimals 18
sun --json --yes sunpump sell TXYZ... --amount 1000 --decimals 18

First sell of a given token triggers an automatic TRC20 approve tx — only the final sell tx hash is returned.

---

Pattern 3 — Discover and Research

Top gainers right now:

sun --json sunpump token ranking --type PRICE_CHANGE_24H --size 10

Inspect one:

sun --json sunpump token get TXYZ...

Check holder concentration:

sun --json sunpump token holders TXYZ... --size 20

A few wallets holding >50% combined is a red flag — surface this to the user.

---

Pattern 4 — Audit a Wallet

Current holdings:

sun --json sunpump portfolio T... --min-trx 1 --sort valueInTrx,desc --size 50

Recent trades:

sun --json sunpump tx user T... --size 20 --sort txDateTime,desc

Filter to buys only:

sun --json sunpump tx user T... --swap-type BUY --size 20

---

Pattern 5 — Launch a New Token

Step 1 — Collect and confirm metadata with the user: name, symbol, description, logo image, optional social links.

Step 2 — Check for symbol collisions:

sun --json sunpump token search MEME

Step 3 — Dry-run and show the user the payload:

sun --json --yes --dry-run sunpump launch --name "My Meme" --symbol MEME --description "..." --image ./logo.png

Step 4 — User confirms → launch (once):

sun --json --yes sunpump launch --name "My Meme" --symbol MEME --description "..." --image ./logo.png \
  --twitter-url https://x.com/mymeme --telegram-url https://t.me/mymeme --website-url https://mymeme.example

Step 5 — Verify and hand back:

sun --json sunpump token get <contractAddress>
sun --json sunpump state <contractAddress>      # expect 1 (TRADING)

Show the user: contract address, creation tx hash (createTxHash), logo URL, and a Tronscan link (https://tronscan.org/#/transaction/<createTxHash>). The token is now live on the bonding curve and buyable via [Pattern 1b](#pattern-1b--pre-launch-buy-via-sun-sunpump-buy).

---

Security Rules

CRITICAL: Never Display Private Keys

FORBIDDEN: private keys, seed phrases, mnemonics, env-var values that contain secrets, agent-wallet passwords.

ALLOWED: public wallet addresses, transaction hashes, token balances, prices.

CRITICAL: Always Preview Before Trading

The AI agent must never execute sun swap or sun sunpump buy/sell without first showing the user a preview. Correct sequence (both paths):

1. sun --json sunpump state <address> — determine trade path (pre/post-launch)
2. sun --json sunpump token get <address> — show metadata, holder concentration, decimals
3. Quote — sun --json swap:quote ... or sun --json sunpump quote-buy/sell ... — show expected output, fee, price impact
4. sun --json wallet balances — confirm sufficient funds
5. Ask the user to confirm
6. Execute with --yes: sun --json --yes swap ... or sun --json --yes sunpump buy/sell ...

WARNING: Do not pass --yes on the first call. Use --yes only after the user has reviewed the preview and confirmed.

CRITICAL: Always Preview Before Launching a Token

sun sunpump launch creates a permanent on-chain token. Correct sequence:

1. Collect --name / --symbol / --description / logo from the user — never invent them
2. sun --json sunpump token search <symbol> — surface symbol collisions
3. sun --json --yes --dry-run sunpump launch ... — show the user the exact payload
4. Ask the user to confirm
5. Execute once with --yes

CRITICAL: Prevent Duplicate Transactions

• One user command = one transaction
• After a successful swap or launch, mark it as done
• Never silently retry a successful transaction
• For launch: if the call errors ambiguously (timeout, opaque server error), check sun sunpump token search <symbol> before retrying — the token may already exist

CRITICAL: Highlight Holder Concentration

Meme tokens are vulnerable to rug pulls. When surfacing token info to the user, also surface holder concentration. If the top 5 holders combined hold >40% of supply, warn the user explicitly.

---

User Communication Protocol

Before a swap:

Token: PEPE (TXYZ...)
  Price: $0.000123  •  24h: +18.4%  •  MCap: $2.4M  •  Holders: 1,420
  Top 5 hold: 31.2%

Quote: 100 TRX → 812,344 PEPE
  Route: TRX → WTRX → PEPE
  Price Impact: 0.42%
  Slippage tolerance: 1%

Proceed with buy?

After success:

Swap completed.
  Transaction: abc123...
  Explorer:    https://tronscan.org/#/transaction/abc123...
  Bought:      100 TRX → 812,344 PEPE

Before a token launch:

About to create a new SunPump token (irreversible):
  Name:        My Meme
  Symbol:      MEME
  Description: The dankest meme on TRON
  Logo:        ./logo.png (24,310 bytes)
  Socials:     x.com/mymeme • t.me/mymeme • mymeme.example

No similarly-named token found on SunPump.

Proceed with launch?

After a successful launch:

Token created.
  Contract:  TXYZ...
  Create Tx: abc123...
  Explorer:  https://tronscan.org/#/transaction/abc123...
  Logo:      https://.../logo.png
  State:     TRADING (bonding curve) — buyable via `sun sunpump buy`

---

Known Limitations

| Issue | Affected Commands | Behavior | Agent Workaround | |-------|-------------------|----------|------------------| | --dry-run doesn't check balances | swap | Returns preview even if balance is insufficient | Check wallet balances first | | Same-token swap not rejected | swap | Accepts TRX→TRX in dry-run | Verify tokenIn ≠ tokenOut before calling | | Pre-launch tokens not on SunSwap | swap against a SunPump token | Pool doesn't exist; swap will fail on-chain | Use sun sunpump buy/sell instead — verify via sunpump state | | sunpump quote-buy/sell ignores state | sunpump quote-* | Returns a price even on LAUNCHED tokens (quote-sell may revert) | Always call sunpump state before quoting | | sun-kit enum mislabels state 2 vs 3 | sunpump.buyToken/sellToken internal check | TS enum says LAUNCHED=2 but contract returns 3 for launched | CLI relabels: trust the printed LAUNCHED (3) label, not raw int | | First sell needs TRC20 approve | sunpump sell | Two on-chain txs (approve + sell), only sell tx hash returned | Expected; subsequent sells use cached MaxUint256 allowance | | SunPump is mainnet only | All sunpump subcommands | CLI throws SunPump is only available on mainnet on any other --network | Drop --network or pass --network mainnet; the nile/shasta API hosts aren't publicly reachable | | Invalid --type for ranking | token ranking | API rejects with non-obvious error | Only pass MARKET_CAP, VOLUME_24H, or PRICE_CHANGE_24H | | --start-time / --end-time are seconds, not ms | tx user, tx token | Ms values produce empty results | Use epoch seconds | | percent field magnitude differs by endpoint | token holders vs token list | Holders endpoint returns 38.51, list endpoint returns 0.3851 | The CLI normalizes, but check magnitude when consuming raw JSON | | Launch without a logo fails opaquely | sunpump launch | Server returns Invoke third part error when no image accompanies the launch | Always pass --image <path> (or --image-base64) | | Launch *Instant fields use a non-standard unit | sunpump launch (--json mode) | tokenCreatedInstant etc. come back as epoch-millis ÷ 1e6 (e.g. 1780476.327), not epoch seconds | Multiply by 1000 for epoch seconds; the CLI only normalizes in human-readable mode |

---

Troubleshooting

"sun: command not found"

npm install -g @sun-protocol/sun-cli@^1.2.2

Empty results from a SunPump query

• Confirm the address is a valid TRON base58 (T..., 34 chars)
• Try the same command without filters to isolate which option excludes everything
• For tx user time windows, confirm timestamps are epoch seconds

Swap fails on a SunPump token

• Run sun sunpump state <address> first. If state is 1 (TRADING) or 2 (READY_TO_LAUNCH), use sun sunpump buy/sell — not sun swap.
• If state is 3 (LAUNCHED) and swap still fails, try increasing --slippage (meme pools often need 1–5%).
• Ensure ≥ 100 TRX for gas in the wallet.

sun sunpump buy/sell fails with SUNPUMP_LAUNCHED

The token has already migrated to SunSwap. Switch to sun swap.

sun sunpump sell quote-sell reverts

The token is in state 3 (LAUNCHED). The bonding-curve contract refuses sells once a token has migrated. Use sun swap instead.

sun sunpump launch fails with Invoke third part error

The launch most likely lacked a logo image. Retry with --image <path> (or --image-base64 <data>). If it still fails, check the image is a valid PNG/JPG and try a smaller file.

sun sunpump launch timed out or returned an ambiguous error

The token may still have been created server-side. Before retrying, check:

sun --json sunpump token search <symbol>

If the token exists, treat the launch as successful — do not launch again.

"Wallet not configured" (write commands only)

Set one of TRON_PRIVATE_KEY, TRON_MNEMONIC, or AGENT_WALLET_PASSWORD. Read-only sunpump commands, sunpump launch, and --dry-run previews do not need a wallet.

Network error / timeout

• Check internet
• For mainnet, set TRONGRID_API_KEY
• SunPump itself is mainnet-only — testnet API host is internal-only and not publicly reachable

---

Version: 1.4.0 (sun-protocol sun-cli scope) Last Updated: 2026-07-09 Maintainer: Bank of AI Team