Menu
Execute token swaps, manage liquidity, and query market data on SunSwap DEX via the sun-cli.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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"] |
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.
Wallet required for real writes only: Run
agent-wallet listbefore executing swaps, liquidity changes, orcontract send. Read-only queries and--dry-runpreviews do not need a wallet. If no wallets exist, invokebankofai-guide(Section C — Wallet Guard) before proceeding.
Install sun-cli (globally):
npm install -g @sun-protocol/sun-cli@^1.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.
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.
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:
--networkonly acceptsmainnet,nile, orshasta. Invalid network names silently fall back to mainnet without error. The AI agent must validate the network value before passing it.
WARNING:
--dry-runonly 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.
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.
Check balance is sufficient:
sun --json wallet balances
Compare the token balance against the amountIn. Abort if insufficient.
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.
Validate slippage is reasonable: Recommended range: 0.001 (0.1%) to 0.05 (5%). Warn the user if outside this range.
Use only valid fee tiers: 100, 500, 3000, or 10000.
Invalid fee values (e.g. 9999) are not rejected by --dry-run.
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.
Check balance is sufficient for both token0 and token1 amounts.
sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --protocol V3
--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").--network is one of: mainnet, nile, shasta. Invalid values silently fall back to mainnet.--type for tx scan is one of: swap, add, withdraw. Invalid values return empty results instead of errors.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:
--tokensonly accepts contract addresses. Passing symbols (e.g.TRX,USDT) will returnInvalid contract address provided. Use the address table in Supported Token Symbols to resolve symbols to addresses first.
Fetch token prices from SUN.IO.
sun --json price TRX
sun --json price USDT
Query by contract address:
sun --json price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
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
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
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.
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
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
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:
--feemust be exactly one of:100,500,3000,10000. Other values are NOT rejected by--dry-runbut will fail on-chain.
--tick-lowerand--tick-uppermust be exact multiples of the tick spacing. Misaligned ticks are NOT rejected by--dry-runbut will fail on-chain.
Parameters for mint: --token0, --token1 (symbol or address), --fee, --tick-lower, --tick-upper, --amount0, --amount1. Optional: --recipient, --deadline.
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
sun --json --yes liquidity v3:increase --token-id 123 --amount0 500000
sun --json --yes liquidity v3:decrease --token-id 123 --liquidity 1000
sun --json --yes liquidity v3:collect --token-id 123
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.
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
sun --json --yes liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000
sun --json --yes liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT
sun --json --yes liquidity v4:collect --token-id 123
sun --json liquidity v4:info --pm TLSWrv7eC1AZCXkRjpqMZUmvgd99cj7pPF --token-id 123
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
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
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
Resolve trading pair information.
WARNING:
pair info --tokenonly 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 ortoken search.
Query by USDT contract address:
sun --json pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
Query by WTRX contract address:
sun --json pair info --token T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb
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
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
Scan DEX transaction activity.
IMPORTANT:
--typemust 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
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
Best for: User-facing swap operations.
Step 1 — Validate inputs (agent-side, no CLI call):
--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
Best for: Large amounts or cautious operations.
NOTE:
--dry-runonly 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
Best for: Adding concentrated liquidity.
Step 1 — Validate parameters (agent-side):
--fee is one of: 100, 500, 3000, 10000--tick-lower and --tick-upper are multiples of tick spacing (e.g. 60 for fee=3000)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
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
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.
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.
The CLI does not validate all inputs in --dry-run mode. The agent must:
--fee is one of: 100, 500, 3000, 10000 before V3 mint--network is one of: mainnet, nile, shastawallet balances to confirm sufficient funds before any write operationsun --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.
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:
--yesWARNING: Do not pass
--yeson the first call. Use--yesonly 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.
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
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 |
npm install -g @sun-protocol/sun-cli@^1.2.2
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 withSecrets directory not found. UseTRON_PRIVATE_KEYorTRON_MNEMONICfor simpler setup. Only set one wallet source at a time.
TRONGRID_API_KEY--slippage 0.01sun --json wallet balances--dry-run to verify transaction structure even when resources are insufficientVersion: 3.3.0 (sun-protocol sun-cli scope) Last Updated: 2026-07-09 Maintainer: Bank of AI Team
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.
Pay for x402-enabled Agent endpoints using ERC20 tokens (USDT/USDC) on EVM or TRC20 tokens (USDT/USDD) on TRON.
Use when the user asks to generate an X/Twitter daily digest or says phrases such as "生成X日报", "生成 x 日报", "X日报", "推特日报", "Twitter digest", or wants an agent to analyze their own X/Twitter mentions, home timeline, reply opportunities, and daily social-media summaries. This skill is API-only.
Use when the user wants to install or authorize xurl for X/Twitter, generate "生成X日报", "X日报", "推特日报", or "Twitter digest" from the local xurl CLI, or optionally register/troubleshoot the hosted X MCP bridge.
BANK OF AI account query and recharge skill. Use for requests like 'recharge 1 usdt', '给 BANK OF AI 充值 1 USDT', or to query BANK OF AI balance/orders. Recharge uses the remote MCP endpoint https://recharge.bankofai.io/mcp with the single `recharge` tool.
Use when the user asks to create a wallet, check wallet addresses, sign transactions or messages, switch active wallets, or perform any blockchain signing operation using the agent-wallet CLI. Supports EVM and TRON networks.