sunswap-dex-trading

name	SunSwap DEX Trading
description	Execute token swaps, manage liquidity, and query market data on SunSwap DEX via the sun-cli.
version	3.3.0
dependencies	["@sun-protocol/sun-cli"]
tags	["defi","dex","swap","liquidity","tron","sunswap"]

SunSwap DEX Trading Skill

Quick Start

This skill enables AI agents to interact with SunSwap DEX on the TRON blockchain through sun-cli — a unified CLI for quoting swaps, executing trades, managing liquidity (V2/V3/V4), querying pools, prices, positions, and more.

Prerequisites

Wallet required for real writes only: Run agent-wallet list before executing swaps, liquidity changes, or contract send. Read-only queries and --dry-run previews do not need a wallet. If no wallets exist, invoke bankofai-guide (Section C — Wallet Guard) before proceeding.

1. Install sun-cli (globally):

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

2. Configure wallet (required for write operations only):

   export TRON_PRIVATE_KEY="your_private_key_here"
   

   Alternative wallet sources: TRON_MNEMONIC or AGENT_WALLET_PASSWORD.

3. Optional environment variables:

   export TRON_NETWORK=mainnet
   export TRONGRID_API_KEY=your_key
   

Read-only commands (price, quote, pool list, etc.) and --dry-run previews work without wallet credentials.

---

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
--dry-run	Simulate write operations without sending transactions
--fields	Limit output to specific comma-separated fields
--network	Override network: mainnet, nile, shasta

Standard agent invocation pattern:

sun --json price TRX

Write operations add --yes to skip prompts:

sun --json --yes swap TRX USDT 100000000

WARNING: --network only accepts mainnet, nile, or shasta. Invalid network names silently fall back to mainnet without error. The AI agent must validate the network value before passing it.

WARNING: --dry-run only builds a transaction preview. It does NOT check balances, validate fee tiers, verify tick alignment, or reject same-token swaps. The agent must perform these validations before executing. See Agent Pre-Validation Checklist below.

---

Agent Pre-Validation Checklist

Before executing any write operation (swap, liquidity, contract send), the AI agent must perform the following checks. The CLI's --dry-run does not validate these — it only builds a transaction preview.

Before Swap

1. Check balance is sufficient:

   sun --json wallet balances
   

   Compare the token balance against the amountIn. Abort if insufficient.

2. Verify tokenIn ≠ tokenOut: Same-token swaps (e.g. TRX → TRX) are not rejected by --dry-run. The agent must check that the two tokens are different before executing.

3. Validate slippage is reasonable: Recommended range: 0.001 (0.1%) to 0.05 (5%). Warn the user if outside this range.

Before V3 Liquidity (Mint)

1. Use only valid fee tiers: 100, 500, 3000, or 10000. Invalid fee values (e.g. 9999) are not rejected by --dry-run.

2. Ensure ticks are aligned to tick spacing:

   Fee Value	Tick Spacing	Valid tick examples
   100	1	any integer
   500	10	-10, 0, 10, 20
   3000	60	-120, -60, 0, 60
   10000	200	-400, -200, 0, 200

   Both --tick-lower and --tick-upper must be exact multiples of the tick spacing. Misaligned ticks are not rejected by --dry-run but will fail on-chain.

3. Check balance is sufficient for both token0 and token1 amounts.

Before V3/V4 Position Operations (Increase/Decrease/Collect)

1. Verify token-id exists: Query the user's positions first:

   sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --protocol V3
   

   Confirm the target --token-id appears in the result. Passing a non-existent token-id may produce misleading errors (e.g. "amount required" instead of "position not found").

Before V2 Liquidity (Add)

1. Check balance is sufficient for both token-a and token-b amounts.

General

• Validate --network is one of: mainnet, nile, shasta. Invalid values silently fall back to mainnet.
• Validate --type for tx scan is one of: swap, add, withdraw. Invalid values return empty results instead of errors.

---

Command Reference

1. Wallet

Check wallet address and token balances.

sun --json wallet address

sun --json wallet balances

Check balances for a specific owner address:

sun --json wallet balances --owner TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf

Filter by specific tokens (contract addresses only, symbols like TRX/USDT are NOT supported):

sun --json wallet balances --tokens TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t,TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR

WARNING: --tokens only accepts contract addresses. Passing symbols (e.g. TRX,USDT) will return Invalid contract address provided. Use the address table in Supported Token Symbols to resolve symbols to addresses first.

---

2. Token Price

Fetch token prices from SUN.IO.

sun --json price TRX

sun --json price USDT

Query by contract address:

sun --json price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

---

3. Swap Quote (Read-Only)

Get a price quote without executing. No wallet required.

Parameters: tokenIn and tokenOut accept token symbols (TRX, USDT) or TRC20 addresses. amountIn is in sun (smallest unit, e.g. 1000000 = 1 TRX).

sun --json swap:quote TRX USDT 100000000

Quote with all route details:

sun --json swap:quote TRX USDT 100000000 --all

Quote on a specific network:

sun --json swap:quote TRX USDT 100000000 --network nile

Reverse direction:

sun --json swap:quote USDT TRX 1000000

---

4. Execute Swap

Execute a token swap through the SunSwap Universal Router.

Parameters: tokenIn and tokenOut accept symbols or addresses. amountIn is in sun. --slippage is a decimal (default: 0.005 = 0.5%).

sun --json --yes swap TRX USDT 100000000

Swap with custom slippage (1%):

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

Dry-run (simulate without sending):

sun --json --yes --dry-run swap TRX USDT 100000000

Use contract addresses instead of symbols:

sun --json --yes swap T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 100000000

Swap on nile testnet:

sun --json --yes swap TRX USDT 1000000 --network nile

---

5. V2 Liquidity

Add or remove liquidity on SunSwap V2 AMM pools.

Parameters for add: --token-a and --token-b accept symbols or addresses. --amount-a and --amount-b are in sun. Optional: --min-a, --min-b, --to, --deadline.

Parameters for remove: --token-a, --token-b, --liquidity (raw LP amount). Optional: --min-a, --min-b, --to, --deadline.

Add Liquidity

Single-side (auto-calculate other):

sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000

Both sides:

sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000

Dry-run:

sun --json --yes --dry-run liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000

With minimum amounts and recipient:

sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 --min-a 950000 --min-b 275000

Remove Liquidity

sun --json --yes liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000

Dry-run:

sun --json --yes --dry-run liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000

---

6. V3 Liquidity (Concentrated)

Manage concentrated liquidity positions on SunSwap V3.

Fee tiers (only these values are valid):

Fee Rate	Fee Value	Tick Spacing	Full Range Ticks
0.01%	100	1	-887272 / 887272
0.05%	500	10	-887270 / 887270
0.3%	3000	60	-887220 / 887220
1%	10000	200	-887200 / 887200

IMPORTANT: --fee must be exactly one of: 100, 500, 3000, 10000. Other values are NOT rejected by --dry-run but will fail on-chain.

--tick-lower and --tick-upper must be exact multiples of the tick spacing. Misaligned ticks are NOT rejected by --dry-run but will fail on-chain.

Parameters for mint: --token0, --token1 (symbol or address), --fee, --tick-lower, --tick-upper, --amount0, --amount1. Optional: --recipient, --deadline.

Mint New Position

Full-range with defaults:

sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000

With specific fee and tick range (fee=3000, tick spacing=60):

sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000

Dry-run:

sun --json --yes --dry-run liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000

With specific fee tier (fee=500, tick spacing=10):

sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 500 --tick-lower -887270 --tick-upper 887270 --amount0 1000000

With recipient:

sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -60 --tick-upper 60 --amount0 1000000 --recipient TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW

Increase Position

sun --json --yes liquidity v3:increase --token-id 123 --amount0 500000

Decrease Position

sun --json --yes liquidity v3:decrease --token-id 123 --liquidity 1000

Collect Fees

sun --json --yes liquidity v3:collect --token-id 123

---

7. V4 Liquidity

Manage liquidity on SunSwap V4 pools (with hooks support).

Parameters for mint: --token0, --token1, --fee, --tick-lower, --tick-upper, --amount0, --amount1. Optional: --slippage, --recipient, --create-pool.

Mint New Position

sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000

Create pool if it does not exist:

sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool

With slippage:

sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --slippage 0.01

Dry-run:

sun --json --yes --dry-run liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000

Increase Position

sun --json --yes liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000

Decrease Position

sun --json --yes liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT

Collect Fees

sun --json --yes liquidity v4:collect --token-id 123

Query Position Info

sun --json liquidity v4:info --pm TLSWrv7eC1AZCXkRjpqMZUmvgd99cj7pPF --token-id 123

---

8. Pool Discovery

Search and inspect liquidity pools.

List pools by token address:

sun --json pool list --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Search by keyword:

sun --json pool search "TRX USDT"

Top APY pools:

sun --json pool top-apy --page-size 10

Pool volume history (requires a pool address):

sun --json pool vol-history TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx --start 2026-01-01 --end 2026-03-15

Pool liquidity history:

sun --json pool liq-history TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx --start 2026-01-01 --end 2026-03-15

Pool hooks (V4):

sun --json pool hooks

---

9. Token Discovery

Search and list token metadata.

sun --json token list

Filter by protocol:

sun --json token list --protocol V3

Search by keyword:

sun --json token search USDT

---

10. Position Management

Query user liquidity positions.

List all positions for an owner:

sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW

Filter by protocol:

sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --protocol V3

Pool tick info:

sun --json position tick TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx

---

11. Pair Info

Resolve trading pair information.

WARNING: pair info --token only accepts contract addresses. Passing a symbol (e.g. USDT) will fail with an API error or return unexpected results. Always resolve the symbol to a contract address first using the Supported Token Symbols table or token search.

Query by USDT contract address:

sun --json pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Query by WTRX contract address:

sun --json pair info --token T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

---

12. Protocol Analytics

Fetch protocol-level metrics.

sun --json protocol info

sun --json protocol vol-history --start 2026-01-01 --end 2026-03-15

sun --json protocol users-history --start 2026-01-01 --end 2026-03-15

sun --json protocol tx-history --start 2026-01-01 --end 2026-03-15

sun --json protocol pools-history --start 2026-01-01 --end 2026-03-15

sun --json protocol liq-history --start 2026-01-01 --end 2026-03-15

---

13. Farm

Inspect SUN.IO farms.

sun --json farm list

Farm transactions for a specific owner:

sun --json farm tx --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --type stake

User farm positions:

sun --json farm positions --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW

---

14. Transaction Scan

Scan DEX transaction activity.

IMPORTANT: --type must be exactly one of: swap, add, withdraw. Invalid types return empty results instead of an error.

sun --json tx scan --type swap --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --start 2026-01-01 --end 2026-03-15

sun --json tx scan --type add --start 2026-01-01 --end 2026-03-15

sun --json tx scan --type withdraw --start 2026-01-01 --end 2026-03-15

---

15. Generic Contract Calls

Read or send arbitrary TRON contract calls when higher-level commands are insufficient.

Read a contract (no wallet needed):

sun --json contract read TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t name

sun --json contract read TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t balanceOf --args '["TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW"]'

Send a contract call (requires wallet, use --dry-run to simulate):

sun --json --yes --dry-run contract send TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t approve --args '["TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax","1000000"]' --value 0

---

Recommended Workflow for AI Agents

Pattern 1: Quick Swap (Three-Step with Validation)

Best for: User-facing swap operations.

Step 1 — Validate inputs (agent-side, no CLI call):

• Confirm tokenIn ≠ tokenOut (same-token swaps like TRX→TRX are not rejected by CLI)
• Confirm --network is valid (mainnet, nile, or shasta)

Step 2 — Check balance and get quote:

sun --json wallet balances

sun --json swap:quote TRX USDT 100000000

Verify balance ≥ amountIn. Show the user: expected output amount, price impact, route.

Step 3 — Execute after user confirms:

sun --json --yes swap TRX USDT 100000000 --slippage 0.005

---

Pattern 2: Safe Execution (Dry-Run First)

Best for: Large amounts or cautious operations.

NOTE: --dry-run only previews the transaction structure. It does NOT check balances, validate fee tiers, or reject invalid parameters.

Check balance first:

sun --json wallet balances

Simulate (preview transaction structure):

sun --json --yes --dry-run swap TRX USDT 100000000

Execute after reviewing dry-run result and confirming balance:

sun --json --yes swap TRX USDT 100000000

---

Pattern 3: Liquidity Management (V3 Example)

Best for: Adding concentrated liquidity.

Step 1 — Validate parameters (agent-side):

• Confirm --fee is one of: 100, 500, 3000, 10000
• Confirm --tick-lower and --tick-upper are multiples of tick spacing (e.g. 60 for fee=3000)
• Confirm token0 ≠ token1

Step 2 — Check balances and pool info:

sun --json wallet balances

sun --json pool search "TRX USDT"

Verify balance is sufficient for both amount0 and amount1.

Step 3 — Dry-run mint (preview only, does not validate balances or parameters):

sun --json --yes --dry-run liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000

Step 4 — Execute after user confirms:

sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000

---

Pattern 4: Information Gathering

Best for: Answering user questions about tokens, pools, prices.

Query token price:

sun --json price TRX

Top APY pools:

sun --json pool top-apy --page-size 10

User positions:

sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW

Pair info (requires contract address, not symbol):

sun --json pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Limit output fields to reduce response size:

sun --json --fields address,network wallet address

---

Supported Token Symbols

sun-cli has built-in symbol resolution. Common symbols:

Symbol	Mainnet Address	Decimals
TRX	T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb	6
WTRX	TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR	6
USDT	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t	6
USDC	TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8	6
USDD	TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn	18
SUN	TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S	18
JST	TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9	18
BTT	TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4	18
WIN	TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7	6

Any TRC20 token can also be referenced by its contract address directly.

---

Security Rules

CRITICAL: Never Display Private Keys

FORBIDDEN: private keys, seed phrases, mnemonics, environment variable values containing secrets, agent wallet passwords.

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

To verify no secrets leak in output:

sun --json wallet address

The output must not contain private key material.

CRITICAL: Prevent Duplicate Transactions

• One user command = one transaction
• After a successful transaction, mark it as done
• Never retry a successful transaction

CRITICAL: Validate Inputs Before Execution

The CLI does not validate all inputs in --dry-run mode. The agent must:

• Verify tokenIn ≠ tokenOut before swap
• Verify --fee is one of: 100, 500, 3000, 10000 before V3 mint
• Verify tick values are aligned to tick spacing before V3 mint
• Verify --network is one of: mainnet, nile, shasta
• Check wallet balances to confirm sufficient funds before any write operation

CRITICAL: Use Quote + Balance Check for High-Value Operations

sun --json wallet balances

sun --json swap:quote TRX USDT 1000000000

Always check balance and get a quote before executing. --dry-run only shows transaction structure and does NOT validate balances or parameters.

CRITICAL: Always Preview Before Write Operations

The AI agent must never execute a write operation (swap, liquidity add/remove/mint, contract send) without first showing the user a preview. The correct sequence is:

1. Get a quote or dry-run to show what will happen
2. Display the preview to the user (amounts, route, price impact, fees)
3. Ask for explicit confirmation from the user
4. Only then execute with --yes

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

Correct pattern:

sun --json swap:quote TRX USDT 100000000

Show results to user. After user confirms:

sun --json --yes swap TRX USDT 100000000

For high-value operations (large amounts): Always use --dry-run first in addition to the quote:

sun --json --yes --dry-run swap TRX USDT 1000000000

Then execute only after user reviews both the quote and the dry-run result.

---

User Communication Protocol

When executing trades or liquidity operations, communicate clearly:

Before execution:

Getting quote for 100 TRX → USDT...

Quote received:
  100 TRX → 15.234 USDT
  Price Impact: 0.12%
  Route: TRX → WTRX → USDT

Proceed with swap?

After success:

Swap completed!
  Transaction: abc123def456...
  Explorer: https://tronscan.org/#/transaction/abc123def456...
  Swapped: 100 TRX → 15.234 USDT

---

Known Limitations

These are CLI-level behaviors that the AI agent must work around:

Issue	Affected Commands	Behavior	Agent Workaround
--dry-run doesn't check balances	swap, liquidity v2:add, all V3/V4 ops	Returns preview even if balance is insufficient	Check wallet balances before executing
--dry-run doesn't validate V3 fee tiers	liquidity v3:mint	Accepts invalid fees like 9999	Only pass 100, 500, 3000, or 10000
--dry-run doesn't validate tick alignment	liquidity v3:mint	Accepts misaligned ticks	Ensure ticks are multiples of tick spacing
Same-token swap not rejected	swap	Accepts TRX→TRX in dry-run	Verify tokenIn ≠ tokenOut before calling
Invalid --network silently falls back	All commands	Unknown network names use mainnet	Only pass mainnet, nile, or shasta
Invalid --type returns empty results	tx scan	Unknown types return empty list, no error	Only pass swap, add, or withdraw
pair info --token needs address	pair info	Symbols cause API error or bad results	Use contract addresses, not symbols
--tokens filter needs addresses	wallet balances	Symbols like TRX,USDT cause Invalid contract address provided	Resolve symbols to addresses before calling
BigInt serialization in JSON output	contract read	Functions returning large integers (e.g. totalSupply) may crash with Do not know how to serialize a BigInt	Wrap result with .toString() client-side, or avoid --json for these calls
V3 invalid --token-id error misleading	v3:increase, v3:decrease, v3:collect	Non-existent token-id may report "amount required" instead of "position not found"	Verify the token-id exists via position list before operating
AGENT_WALLET_PASSWORD needs wallet store	wallet address	Fails if ~/.agent-wallet directory is not initialized	Use TRON_PRIVATE_KEY or TRON_MNEMONIC instead, or initialize wallet store first
Testnet transactions need bandwidth/energy	All write commands on nile/shasta	Real execution may fail with resource errors even if dry-run succeeds	Ensure test wallet has sufficient TRX staked for bandwidth and energy

---

Troubleshooting

"sun: command not found"

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

"Wallet not configured" on real writes

Set one of: TRON_PRIVATE_KEY, TRON_MNEMONIC, or AGENT_WALLET_PASSWORD. --dry-run should return a preview without wallet credentials on @sun-protocol/sun-cli >= 1.2.2.

NOTE on AGENT_WALLET_PASSWORD: This mode requires an initialized wallet store at ~/.agent-wallet. If the directory does not exist, the CLI will fail with Secrets directory not found. Use TRON_PRIVATE_KEY or TRON_MNEMONIC for simpler setup. Only set one wallet source at a time.

"Network error" or "Timeout"

• Check internet connectivity
• For mainnet, set TRONGRID_API_KEY
• Retry (network may be congested)

Transaction fails

• Ensure sufficient TRX for gas (100+ TRX recommended)
• Increase slippage: --slippage 0.01
• Verify token balance with sun --json wallet balances

Testnet transaction fails with bandwidth/energy error

• Nile and Shasta testnets require staked TRX for bandwidth and energy
• Dry-run may succeed but real execution fails if the wallet lacks resources
• Fund the test wallet with testnet TRX and stake for resources before testing
• Use --dry-run to verify transaction structure even when resources are insufficient

---

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