npx skills add https://github.com/bofai/skills --skill 'SunSwap DEX Trading'此技能使 AI 代理能够通过 sun-cli 与 TRON 区块链上的 SunSwap DEX 进行交互——这是一个用于报价兑换、执行交易、管理流动性（V2/V3/V4）、查询池、价格、头寸等的统一 CLI。
安装 sun-cli（全局安装）：
npm install -g @bankofai/sun-cli
配置钱包（仅写入操作需要）：
export TRON_PRIVATE_KEY="your_private_key_here"
替代钱包来源：TRON_MNEMONIC 或 AGENT_WALLET_PASSWORD。
可选环境变量：
export TRON_NETWORK=mainnet
export TRONGRID_API_KEY=your_key
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
只读命令（价格、报价、池列表等）无需钱包凭据即可工作。
从 AI 代理调用 sun 时，始终使用这些标志：
| 标志 | 用途 |
|---|---|
--json | 输出机器可读的 JSON 到标准输出 |
--yes | 跳过交互式确认提示 |
--dry-run | 模拟写入操作而不发送交易 |
--fields | 将输出限制为特定的逗号分隔字段 |
--network | 覆盖网络：mainnet、nile、shasta |
标准代理调用模式：
sun --json price TRX
写入操作添加 --yes 以跳过提示：
sun --json --yes swap TRX USDT 100000000
警告：
--network仅接受mainnet、nile或shasta。 无效的网络名称会静默回退到主网而不报错。AI 代理必须在传递网络值之前验证它。
警告：
--dry-run仅构建交易预览。 它不检查余额、验证费用层级、验证刻度对齐或拒绝同币种兑换。代理必须在执行前执行这些验证。请参阅下面的代理预验证清单。
在执行任何写入操作（swap、liquidity、contract send）之前，AI 代理必须执行以下检查。CLI 的 --dry-run 不验证这些——它只构建交易预览。
检查余额是否充足：
sun --json wallet balances
将代币余额与 amountIn 进行比较。如果不足则中止。
验证 tokenIn ≠ tokenOut： 同币种兑换（例如 TRX → TRX）不会被 --dry-run 拒绝。代理必须在执行前检查两个代币是不同的。
验证滑点是否合理： 推荐范围：0.001 (0.1%) 到 0.05 (5%)。如果超出此范围，请警告用户。
仅使用有效的费用层级： 100、500、3000 或 10000。无效的费用值（例如 9999）不会被 --dry-run 拒绝。
确保刻度与刻度间距对齐：
| 费用值 | 刻度间距 | 有效刻度示例 |
|---|---|---|
| 100 | 1 | 任意整数 |
| 500 | 10 | -10, 0, 10, 20 |
| 3000 | 60 | -120, -60, 0, 60 |
| 10000 | 200 | -400, -200, 0, 200 |
--tick-lower 和 --tick-upper 都必须是刻度间距的精确倍数。未对齐的刻度不会被 --dry-run 拒绝，但会在链上失败。
验证 token-id 存在： 首先查询用户的头寸：
sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --protocol V3
确认目标 --token-id 出现在结果中。传递不存在的 token-id 可能会产生误导性错误（例如“需要金额”而不是“未找到头寸”）。
--network 是以下之一：mainnet、nile、shasta。无效值会静默回退到主网。--type 对于 tx scan 是以下之一：swap、add、withdraw。无效值返回空结果而不是错误。检查钱包地址和代币余额。
sun --json wallet address
sun --json wallet balances
检查特定所有者地址的余额：
sun --json wallet balances --owner TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf
按特定代币过滤（仅限合约地址，不支持像 TRX/USDT 这样的符号）：
sun --json wallet balances --tokens TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t,TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR
警告：
--tokens仅接受合约地址。传递符号（例如TRX,USDT）将返回Invalid contract address provided。请先使用支持的代币符号表中的地址将符号解析为地址。
从 SUN.IO 获取代币价格。
sun --json price TRX
sun --json price USDT
按合约地址查询：
sun --json price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
获取价格报价而不执行。无需钱包。
参数： tokenIn 和 tokenOut 接受代币符号（TRX, USDT）或 TRC20 地址。amountIn 以 sun 为单位（最小单位，例如 1000000 = 1 TRX）。
sun --json swap:quote TRX USDT 100000000
包含所有路由详情的报价：
sun --json swap:quote TRX USDT 100000000 --all
在特定网络上的报价：
sun --json swap:quote TRX USDT 100000000 --network nile
反向兑换：
sun --json swap:quote USDT TRX 1000000
通过 SunSwap 通用路由器执行代币兑换。
参数： tokenIn 和 tokenOut 接受符号或地址。amountIn 以 sun 为单位。--slippage 是小数（默认值：0.005 = 0.5%）。
sun --json --yes swap TRX USDT 100000000
使用自定义滑点（1%）进行兑换：
sun --json --yes swap TRX USDT 100000000 --slippage 0.01
模拟运行（模拟而不发送）：
sun --json --yes --dry-run swap TRX USDT 100000000
使用合约地址代替符号：
sun --json --yes swap T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 100000000
在 nile 测试网上兑换：
sun --json --yes swap TRX USDT 1000000 --network nile
在 SunSwap V2 AMM 池上添加或移除流动性。
添加参数： --token-a 和 --token-b 接受符号或地址。--amount-a 和 --amount-b 以 sun 为单位。可选：--min-a、--min-b、--to、--deadline。
移除参数： --token-a、--token-b、--liquidity（原始 LP 数量）。可选：--min-a、--min-b、--to、--deadline。
单边（自动计算另一边）：
sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000
双边：
sun --json --yes liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000
模拟运行：
sun --json --yes --dry-run liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000
包含最小金额和接收者：
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
模拟运行：
sun --json --yes --dry-run liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000
管理 SunSwap V3 上的集中流动性头寸。
费用层级（仅以下值有效）：
| 费用率 | 费用值 | 刻度间距 | 全范围刻度 |
|---|---|---|---|
| 0.01% | 100 | 1 | -887272 / 887272 |
| 0.05% | 500 | 10 | -887270 / 887270 |
| 0.3% | 3000 | 60 | -887220 / 887220 |
| 1% | 10000 | 200 | -887200 / 887200 |
重要：
--fee必须恰好是以下之一：100、500、3000、10000。其他值不会被--dry-run拒绝，但会在链上失败。
--tick-lower和--tick-upper必须是刻度间距的精确倍数。未对齐的刻度不会被--dry-run拒绝，但会在链上失败。
铸造参数： --token0、--token1（符号或地址）、--fee、--tick-lower、--tick-upper、--amount0、--amount1。可选：--recipient、--deadline。
全范围使用默认值：
sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000
指定费用和刻度范围（fee=3000，刻度间距=60）：
sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000
模拟运行：
sun --json --yes --dry-run liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000
指定费用层级（fee=500，刻度间距=10）：
sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 500 --tick-lower -887270 --tick-upper 887270 --amount0 1000000
指定接收者：
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
管理 SunSwap V4 池上的流动性（支持钩子）。
铸造参数： --token0、--token1、--fee、--tick-lower、--tick-upper、--amount0、--amount1。可选：--slippage、--recipient、--create-pool。
sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000
如果池不存在则创建池：
sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool
包含滑点：
sun --json --yes liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --slippage 0.01
模拟运行：
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
搜索和检查流动性池。
按代币地址列出池：
sun --json pool list --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
按关键词搜索：
sun --json pool search "TRX USDT"
最高 APY 池：
sun --json pool top-apy --page-size 10
池交易量历史（需要池地址）：
sun --json pool vol-history TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx --start 2026-01-01 --end 2026-03-15
池流动性历史：
sun --json pool liq-history TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx --start 2026-01-01 --end 2026-03-15
池钩子（V4）：
sun --json pool hooks
搜索和列出代币元数据。
sun --json token list
按协议过滤：
sun --json token list --protocol V3
按关键词搜索：
sun --json token search USDT
查询用户流动性头寸。
列出所有者的所有头寸：
sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW
按协议过滤：
sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --protocol V3
池刻度信息：
sun --json position tick TSUUVjysXV8YqHytSNjfkNXnnB49QDvZpx
解析交易对信息。
警告：
pair info --token仅接受合约地址。传递符号（例如USDT）将导致 API 错误或返回意外结果。请始终先使用支持的代币符号表或token search将符号解析为合约地址。
按 USDT 合约地址查询：
sun --json pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
按 WTRX 合约地址查询：
sun --json pair info --token T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb
获取协议级别的指标。
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
检查 SUN.IO 农场。
sun --json farm list
特定所有者的农场交易：
sun --json farm tx --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW --type stake
用户农场头寸：
sun --json farm positions --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW
扫描 DEX 交易活动。
重要：
--type必须恰好是以下之一：swap、add、withdraw。无效类型返回空结果而不是错误。
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
当高级命令不足时，读取或发送任意的 TRON 合约调用。
读取合约（无需钱包）：
sun --json contract read TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t name
sun --json contract read TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t balanceOf --args '["TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW"]'
发送合约调用（需要钱包，使用 --dry-run 模拟）：
sun --json --yes --dry-run contract send TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t approve --args '["TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax","1000000"]' --value 0
最适合： 面向用户的兑换操作。
步骤 1 — 验证输入（代理端，无 CLI 调用）：
--network 有效（mainnet、nile 或 shasta）步骤 2 — 检查余额并获取报价：
sun --json wallet balances
sun --json swap:quote TRX USDT 100000000
验证余额 ≥ amountIn。向用户显示：预期输出金额、价格影响、路由。
步骤 3 — 用户确认后执行：
sun --json --yes swap TRX USDT 100000000 --slippage 0.005
最适合： 大额或谨慎的操作。
注意：
--dry-run仅预览交易结构。它不检查余额、验证费用层级或拒绝无效参数。
首先检查余额：
sun --json wallet balances
模拟（预览交易结构）：
sun --json --yes --dry-run swap TRX USDT 100000000
查看模拟运行结果并确认余额后执行：
sun --json --yes swap TRX USDT 100000000
最适合： 添加集中流动性。
步骤 1 — 验证参数（代理端）：
--fee 是以下之一：100、500、3000、10000--tick-lower 和 --tick-upper 是刻度间距的倍数（例如 fee=3000 时为 60）步骤 2 — 检查余额和池信息：
sun --json wallet balances
sun --json pool search "TRX USDT"
验证余额对于 amount0 和 amount1 都充足。
步骤 3 — 模拟铸造（仅预览，不验证余额或参数）：
sun --json --yes --dry-run liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000
步骤 4 — 用户确认后执行：
sun --json --yes liquidity v3:mint --token0 TRX --token1 USDT --fee 3000 --tick-lower -887220 --tick-upper 887220 --amount0 1000000
最适合： 回答用户关于代币、池、价格的问题。
查询代币价格：
sun --json price TRX
最高 APY 池：
sun --json pool top-apy --page-size 10
用户头寸：
sun --json position list --owner TMgYX7m37cyyTSgVbtCoDUAQcFZ9RoYxJW
交易对信息（需要合约地址，而非符号）：
sun --json pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
限制输出字段以减少响应大小：
sun --json --fields address,network wallet address
sun-cli 具有内置的符号解析功能。常见符号：
| 符号 | 主网地址 | 小数位数 |
|---|---|---|
| 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 |
任何 TRC20 代币也可以直接通过其合约地址引用。
禁止： 私钥、助记词、包含秘密的环境变量值、代理钱包密码。
允许： 公共钱包地址、交易哈希、代币余额和价格。
验证输出中没有泄露秘密：
sun --json wallet address
输出不得包含私钥材料。
CLI 在 --dry-run 模式下不验证所有输入。代理必须：
--fee 是以下之一：100, 500, 3000, 10000--network 是以下之一：mainnet, nile, shastawallet balances 以确认资金充足sun --json wallet balances
sun --json swap:quote TRX USDT 1000000000
执行前始终检查余额并获取报价。--dry-run 仅显示交易结构，不验证余额或参数。
AI 代理绝不可在没有先向用户显示预览的情况下执行写入操作（swap、liquidity add/remove/mint、contract send）。正确的顺序是：
--yes 执行警告： 不要在第一次调用时传递
--yes。仅在用户查看预览并确认后使用--yes。跳过预览违反了安全协议。
正确模式：
sun --json swap:quote TRX USDT 100000000
向用户显示结果。用户确认后：
sun --json --yes swap TRX USDT 100000000
对于高价值操作（大额）： 除了报价外，始终先使用 --dry-run：
sun --json --yes --dry-run swap TRX USDT 1000000000
然后仅在用户查看报价和模拟运行结果后执行。
执行交易或流动性操作时，清晰沟通：
执行前：
正在获取 100 TRX → USDT 的报价...
收到报价：
100 TRX → 15.234 USDT
价格影响：0.12%
路由：TRX → WTRX → USDT
是否继续兑换？
成功后：
兑换完成！
交易：abc123def456...
浏览器：https://tronscan.org/#/transaction/abc123def456...
兑换：100 TRX → 15.234 USDT
这些是 CLI 级别的行为，AI 代理必须解决：
| 问题 | 受影响的命令 | 行为 | 代理解决方案 |
|---|---|---|---|
--dry-run 不检查余额 | swap、liquidity v2:add、所有 V3/V4 操作 | 即使余额不足也返回预览 | 执行前检查 wallet balances |
--dry-run 不验证 V3 费用层级 | liquidity v3:mint | 接受无效费用如 9999 | 仅传递 100、500、3000 或 10000 |
--dry-run 不验证刻度对齐 | liquidity v3:mint | 接受未对齐的刻度 | 确保刻度是刻度间距的倍数 |
| 同币种兑换不被拒绝 | swap | 在模拟运行中接受 TRX→TRX | 调用前验证 tokenIn ≠ tokenOut |
无效 --network 静默回退 | 所有命令 | 未知网络名称使用主网 | 仅传递 mainnet、nile 或 shasta |
无效 --type 返回空结果 | tx scan | 未知类型返回空列表，无错误 | 仅传递 swap、add 或 withdraw |
pair info --token 需要地址 | pair info | 符号导致 API 错误或错误结果 | 使用合约地址，而非符号 |
--tokens 过滤器需要地址 | wallet balances | 符号如 TRX,USDT 导致 Invalid contract address provided | 调用前将符号解析为地址 |
| JSON 输出中的 BigInt 序列化 | contract read | 返回大整数（例如 totalSupply）的函数可能因 Do not know how to serialize a BigInt 而崩溃 | 在客户端用 .toString() 包装结果，或避免对这些调用使用 --json |
V3 无效 --token-id 错误误导 | v3:increase、v3:decrease、v3:collect | 不存在的 token-id 可能报告“需要金额”而不是“未找到头寸” | 通过 position list 验证 token-id 存在后再操作 |
AGENT_WALLET_PASSWORD 需要钱包存储 | wallet address | 如果 ~/.agent-wallet 目录未初始化则失败 | 改用 TRON_PRIVATE_KEY 或 TRON_MNEMONIC，或先初始化钱包存储 |
| 测试网交易需要带宽/能量 | nile/shasta 上的所有写入命令 | 即使模拟运行成功，实际执行也可能因资源错误而失败 | 确保测试钱包有足够的 TRX 质押用于带宽和能量 |
npm install -g @bankofai/sun-cli
设置以下之一：TRON_PRIVATE_KEY、TRON_MNEMONIC 或 AGENT_WALLET_PASSWORD。
关于 AGENT_WALLET_PASSWORD 的注意： 此模式需要在
~/.agent-wallet处初始化钱包存储。如果目录不存在，CLI 将失败并显示Secrets directory not found。使用TRON_PRIVATE_KEY或TRON_MNEMONIC进行更简单的设置。一次只设置一个钱包来源。
TRONGRID_API_KEY--slippage 0.01sun --json wallet balances 验证代币余额--dry-run 验证交易结构版本 : 3.2.0 (基于 sun-cli) 最后更新 : 2026-03-20 维护者 : Bank of AI Team
每周安装次数
–
代码仓库
GitHub 星标数
2
首次出现
–
安全审计
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.
Install sun-cli (globally):
npm install -g @bankofai/sun-cli
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.) 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, |
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.
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").
--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, , , or |
npm install -g @bankofai/sun-cli
Set one of: TRON_PRIVATE_KEY, TRON_MNEMONIC, or AGENT_WALLET_PASSWORD.
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.2.0 (sun-cli based) Last Updated : 2026-03-20 Maintainer : Bank of AI Team
Weekly Installs
–
Repository
GitHub Stars
2
First Seen
–
Security Audits
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
27,600 周安装
shasta500300010000--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 |