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:** Configure a supported sun-cli wallet source > before swaps, liquidity changes, or `contract send`, then verify the public address with > `sun wallet address`. Read-only queries and `--dry-run` previews do not need a wallet. > The retired wallet and onboarding Skills are not prerequisites; wallet-cli accounts are > not automatically available to sun-cli. Never request or display secret values in chat. 1. **Verify sun-cli**: ```bash sun --version ``` The required version is exactly `1.2.2`. If it is missing or another version is installed, obtain approval before changing the global package: ```bash npm install -g @sun-protocol/sun-cli@1.2.2 ``` 2. **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`. 3. **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: ```bash sun --json price TRX ``` Write operations add `--yes` to skip prompts: ```bash 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. 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: ```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. ```bash sun --json wallet address ``` ```bash sun --json wallet balances ``` Check balances for a specific owner address: ```bash sun --json wallet balances --owner TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf ``` Filter by specific tokens (contract addresses only, symbols like TRX/USDT are NOT supported): ```bash 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. ```bash sun --json price TRX ``` ```bash sun --json price USDT ``` Query by contract address: ```bash 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). ```bash sun --json swap:quote TRX USDT 100000000 ``` Quote with all route details: ```bash sun --json swap:quote TRX USDT 100000000 --all ``` Quote on a specific network: ```bash sun --json swap:quote TRX USDT 100000000 --network nile ``` Reverse direction: ```bash 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%). ```bash sun --json --yes swap TRX USDT 100000000 ``` Swap with custom slippage (1%): ```bash sun --json --yes swap TRX USDT 100000000 --slippage 0.01 ``` Dry-run (simulate without sending): ```bash sun --json --yes --dry-run swap TRX USDT 100000000 ``` Use contract addresses instead of symbols: ```bash sun --json --yes swap T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 100000000 ``` Swap on nile testnet: ```bash 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): ```bash sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 ``` Both sides: ```bash sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 ``` Dry-run: ```bash sun --json --yes --dry-run liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 ``` With minimum amounts and recipient: ```bash 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 ```bash sun --json --yes liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 ``` Dry-run: ```bash 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: ```bash sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 ``` With specific fee and tick range (fee=3000, tick spacing=60): ```bash sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000 ``` Dry-run: ```bash sun --json --yes --dry-run liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 ``` With specific fee tier (fee=500, tick spacing=10): ```bash sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 500 --tick-lower -887270 --tick-upper 887270 --amount0 1000000 ``` With recipient: ```bash sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -60 --tick-upper 60 --amount0 1000000 --recipient TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW ``` #### Increase Position ```bash sun --json --yes liquidity v3:increase --token-id 123 --amount0 500000 ``` #### Decrease Position ```bash sun --json --yes liquidity v3:decrease --token-id 123 --liquidity 1000 ``` #### Collect Fees ```bash sun --json --yes liquidity v3:collect --token-id 123 ``` --- ### 7. V4 Liquidity Manage liquidity on SunSwap V4 pools (with hooks support).