sunswap-dex-trading

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): ```bash npm install -g @sun-protocol/sun-cli@^1.2.2 ```

1. Configure wallet (required for write operations only): ```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 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](#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: ```bash sun --json wallet balances ``` Compare the token balance against the amountIn. Abort if insufficient.

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

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

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

1. 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: ```bash 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](#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](#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