release v1.2.0

@bankofai/sun-cli v1.2.0

HighLight

sun sunpump — read-only data (no wallet required)

• token list — paginated token list with filters and sort
• token get <addr> — token detail (price, market cap, holders, social links,
  listed CEXes); human mode prints a labelled key/value view, --json returns
  the raw object
• token search <q> / token search-v2 <q> — fuzzy search
• token by-owner <addr> — tokens created by a wallet
• token holders <addr> / token holders-v2 <addr> — top holders with a
  Type column distinguishing pools from users
• token favors — signed-message favourites lookup
• token ranking --type MARKET_CAP|VOLUME_24H|PRICE_CHANGE_24H
• token king-of-hill
• token pump-list — raw SunSwap-compatible token list
• tx token <addr> / tx user <addr> — swap history with filters
• portfolio <wallet> — wallet's SunPump positions with TRX value

sun sunpump — on-chain trading (wallet required)

• state <addr> — on-chain state with named label: 0 NOT_EXIST /
  1 TRADING / 2 READY_TO_LAUNCH / 3 LAUNCHED
• quote-buy <addr> --trx <decimal> — read-only buy preview
• quote-sell <addr> --amount <decimal> [--decimals 18] — read-only sell
  preview
• buy <addr> --trx <decimal> [--slippage 0.05] [--min-out <raw>] — spend TRX,
  receive tokens
• sell <addr> --amount <decimal> [--decimals 18] [--slippage 0.05] [--min-out <raw>]
  — sell tokens for TRX (auto-handles first-time TRC20 approval)

All write commands go through writeAction: wallet check → signed summary →
confirmation prompt → broadcast → Tronscan link. --dry-run and --yes work
as expected. Decimal inputs (--trx 10, --amount 1000) are scaled
internally by 1e6 (TRX → Sun) and 10^decimals (tokens → raw uint256).
Buy/sell summaries pre-fetch a quote so the user sees expected output and fee
before confirming.

Output & formatting improvements

• New table configs: tokenTable with a tokenPriceUsd fallback (no more
  $0 rows when the API omits the TRX/USD rate — falls back to
  marketCap / totalSupply); holderTable reading the correct percentage
  field with auto-detected fraction/percent units; portfolioTable;
  key/value detail view for token get.
• extractList recognises tokens (alongside the existing swaps/holders);
  readPagination descends into pageData / metadata and treats size as
  a pageSize alias.
• HTTP errors from SunPump now surface the API's msg field, e.g.
  SunPump request failed: 400 Bad Request (/token/getRanking) — Validation error: No enum constant ....

Notes & gotchas

• State enum off-by-one. sun-kit's exported SunPumpTokenState lists
  LAUNCHED = 2, but the on-chain contract returns 3 for tokens that have
  migrated to SunSwap. The CLI re-labels: state 3 prints as LAUNCHED (3).
  Trust the printed label, not the raw int.
• Quotes ignore on-chain state. quote-buy returns a price even for
  LAUNCHED tokens (and quote-sell may revert with
  REVERT opcode executed). The actual buy / sell pre-checks state and
  throws SUNPUMP_LAUNCHED cleanly — call sunpump state first if you're
  routing logic.
• First sell ≠ one transaction. When the wallet has zero allowance, the
  SDK auto-sends approve(SunPump, 2^256-1) before the sell tx. Only the
  final sell tx hash is returned in tronscanUrl.
• Default slippage for bonding-curve trading is 0.05 (5%) — meme tokens
  are volatile. Tighten with --slippage 0.005 or pass --min-out <raw> for
  an exact floor.

Companion release

sunpump-agent-skill
v1.2.0 ships in parallel — pins this CLI version, documents the new
buy/sell/quote-*/state commands as the pre-launch trade path with sun swap
as the post-launch path, and updates pre-validation checklists to enforce
--network mainnet.

Install

npm install -g @bankofai/sun-cli@^1.2.0
npx skills add BofAI/skills

release v1.1.0

sun-cli v1.1.0

Highlights

• Read commands now display all columns. A widespread mismatch between the SUN.IO API field names and the column mappings caused many cells to fall through to -. Fixed across 8 command groups (see below).
• token list shows a Protocol column. Resolves the appearance of "duplicate" rows when the API returns one record per protocol (ALL/V1/V2/V3/…).
• farm positions exposes subpool rewards. Governance farms (e.g. SUN-staking with WTRX bonus) now surface their secondary pending reward in a dedicated column.
• README rewrite with a tighter structure, scannable tables, a new Getting Help section, and shell-completion snippets for zsh/bash.

Fixed

Field mappings were corrected across every read command that uses the SUN.IO REST API. Each fix preserved existing fallback names for forward compatibility.

Command	Columns previously stuck on - (now populated)
token list, token search	Decimals, Volume 24h, Price, TVL
position list	Token0/Token1, Liquidity, Range, Token0/1 Amt, Value
position tick	Schema rewritten — now: Pool / Tick / Liquidity Net / Price 0→1 / Price 1→0
pool list	Vol 24h
pool hooks	Address, Name, Docs
pool vol-history	Restructured: Date / Volume USD / Fees USD / Tx Count
pool liq-history	Restructured: Date / Liquidity USD
pair info	Schema rewritten — now: Base / Quote / Protocol / Price / Base Vol 1d / Quote Vol 1d
farm list	Schema rewritten — now: Farm / Name / Type / Stake Token / Reward Token / APY / TVL
farm positions	Staked, Pending Reward
protocol info	Volume 24h, Users 24h, Pools, Tx 24h
protocol vol/users/tx/pools/liq-history (×5)	Date and metric value
tx scan	Token0/Token1, Amount0/Amount1, Time

Root cause: the toRow mappers were written against guessed field names (volume24h, tvl, decimals, tickLower, …) instead of the API's actual response shape (volumeUsd1d, reserveUsd, tokenDecimal, extraInfo.tick_lower, …).

Added

• token list / token search — new Protocol column. The SUN.IO /tokens endpoint returns one row per (protocol × token); without this column those rows looked like duplicates.
• farm positions — new Subpool Pending Reward column, formatted as <amount> <symbol> (e.g. 19.190937 WTRX). Pending Reward also now suffixes its own symbol (e.g. 0 SUN) so the value is unambiguous standalone.

Improved

• farm list schema replaced with a single-stake-token model (Farm / Name / Type / Stake Token / Reward Token / APY / TVL); the previous Token0/Token1 layout was inherited from LP-pool tables and didn't fit staking farms.
• pool top-apy, pool list, pool search — explicit tokenSymbolList / reserveUsd / totalApr fallbacks so live data renders without requiring deprecated field names.

Internal

• parseApiResponse already validates the SUN.IO envelope (code/message) and surfaces pagination metadata for list commands — this release leans on that infrastructure across all updated tables.
• All 106 existing tests pass; lint and TypeScript build are clean.

Upgrade

npm install -g @bankofai/sun-cli@1.1.0

No configuration or scripting changes required. JSON output keys are unchanged — agents and pipelines that consume --json will see the same structure they did in 1.0.x.

v1.0.2

sun-cli v1.0.2

What's Changed

Agent Wallet Integration Update

• Migrated wallet environment variables from TRON_PRIVATE_KEY / TRON_MNEMONIC / TRON_MNEMONIC_ACCOUNT_INDEX to AGENT_WALLET_PRIVATE_KEY / AGENT_WALLET_MNEMONIC / AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX for consistency with @bankofai/agent-wallet
• Simplified initWallet() to delegate fully to resolveWalletProvider() instead of manually mapping env vars
• Improved wallet init error handling — gracefully returns null on failure instead of throwing

Bug Fixes

• Fixed BigInt serialization in JSON output — bigint values are now stringified correctly instead of throwing TypeError
• Fixed version string — CLI version is now read dynamically from package.json instead of being hardcoded
• Removed unused printKeyValue import in liquidity commands

CI / Tooling

• Added audit-pr.yml GitHub Actions workflow for automated PR auditing
• Unified ESLint and lint configuration

Documentation

• Rewrote README with updated wallet configuration and usage instructions

Tests

• Added new tokens.test.ts test suite
• Updated existing test suites for compatibility with wallet changes

v1.0.0

sun-cli v1.0.0

Initial Release

This is the first public release of sun-cli, a terminal-first CLI for SUN.IO / SUNSWAP workflows on TRON.

sun-cli is designed for both human operators and AI agents, with support for interactive execution, machine-readable output, and wallet-aware transaction flows.

Included in v1.0.0

Core CLI Commands

This release includes command groups for:

• wallet access and balances
• token pricing and token discovery
• pool discovery and analytics
• swap quoting and swap execution
• liquidity management across V2, V3, and V4
• protocol metrics and history
• farm queries
• position and pair inspection
• transaction scanning
• generic contract read and send

Wallet Support

sun-cli uses a unified agent-wallet based flow and supports:

• TRON_PRIVATE_KEY
• TRON_MNEMONIC
• TRON_MNEMONIC_ACCOUNT_INDEX
• AGENT_WALLET_PASSWORD
• AGENT_WALLET_DIR

Root-level wallet flags are also supported for per-invocation overrides:

• -k, --private-key <key>
• -m, --mnemonic <phrase>
• -i, --mnemonic-account-index <index>
• -p, --agent-wallet-password <password>
• -d, --agent-wallet-dir <dir>

Output Modes

This release supports:

• table output for interactive terminal use
• compact JSON output for agents and scripts
• TSV output for shell pipelines
• field filtering with --fields
• --dry-run for write-flow previews
• --yes for non-interactive execution

Broadcast Result Enhancements

Successful write operations return transaction results with:

• txid
• route information when available
• tronscanUrl derived from the selected network

Supported explorer formats:

• mainnet → https://tronscan.org/#/transaction/<txid>
• nile → https://nile.tronscan.org/#/transaction/<txid>
• shasta → https://shasta.tronscan.org/#/transaction/<txid>

Tooling and Project Setup

This initial release also includes:

• Jest-based test coverage
• ESLint and Prettier configuration
• separate TypeScript configs for build and lint
• deterministic CI installs through dependency overrides
• rewritten product-style README with real command output examples

Notes

Wallet Behavior

Only one wallet source should be configured at a time.

Invocation-time wallet configuration follows this priority:

• root flags
• environment variables

Command Surface

The wallet command group in this initial release focuses on active wallet usage:

• wallet address
• wallet balances

Wallet management commands such as wallet listing and wallet switching are not part of sun-cli v1.0.0.

v1.0.0-beta

sun-cli v1.0.0

Initial Release

This is the first public release of sun-cli, a terminal-first CLI for SUN.IO / SUNSWAP workflows on TRON.

sun-cli is designed for both human operators and AI agents, with support for interactive execution, machine-readable output, and wallet-aware transaction flows.

Included in v1.0.0

Core CLI Commands

This release includes command groups for:

• wallet access and balances
• token pricing and token discovery
• pool discovery and analytics
• swap quoting and swap execution
• liquidity management across V2, V3, and V4
• protocol metrics and history
• farm queries
• position and pair inspection
• transaction scanning
• generic contract read and send

Wallet Support

sun-cli uses a unified agent-wallet based flow and supports:

• TRON_PRIVATE_KEY
• TRON_MNEMONIC
• TRON_MNEMONIC_ACCOUNT_INDEX
• AGENT_WALLET_PASSWORD
• AGENT_WALLET_DIR

Root-level wallet flags are also supported for per-invocation overrides:

• -k, --private-key <key>
• -m, --mnemonic <phrase>
• -i, --mnemonic-account-index <index>
• -p, --agent-wallet-password <password>
• -d, --agent-wallet-dir <dir>

Output Modes

This release supports:

• table output for interactive terminal use
• compact JSON output for agents and scripts
• TSV output for shell pipelines
• field filtering with --fields
• --dry-run for write-flow previews
• --yes for non-interactive execution

Broadcast Result Enhancements

Successful write operations return transaction results with:

• txid
• route information when available
• tronscanUrl derived from the selected network

Supported explorer formats:

• mainnet → https://tronscan.org/#/transaction/<txid>
• nile → https://nile.tronscan.org/#/transaction/<txid>
• shasta → https://shasta.tronscan.org/#/transaction/<txid>

Tooling and Project Setup

This initial release also includes:

• Jest-based test coverage
• ESLint and Prettier configuration
• separate TypeScript configs for build and lint
• deterministic CI installs through dependency overrides
• rewritten product-style README with real command output examples

Notes

Wallet Behavior

Only one wallet source should be configured at a time.

Invocation-time wallet configuration follows this priority:

• root flags
• environment variables

Command Surface

The wallet command group in this initial release focuses on active wallet usage:

• wallet address
• wallet balances

Wallet management commands such as wallet listing and wallet switching are not part of sun-cli v1.0.0.