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:

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

   npx skills add BofAI/skills
   

2. Verify sun-cli:

   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:

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

   export TRON_PRIVATE_KEY="your_private_key_here"
   

   Alternative wallet sources: TRON_MNEMONIC or AGENT_WALLET_PASSWORD.

4. Optional environment variables:

   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:

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.

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

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

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

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:

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:

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

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

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

Options:

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:

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

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

   sun --json wallet balances
   

2. For sells, confirm token balance ≥ --amount. The SunPump portfolio API may not yet include the token; query the TRC20 balance directly:

   sun --json contract read <tokenAddress> balanceOf --args "[\"<walletAddress>\"]"
   

3. Resolve token decimals before passing --amount for sell. Decimals default to 18 but can differ:

   sun --json sunpump token get <memeTokenAddress>  # read decimals
   sun --json --yes sunpump sell <token> --amount 1000 --decimals <n>
   

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

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

Before sun swap (post-launch path)

1. Check balance is sufficient:

   sun --json wallet balances
   

   Compare the token balance against amountIn. Abort if insufficient.

2. Verify the token is launched:

   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.

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

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

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

2. 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).

3. Check for an existing token with the same symbol to avoid confusing duplicates:

   sun --json sunpump token search <symbol>
   

   If close matches exist, surface them to the user and confirm intent.

4. Dry-run and show the user the exact payload before the real call:

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

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

6. 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
• state == 1 or 2 (still bonding) → follow Pattern 1b
• 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.

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

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

• Skill version: 2.0.0
• Runtime dependency: @sun-protocol/sun-cli@1.2.2 Last Updated: 2026-07-09 Maintainer: Bank of AI Team