| name | SunPump Meme Token Toolkit |
| description | Create meme tokens on SunPump (`sun sunpump launch`), trade them — both pre-launch (bonding curve via `sun sunpump buy/sell`) and post-launch (SunSwap via `sun swap`) — and query token info, rankings, holders, portfolios, and trade history. |
| version | 1.4.0 |
| dependencies | ["@sun-protocol/sun-cli"] |
| tags | ["defi","meme","tron","sunpump","sunswap"] |
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:
- Create (launch) a new meme token (
sun sunpump launch) — server-side creation, no wallet needed
- Trade post-launch tokens through SunSwap (
sun swap)
- Trade pre-launch tokens on the SunPump bonding curve (
sun sunpump buy / sun sunpump sell)
- Check a wallet's positions (
sun sunpump portfolio)
- View a wallet's trade history (
sun sunpump tx user)
- Look up token info (
sun sunpump token get)
- See token rankings (
sun sunpump token ranking)
- 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.
-
Install this skill (once, picked up by Claude Code / Cursor / Codex):
npx skills add BofAI/skills
-
Install sun-cli (≥ 1.2.2 required — includes sunpump launch, bonding-curve trading, and wallet-free --dry-run previews):
npm install -g @sun-protocol/sun-cli@^1.2.2
-
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.
-
Optional environment variables:
export TRON_NETWORK=mainnet
export TRONGRID_API_KEY=your_key
export SUNPUMP_API_BASE_URL=...
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.
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:
| 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
sun --json --yes sunpump buy TXYZ... --trx 10 --min-out 27955000000000000000000
| 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
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>
sun --json sunpump state <contractAddress>
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 SunPumpstate == 1 (TRADING) or 2 (READY_TO_LAUNCH) → use sun sunpump buy/sellstate == 3 (LAUNCHED) → use sun swap
Before sun sunpump buy / sun sunpump sell (pre-launch path)
-
Check TRX balance is sufficient for --trx plus gas reserve (≥1 TRX recommended):
sun --json wallet balances
-
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>\"]"
-
Resolve token decimals before passing --amount for sell. Decimals default to 18 but can differ:
sun --json sunpump token get <memeTokenAddress>
sun --json --yes sunpump sell <token> --amount 1000 --decimals <n>
-
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.
-
--network must be mainnet. The CLI throws immediately on any other value.
Before sun swap (post-launch path)
-
Check balance is sufficient:
sun --json wallet balances
Compare the token balance against amountIn. Abort if insufficient.
-
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.
-
Verify tokenIn ≠ tokenOut. Same-token swaps are not rejected by --dry-run.
-
Validate slippage is reasonable. Meme tokens often need 1–5% slippage; flag anything outside 0.001 (0.1%) – 0.10 (10%) for review.
-
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)
-
Confirm all three required fields with the user: --name, --symbol, --description. Never invent or autofill these — they are permanent on-chain metadata.
-
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).
-
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.
-
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
-
--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.
-
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 1astate == 1 or 2 (still bonding) → follow Pattern 1bstate == 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
sun --json wallet balances
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
sun --json wallet balances
sun --json --yes sunpump buy TXYZ... --trx 10
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...
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>
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):
sun --json sunpump state <address> — determine trade path (pre/post-launch)sun --json sunpump token get <address> — show metadata, holder concentration, decimals- Quote —
sun --json swap:quote ... or sun --json sunpump quote-buy/sell ... — show expected output, fee, price impact
sun --json wallet balances — confirm sufficient funds- Ask the user to confirm
- 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:
- Collect
--name / --symbol / --description / logo from the user — never invent them
sun --json sunpump token search <symbol> — surface symbol collisionssun --json --yes --dry-run sunpump launch ... — show the user the exact payload- Ask the user to confirm
- 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
