From 88c765ccdb6133bcb4624f57893f139676858c67 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Thu, 2 Apr 2026 17:35:00 +0800 Subject: [PATCH 01/33] add sun-cli --- .../MCP/SUNCli/CommandGuide.md | 377 ++++++++++++++++++ docs/McpServer-Skills/MCP/SUNCli/FAQ.md | 130 ++++++ docs/McpServer-Skills/MCP/SUNCli/Intro.md | 127 ++++++ .../McpServer-Skills/MCP/SUNCli/QuickStart.md | 147 +++++++ .../MCP/SUNCli/CommandGuide.md | 377 ++++++++++++++++++ .../McpServer-Skills/MCP/SUNCli/FAQ.md | 130 ++++++ .../McpServer-Skills/MCP/SUNCli/Intro.md | 127 ++++++ .../McpServer-Skills/MCP/SUNCli/QuickStart.md | 147 +++++++ .../current/sidebars.js | 11 + sidebars.js | 11 + 10 files changed, 1584 insertions(+) create mode 100644 docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md create mode 100644 docs/McpServer-Skills/MCP/SUNCli/FAQ.md create mode 100644 docs/McpServer-Skills/MCP/SUNCli/Intro.md create mode 100644 docs/McpServer-Skills/MCP/SUNCli/QuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/QuickStart.md diff --git a/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md new file mode 100644 index 0000000..97654f4 --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md @@ -0,0 +1,377 @@ +# Command Guide + +This page is the complete reference for all SUN CLI commands. Commands are organized by category: wallet management, market data, trading, liquidity, protocol analytics, and contract interaction. + +--- + +## Global Flags + +All commands inherit these root-level flags. **Root flags must be placed before the subcommand.** + +| Flag | Description | +| :--- | :--- | +| `--output ` | Output format: `table`, `json`, `tsv` | +| `--json` | Shortcut for JSON output | +| `--fields ` | Comma-separated output field filter | +| `--network ` | Override `TRON_NETWORK` (e.g., `mainnet`, `nile`, `shasta`) | +| `-k, --private-key ` | Provide a private key for this invocation only | +| `-m, --mnemonic ` | Provide a mnemonic for this invocation only | +| `-i, --mnemonic-account-index ` | Provide a mnemonic account index for this invocation only | +| `-p, --agent-wallet-password ` | Override `AGENT_WALLET_PASSWORD` for this invocation | +| `-d, --agent-wallet-dir ` | Override `AGENT_WALLET_DIR` for this invocation | +| `-y, --yes` | Skip confirmation prompts | +| `--dry-run` | Print intent without sending the write action | + +**Examples:** + +```bash +sun --json price TRX +``` + +```bash +sun --output tsv pool top-apy --page-size 10 +``` + +```bash +sun --fields address,network wallet address +``` + +```bash +sun -k your_private_key --network nile --yes swap TRX USDT 1000000 +``` + +```bash +sun --dry-run contract send TContract transfer --args '["TRecipient","1000000"]' +``` + +--- + +## Wallet & Portfolio + +Inspect the active wallet and on-chain balances. + +### `wallet address` + +Display the configured wallet address and current network. + +```bash +sun wallet address +``` + +### `wallet balances` + +Query token balances for the active wallet or any address. + +```bash +sun wallet balances +``` + +```bash +sun wallet balances --owner TYourAddress --tokens TRX,TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `position list` + +View SunSwap liquidity positions for an address. + +```bash +sun position list --owner TYourAddress +``` + +### `position tick` + +Query tick data for a specific pool. + +```bash +sun position tick +``` + +### `farm positions` + +View yield farm positions. + +```bash +sun farm positions --owner TYourAddress +``` + +--- + +## Price & Discovery + +### `price` + +Query real-time token prices on SunSwap. + +```bash +sun price TRX +``` + +```bash +sun price USDT +``` + +```bash +sun price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `token list` + +List tokens by protocol version. + +```bash +sun token list --protocol V3 +``` + +### `token search` + +Search for tokens by name or symbol. + +```bash +sun token search USDT +``` + +### `pool list` + +List pools filtered by token. + +```bash +sun pool list --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `pool search` + +Search for pools by token pair. + +```bash +sun pool search "TRX USDT" +``` + +### `pool top-apy` + +List pools ranked by APY. + +```bash +sun pool top-apy --page-size 10 +``` + +### `pool hooks` + +List pools with hooks enabled. + +```bash +sun pool hooks +``` + +### `pair info` + +Get pair-level information for a token. + +```bash +sun pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `farm list` + +List available yield farms. + +```bash +sun farm list +``` + +--- + +## Swap + +### `swap` + +Execute a token swap via the optimal route. Requires a configured wallet. + +```bash +sun swap TRX USDT 1000000 --slippage 0.005 +``` + +```bash +sun -k your_private_key --network nile --yes swap TRX USDT 1000000 +``` + +Successful responses include `txid`, route details, and a `tronscanUrl` link. + +### `swap:quote` + +Get a read-only swap quote without executing. No wallet needed. + +```bash +sun swap:quote TRX USDT 1000000 +``` + +```bash +sun swap:quote TRX USDT 1000000 --all +``` + +### `swap:quote-raw` + +Low-level router quote with raw arguments. + +```bash +sun swap:quote-raw --router --args '[...]' +``` + +### `swap:exact-input` + +Low-level exact-input swap via a specific router. + +```bash +sun swap:exact-input --router --args '[...]' --value 1000000 +``` + +--- + +## Liquidity + +### V2 + +```bash +sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 +``` + +```bash +sun liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 +``` + +### V3 + +```bash +sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 +``` + +```bash +sun liquidity v3:increase --token-id 123 --amount0 500000 +``` + +```bash +sun liquidity v3:decrease --token-id 123 --liquidity 1000 +``` + +```bash +sun liquidity v3:collect --token-id 123 +``` + +### V4 + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 +``` + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool +``` + +```bash +sun liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000 +``` + +```bash +sun liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT +``` + +```bash +sun liquidity v4:collect --token-id 123 +``` + +```bash +sun liquidity v4:info --pm --token-id 123 +``` + +--- + +## Protocol & History + +### Protocol Analytics + +```bash +sun protocol info +``` + +```bash +sun protocol vol-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol users-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol tx-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol pools-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol liq-history --start 2026-01-01 --end 2026-03-01 +``` + +### Pool History + +```bash +sun pool vol-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun pool liq-history --start 2026-01-01 --end 2026-03-01 +``` + +### Transaction Scan + +```bash +sun tx scan --type swap --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --start 2026-01-01 +``` + +--- + +## Generic Contract + +Read from or write to arbitrary TRON smart contracts. + +### `contract read` + +```bash +sun contract read balanceOf --args '["TYourAddress"]' +``` + +### `contract send` + +```bash +sun contract send transfer --args '["TRecipient","1000000"]' --value 0 +``` + +`contract send` also returns a `tronscanUrl` link when a transaction is broadcast successfully. + +--- + +## Built-In Token Symbols + +Many commands accept token symbols in addition to full TRON addresses: + +| Symbol | Address | Decimals | +| :--- | :--- | :--- | +| `TRX` | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` | 6 | +| `WTRX` | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | +| `USDT` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | +| `USDCOLD` | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | +| `USDD` | `TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn` | 18 | +| `SUN` | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | +| `JST` | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | +| `BTT` | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | +| `WIN` | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | + +You can use either the symbol or the full address: + +```bash +sun swap TRX USDT 1000000 +``` + +```bash +sun swap T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 +``` diff --git a/docs/McpServer-Skills/MCP/SUNCli/FAQ.md b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md new file mode 100644 index 0000000..b49bf66 --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -0,0 +1,130 @@ +# FAQ + +Common questions and troubleshooting tips for SUN CLI. + +--- + +## Installation & Setup + +### What are the system requirements? + +- **Node.js** 20.0.0 or later +- **npm** (comes with Node.js) +- A terminal or shell environment (macOS, Linux, or Windows with WSL) + +### How do I update SUN CLI? + +```bash +npm update -g @bankofai/sun-cli +``` + +--- + +## Wallet & Configuration + +### I get "No wallet configured" — what should I do? + +Write operations (swap, liquidity, contract send) require a wallet. Set exactly one wallet source: + +- `AGENT_WALLET_PRIVATE_KEY` — direct private key +- `AGENT_WALLET_MNEMONIC` — mnemonic phrase +- `AGENT_WALLET_PASSWORD` — encrypted wallet via agent-wallet + +Or provide the equivalent root-level flag (`-k`, `-m`, `-p`) for a single invocation. See the [agent-wallet Quick Start](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) for full setup instructions. + +### Can I use SUN CLI without a wallet? + +Yes. All read-only commands work without any wallet configuration: price queries, swap quotes, pool data, protocol stats, token search, and more. + +### Is my private key safe? + +SUN CLI never uploads your private key to any remote service. All signing happens locally. However, be cautious with command-line flags (`-k`, `-m`) as they may appear in your shell history. Prefer environment variables or agent-wallet's encrypted storage. + +--- + +## Common Errors + +### `unknown command 'nile'` + +Root flags like `--network` must be placed **before** the subcommand: + +```bash +# Correct +sun --network nile swap TRX USDT 1000000 + +# Wrong — 'nile' is parsed as a command +sun swap TRX USDT 1000000 --network nile +``` + +When using npm scripts, pass arguments after `--`: + +```bash +npm run start -- --network nile swap TRX USDT 1000000 +``` + +### `Swap failed` + +Common causes: + +- Wallet not configured +- Unsupported token symbol or invalid address +- Insufficient balance +- RPC or router API failure +- Stale or invalid route parameters + +**Recommendation:** Run `swap:quote` first to verify the route, then retry with `--yes` only after the quote looks correct. + +### Transactions succeed but I see unexpected results + +- **Slippage**: In volatile markets, the actual output may differ from the quoted amount. Adjust slippage tolerance with `--slippage`. +- **Token decimals**: Amounts are specified in the token's smallest unit. For TRX (6 decimals), `1000000` = 1 TRX. +- **Network mismatch**: Make sure you're on the intended network. Check with `sun wallet address`. + +--- + +## AI Agent Integration + +### Can AI agents use SUN CLI? + +Yes. SUN CLI is designed for both human and AI-driven workflows. Key features for automation: + +- `--json` output for machine-readable responses +- `--yes` flag to skip confirmation prompts +- `--dry-run` to preview actions without executing +- `--fields` to filter output to specific fields +- Exit codes for error handling in scripts + +### What's the difference between SUN CLI and SUN MCP Server? + +SUN CLI is a command-line tool invoked directly. SUN MCP Server is an MCP-compatible server that AI clients (like Claude) connect to for natural language DeFi interaction. Both access the same SunSwap ecosystem. Choose CLI for scripts and automation, MCP Server for AI-assisted workflows. + +--- + +## Networks & Tokens + +### Which networks are supported? + +Mainnet, Nile testnet, and Shasta testnet. Default is mainnet. Use `--network nile` or `--network shasta` for testing. + +### How do I use a custom token not in the built-in list? + +Use the token's full TRON contract address instead of a symbol: + +```bash +sun price --address TYourTokenAddress +sun swap TYourTokenAddress TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 +``` + +### Can I set a custom RPC endpoint? + +Yes. Set the `TRON_RPC_URL` environment variable: + +```bash +export TRON_RPC_URL=https://your-tron-rpc.example +``` + +--- + +## Still Need Help? + +If your question isn't covered here, check the [Command Guide](./CommandGuide.md) for detailed usage, or file an issue on the [GitHub repository](https://github.com/nicholaskarlson/sun-cli). diff --git a/docs/McpServer-Skills/MCP/SUNCli/Intro.md b/docs/McpServer-Skills/MCP/SUNCli/Intro.md new file mode 100644 index 0000000..939bd6a --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNCli/Intro.md @@ -0,0 +1,127 @@ +# Introduction + +## What is SUN CLI? + +SUN CLI (`@bankofai/sun-cli`) is a command-line tool that brings the full power of [SUN.IO (SunSwap)](https://sun.io) to your terminal. Whether you're a human operator or an AI agent, SUN CLI lets you query DeFi data, execute token swaps, and manage liquidity positions on the TRON network through a single command-line interface. + +Think of it this way: SUN MCP Server lets AI assistants talk to SunSwap through natural language. SUN CLI lets you—or your scripts and automation pipelines—talk to SunSwap through structured commands. Same DeFi capabilities, different interface. + +For example, checking the price of TRX is as simple as: + +```bash +sun price TRX +``` + +And executing a swap: + +```bash +sun swap TRX USDT 1000000 --yes +``` + +No frontend, no browser, no manual contract interaction. + +--- + +## What can it do? + +SUN CLI covers the full range of SunSwap DEX interactions, from real-time market data to on-chain transactions. + +**Data Queries (read-only, no wallet needed):** + +| Capability | Description | Example Command | +| :--- | :--- | :--- | +| **Token Prices** | Real-time prices for any token on SunSwap | `sun price TRX` | +| **Swap Quotes** | Get optimal route and expected output before executing | `sun swap:quote TRX USDT 1000000` | +| **Pool Data** | Pool lists, APY rankings, volume and liquidity history | `sun pool top-apy --page-size 5` | +| **Position Query** | View liquidity positions for any address | `sun position list --owner TYourAddress` | +| **Protocol Stats** | SunSwap-wide volume, users, pools, and liquidity history | `sun protocol info` | +| **Farm Info** | Yield farm lists and user mining positions | `sun farm list` | +| **Token Discovery** | Search tokens, list by protocol version | `sun token search USDT` | + +**DeFi Operations (write, requires wallet):** + +| Capability | Description | Example Command | +| :--- | :--- | :--- | +| **Token Swap** | Execute optimal-route swaps via the Universal Router | `sun swap TRX USDT 1000000` | +| **V2 Liquidity** | Add/remove V2 pool liquidity | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000` | +| **V3 Liquidity** | Mint, increase, decrease concentrated positions, collect fees | `sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000` | +| **V4 Liquidity** | V4 concentrated liquidity with Permit2 authorization | `sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000` | +| **Contract Interaction** | Read or write to any TRON smart contract | `sun contract read
balanceOf --args '[...]'` | + +--- + +## SUN CLI vs SUN MCP Server + +Both tools connect you to the same SunSwap ecosystem, but serve different use cases: + +| Comparison | SUN CLI | SUN MCP Server | +| :--- | :--- | :--- | +| **Interface** | Terminal commands | AI natural language | +| **Best for** | Scripts, automation, developers | AI-assisted DeFi interaction | +| **Invocation** | Direct CLI commands with flags | AI client sends MCP tool calls | +| **Output formats** | Table, JSON, TSV | Structured MCP responses | +| **Write operations** | Supported (with wallet) | Supported (local deployment) | +| **No-prompt mode** | `--yes` flag for unattended execution | AI handles confirmation flow | + +:::tip When to choose SUN CLI? +Choose SUN CLI when you need programmatic access—shell scripts, cron jobs, CI/CD pipelines, or when you prefer explicit commands over natural language. Choose SUN MCP Server when you want an AI assistant to handle DeFi operations conversationally. +::: + +--- + +## Output Modes + +SUN CLI supports three output formats, making it friendly for both humans and machines: + +- **table** — default, human-friendly terminal tables +- **json** — compact, machine-readable JSON for scripts and AI agents +- **tsv** — tab-separated values for shell pipelines + +```bash +sun pool top-apy --page-size 5 +``` + +```bash +sun --json wallet address +``` + +```bash +sun --output tsv token list --protocol V3 +``` + +--- + +## Supported Networks + +SUN CLI supports the same three TRON networks (mainnet by default): + +| Network | Identifier | Purpose | Block Explorer | +| :--- | :--- | :--- | :--- | +| **Mainnet** | `mainnet` | Production, real assets | [tronscan.org](https://tronscan.org) | +| **Nile Testnet** | `nile` | Development and testing (recommended) | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta Testnet** | `shasta` | Development and testing | [shasta.tronscan.org](https://shasta.tronscan.org) | + +Specify the network with the `--network` flag. **We strongly recommend validating operations on the Nile testnet first**—mainnet operations involve real assets and cannot be undone. + +--- + +## Security Notes + +:::warning +DeFi operations involve on-chain assets and mistakes cannot be reversed. Keep these principles in mind: + +- **Never hardcode private keys**: Use environment variables or encrypted wallet management via [agent-wallet](https://github.com/BofAI/agent-wallet), not command-line flags in shared environments. +- **Test on testnet first**: Use `--network nile` before running any write operation on mainnet. +- **Minimum funds principle**: Only keep the funds needed for the current task in the CLI's configured wallet. +- **Use dry-run mode**: Run `--dry-run` before high-value writes to preview intent without broadcasting. +- **Verify token addresses**: When not using built-in symbols, double-check contract addresses. +- **Quotes are not guarantees**: In volatile markets, actual execution results may differ from quotes. +::: + +--- + +## Next Steps + +- Want to get up and running fast? → [Quick Start](./QuickStart.md) +- Need the full command reference? → [Command Guide](./CommandGuide.md) +- Have questions or running into issues? → [FAQ](./FAQ.md) diff --git a/docs/McpServer-Skills/MCP/SUNCli/QuickStart.md b/docs/McpServer-Skills/MCP/SUNCli/QuickStart.md new file mode 100644 index 0000000..91234cd --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNCli/QuickStart.md @@ -0,0 +1,147 @@ +# Quick Start + +The goal of this page is simple: **install SUN CLI and make your first DeFi query in under 1 minute.** + +No wallet needed for read-only commands—install and start querying immediately. + +--- + +## Preparation + +Before you get started, make sure you have: + +1. **Node.js** >= 20.0.0 ([download link](https://nodejs.org/)) +2. **npm** (comes with Node.js) + +--- + +## Step 1: Install + +Run one command to install SUN CLI globally: + +```bash +npm install -g @bankofai/sun-cli +``` + +After installation, the `sun` command is available in your terminal. + +--- + +## Step 2: Your First Query + +Let's check the current price of TRX. Run: + +```bash +sun price TRX +``` + +You should see output like this: + +```text +✔ Fetching prices... +┌───────┬────────────────┐ +│ Token │ Price (USD) │ +├───────┼────────────────┤ +│ TRX │ 0.301739439813 │ +└───────┴────────────────┘ +``` + +That's it—you're connected to SunSwap. + +--- + +## Step 3: Explore More Data + +Try a few more read-only commands to see what's available: + +**Check top APY pools:** + +```bash +sun pool top-apy --page-size 5 +``` + +**Get a swap quote (no wallet required):** + +```bash +sun swap:quote TRX USDT 1000000 +``` + +This shows you the best route and expected output for swapping 1 TRX (1,000,000 sun) to USDT—without executing anything. + +**Get JSON output for scripting:** + +```bash +sun --json price USDT +``` + +--- + +## Configure a Wallet (For Write Operations) + +Read-only commands work out of the box. To execute swaps, manage liquidity, or send contract transactions, you need to configure a wallet. + +SUN CLI uses [`agent-wallet`](https://github.com/BofAI/agent-wallet) for wallet management. Install and configure it: + +```bash +npm install -g @bankofai/agent-wallet +``` + +Then set up your wallet following the [agent-wallet Quick Start guide](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start). + +:::caution Keep your keys safe +Never hardcode private keys or mnemonics in config files or shell history. Use environment variables or agent-wallet's encrypted storage. For testing, always start with the Nile testnet. +::: + +Once your wallet is configured, verify it: + +```bash +sun wallet address +``` + +You should see your wallet address and network: + +```json +{ "address": "TNmoJ...xxxxx", "network": "mainnet" } +``` + +--- + +## Execute Your First Swap (On Testnet) + +With a wallet configured, try a swap on the Nile testnet: + +```bash +sun swap TRX USDT 1000000 --network nile --yes +``` + +The `--yes` flag skips the confirmation prompt. The output includes the transaction ID and a Tronscan link to verify on-chain. + +:::tip Always test on Nile first +Before running any write operation on mainnet, verify it on the Nile testnet. Mainnet operations involve real assets and cannot be undone. +::: + +--- + +## Network & API Configuration + +Optionally, set these environment variables for customization: + +```bash +export TRON_NETWORK=mainnet +``` + +```bash +export TRONGRID_API_KEY="" +``` + +```bash +export TRON_RPC_URL=https://your-rpc +``` + +--- + +## Next Steps + +- **[Command Guide](./CommandGuide.md)** — Full reference for all commands: wallet, price, swap, liquidity, protocol, and contract operations +- **[FAQ](./FAQ.md)** — Troubleshooting common issues +- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi? Use SUN MCP Server for natural language interaction diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md new file mode 100644 index 0000000..c18f733 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md @@ -0,0 +1,377 @@ +# 命令指南 + +本页是 SUN CLI 所有命令的完整参考。命令按类别组织：钱包管理、行情数据、交易、流动性、协议分析和合约交互。 + +--- + +## 全局标志 + +所有命令都继承以下根级标志。**根级标志必须放在子命令之前。** + +| 标志 | 描述 | +| :--- | :--- | +| `--output ` | 输出格式：`table`、`json`、`tsv` | +| `--json` | JSON 输出的快捷方式 | +| `--fields ` | 逗号分隔的输出字段过滤 | +| `--network ` | 覆盖 `TRON_NETWORK`（如 `mainnet`、`nile`、`shasta`） | +| `-k, --private-key ` | 仅为本次调用提供私钥 | +| `-m, --mnemonic ` | 仅为本次调用提供助记词 | +| `-i, --mnemonic-account-index ` | 仅为本次调用提供助记词账户索引 | +| `-p, --agent-wallet-password ` | 覆盖本次调用的 `AGENT_WALLET_PASSWORD` | +| `-d, --agent-wallet-dir ` | 覆盖本次调用的 `AGENT_WALLET_DIR` | +| `-y, --yes` | 跳过确认提示 | +| `--dry-run` | 预览操作意图而不发送交易 | + +**示例：** + +```bash +sun --json price TRX +``` + +```bash +sun --output tsv pool top-apy --page-size 10 +``` + +```bash +sun --fields address,network wallet address +``` + +```bash +sun -k your_private_key --network nile --yes swap TRX USDT 1000000 +``` + +```bash +sun --dry-run contract send TContract transfer --args '["TRecipient","1000000"]' +``` + +--- + +## 钱包与持仓 + +查看已配置的钱包信息和链上余额。 + +### `wallet address` + +显示已配置的钱包地址和当前网络。 + +```bash +sun wallet address +``` + +### `wallet balances` + +查询活跃钱包或任意地址的代币余额。 + +```bash +sun wallet balances +``` + +```bash +sun wallet balances --owner TYourAddress --tokens TRX,TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `position list` + +查看某地址在 SunSwap 上的流动性仓位。 + +```bash +sun position list --owner TYourAddress +``` + +### `position tick` + +查询指定池子的 tick 数据。 + +```bash +sun position tick +``` + +### `farm positions` + +查看收益矿池仓位。 + +```bash +sun farm positions --owner TYourAddress +``` + +--- + +## 价格与发现 + +### `price` + +查询 SunSwap 上代币的实时价格。 + +```bash +sun price TRX +``` + +```bash +sun price USDT +``` + +```bash +sun price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `token list` + +按协议版本列出代币。 + +```bash +sun token list --protocol V3 +``` + +### `token search` + +按名称或符号搜索代币。 + +```bash +sun token search USDT +``` + +### `pool list` + +按代币过滤池子列表。 + +```bash +sun pool list --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `pool search` + +按交易对搜索池子。 + +```bash +sun pool search "TRX USDT" +``` + +### `pool top-apy` + +按 APY 排行列出池子。 + +```bash +sun pool top-apy --page-size 10 +``` + +### `pool hooks` + +列出启用了 hooks 的池子。 + +```bash +sun pool hooks +``` + +### `pair info` + +获取某代币的交易对信息。 + +```bash +sun pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +### `farm list` + +列出可用的收益矿池。 + +```bash +sun farm list +``` + +--- + +## 兑换 + +### `swap` + +通过最优路径执行代币兑换。需要已配置的钱包。 + +```bash +sun swap TRX USDT 1000000 --slippage 0.005 +``` + +```bash +sun -k your_private_key --network nile --yes swap TRX USDT 1000000 +``` + +成功响应包含 `txid`、路径详情和 `tronscanUrl` 链接。 + +### `swap:quote` + +获取只读兑换报价，不执行交易。无需钱包。 + +```bash +sun swap:quote TRX USDT 1000000 +``` + +```bash +sun swap:quote TRX USDT 1000000 --all +``` + +### `swap:quote-raw` + +使用原始参数的低级路由报价。 + +```bash +sun swap:quote-raw --router --args '[...]' +``` + +### `swap:exact-input` + +通过指定路由的低级精确输入兑换。 + +```bash +sun swap:exact-input --router --args '[...]' --value 1000000 +``` + +--- + +## 流动性 + +### V2 + +```bash +sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 +``` + +```bash +sun liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 +``` + +### V3 + +```bash +sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 +``` + +```bash +sun liquidity v3:increase --token-id 123 --amount0 500000 +``` + +```bash +sun liquidity v3:decrease --token-id 123 --liquidity 1000 +``` + +```bash +sun liquidity v3:collect --token-id 123 +``` + +### V4 + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 +``` + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool +``` + +```bash +sun liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000 +``` + +```bash +sun liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT +``` + +```bash +sun liquidity v4:collect --token-id 123 +``` + +```bash +sun liquidity v4:info --pm --token-id 123 +``` + +--- + +## 协议与历史 + +### 协议分析 + +```bash +sun protocol info +``` + +```bash +sun protocol vol-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol users-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol tx-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol pools-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun protocol liq-history --start 2026-01-01 --end 2026-03-01 +``` + +### 池子历史 + +```bash +sun pool vol-history --start 2026-01-01 --end 2026-03-01 +``` + +```bash +sun pool liq-history --start 2026-01-01 --end 2026-03-01 +``` + +### 交易扫描 + +```bash +sun tx scan --type swap --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --start 2026-01-01 +``` + +--- + +## 通用合约 + +读取或写入任意 TRON 智能合约。 + +### `contract read` + +```bash +sun contract read balanceOf --args '["TYourAddress"]' +``` + +### `contract send` + +```bash +sun contract send transfer --args '["TRecipient","1000000"]' --value 0 +``` + +`contract send` 交易广播成功后也会返回 `tronscanUrl` 链接。 + +--- + +## 内置代币符号 + +很多命令同时接受代币符号和完整的 TRON 地址： + +| 符号 | 地址 | 精度 | +| :--- | :--- | :--- | +| `TRX` | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` | 6 | +| `WTRX` | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | +| `USDT` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | +| `USDCOLD` | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | +| `USDD` | `TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn` | 18 | +| `SUN` | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | +| `JST` | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | +| `BTT` | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | +| `WIN` | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | + +你可以使用符号或完整地址： + +```bash +sun swap TRX USDT 1000000 +``` + +```bash +sun swap T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 +``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md new file mode 100644 index 0000000..405a377 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -0,0 +1,130 @@ +# 常见问题 + +SUN CLI 常见问题和故障排查。 + +--- + +## 安装与配置 + +### 系统要求是什么？ + +- **Node.js** 20.0.0 或更高版本 +- **npm**（随 Node.js 一起安装） +- 终端或 Shell 环境（macOS、Linux 或 Windows WSL） + +### 如何更新 SUN CLI？ + +```bash +npm update -g @bankofai/sun-cli +``` + +--- + +## 钱包与配置 + +### 提示"No wallet configured"怎么办？ + +写入操作（swap、liquidity、contract send）需要钱包。设置以下钱包源之一： + +- `AGENT_WALLET_PRIVATE_KEY` — 直接提供私钥 +- `AGENT_WALLET_MNEMONIC` — 助记词 +- `AGENT_WALLET_PASSWORD` — 通过 agent-wallet 的加密钱包 + +或者使用根级标志（`-k`、`-m`、`-p`）为单次调用提供钱包。详见 [agent-wallet 快速开始](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start)。 + +### 不配置钱包能用吗？ + +可以。所有只读命令无需任何钱包配置：价格查询、兑换报价、池子数据、协议统计、代币搜索等等。 + +### 我的私钥安全吗？ + +SUN CLI 永远不会将你的私钥上传到任何远程服务。所有签名都在本地完成。但要注意命令行标志（`-k`、`-m`）可能出现在 Shell 历史记录中。建议使用环境变量或 agent-wallet 的加密存储。 + +--- + +## 常见错误 + +### `unknown command 'nile'` + +`--network` 等根级标志必须放在**子命令之前**： + +```bash +# 正确 +sun --network nile swap TRX USDT 1000000 + +# 错误——'nile' 被解析为命令 +sun swap TRX USDT 1000000 --network nile +``` + +使用 npm scripts 时，在 `--` 后传递参数： + +```bash +npm run start -- --network nile swap TRX USDT 1000000 +``` + +### `Swap failed` + +常见原因： + +- 钱包未配置 +- 不支持的代币符号或无效地址 +- 余额不足 +- RPC 或路由 API 故障 +- 路径参数过期或无效 + +**建议：** 先运行 `swap:quote` 验证路径，确认报价合理后再使用 `--yes` 重试。 + +### 交易成功但结果不符预期 + +- **滑点**：在波动市场中，实际输出可能与报价不同。通过 `--slippage` 调整滑点容忍度。 +- **代币精度**：金额以代币最小单位指定。TRX（6 位精度），`1000000` = 1 TRX。 +- **网络不匹配**：确保你在目标网络上。用 `sun wallet address` 检查。 + +--- + +## AI Agent 集成 + +### AI Agent 能使用 SUN CLI 吗？ + +可以。SUN CLI 专为人类和 AI 驱动的工作流设计。自动化相关的关键特性： + +- `--json` 输出提供机器可读响应 +- `--yes` 标志跳过确认提示 +- `--dry-run` 预览操作而不执行 +- `--fields` 过滤输出到指定字段 +- 退出码用于脚本中的错误处理 + +### SUN CLI 和 SUN MCP Server 有什么区别？ + +SUN CLI 是直接调用的命令行工具。SUN MCP Server 是一个 MCP 兼容的服务器，AI 客户端（如 Claude）通过它进行自然语言 DeFi 交互。两者访问的是同一个 SunSwap 生态。脚本和自动化选 CLI，AI 辅助工作流选 MCP Server。 + +--- + +## 网络与代币 + +### 支持哪些网络？ + +主网、Nile 测试网和 Shasta 测试网。默认为主网。使用 `--network nile` 或 `--network shasta` 进行测试。 + +### 如何使用内置列表之外的代币？ + +使用代币的完整 TRON 合约地址代替符号： + +```bash +sun price --address TYourTokenAddress +sun swap TYourTokenAddress TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 +``` + +### 可以使用自定义 RPC 端点吗？ + +可以。设置 `TRON_RPC_URL` 环境变量： + +```bash +export TRON_RPC_URL=https://your-tron-rpc.example +``` + +--- + +## 还有其他问题？ + +如果这里没有覆盖你的问题，查看 [命令指南](./CommandGuide.md) 了解详细用法，或在 [GitHub 仓库](https://github.com/nicholaskarlson/sun-cli) 提交 Issue。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md new file mode 100644 index 0000000..a97d480 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md @@ -0,0 +1,127 @@ +# 简介 + +## SUN CLI 是什么？ + +SUN CLI（`@bankofai/sun-cli`）是一个命令行工具，让你在终端里就能使用 [SUN.IO（SunSwap）](https://sun.io) 的全部 DeFi 能力。无论你是开发者、运维人员还是 AI Agent，SUN CLI 都能通过一行命令完成代币价格查询、兑换执行、流动性管理等 TRON 链上操作。 + +简单理解：SUN MCP Server 让 AI 助手用自然语言与 SunSwap 对话，SUN CLI 则让你——或你的脚本和自动化流水线——用结构化命令与 SunSwap 对话。相同的 DeFi 能力，不同的交互方式。 + +举个例子，查询 TRX 的实时价格只需： + +```bash +sun price TRX +``` + +执行一笔兑换： + +```bash +sun swap TRX USDT 1000000 --yes +``` + +不需要打开浏览器，不需要前端界面，不需要手动与合约交互。 + +--- + +## 它能做什么？ + +SUN CLI 覆盖了与 SunSwap DEX 交互的完整操作，从实时行情数据到链上交易执行。 + +**数据查询（只读，无需钱包）：** + +| 能力 | 描述 | 示例命令 | +| :--- | :--- | :--- | +| **代币价格** | 查询 SunSwap 上任意代币的实时价格 | `sun price TRX` | +| **兑换报价** | 执行前获取最优路径和预期输出 | `sun swap:quote TRX USDT 1000000` | +| **池子数据** | 池子列表、APY 排行、交易量和流动性历史 | `sun pool top-apy --page-size 5` | +| **持仓查询** | 查看任意地址的流动性仓位 | `sun position list --owner TYourAddress` | +| **协议统计** | SunSwap 全局交易量、用户数、池数量、流动性历史 | `sun protocol info` | +| **矿池信息** | 收益矿池列表和用户挖矿持仓 | `sun farm list` | +| **代币发现** | 按名称搜索代币、按协议版本列表 | `sun token search USDT` | + +**DeFi 操作（写入，需要钱包）：** + +| 能力 | 描述 | 示例命令 | +| :--- | :--- | :--- | +| **代币兑换** | 通过 Universal Router 执行最优路径兑换 | `sun swap TRX USDT 1000000` | +| **V2 流动性** | 向 V2 池添加/移除流动性 | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000` | +| **V3 流动性** | 铸造、增加、减少集中流动性仓位，收取手续费 | `sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000` | +| **V4 流动性** | V4 集中流动性操作，支持 Permit2 授权 | `sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000` | +| **合约交互** | 读取或写入任意 TRON 智能合约 | `sun contract read
balanceOf --args '[...]'` | + +--- + +## SUN CLI vs SUN MCP Server + +两个工具连接的是同一个 SunSwap 生态，但服务于不同的使用场景： + +| 对比项 | SUN CLI | SUN MCP Server | +| :--- | :--- | :--- | +| **交互方式** | 终端命令 | AI 自然语言 | +| **适合场景** | 脚本、自动化、开发者 | AI 辅助 DeFi 操作 | +| **调用方式** | 直接 CLI 命令 + 参数 | AI 客户端发送 MCP 工具调用 | +| **输出格式** | Table、JSON、TSV | 结构化 MCP 响应 | +| **写入操作** | 支持（需配置钱包） | 支持（需本地部署） | +| **免确认模式** | `--yes` 标志跳过确认 | AI 处理确认流程 | + +:::tip 什么时候选 SUN CLI？ +当你需要编程式访问时——Shell 脚本、定时任务、CI/CD 流水线，或者你更喜欢明确的命令而非自然语言。如果你希望 AI 助手以对话方式处理 DeFi 操作，选择 SUN MCP Server。 +::: + +--- + +## 输出模式 + +SUN CLI 支持三种输出格式，同时友好于人类和机器： + +- **table** — 默认，人类友好的终端表格 +- **json** — 紧凑的机器可读 JSON，适合脚本和 AI Agent +- **tsv** — Tab 分隔值，适合 Shell 管道 + +```bash +sun pool top-apy --page-size 5 +``` + +```bash +sun --json wallet address +``` + +```bash +sun --output tsv token list --protocol V3 +``` + +--- + +## 支持的网络 + +SUN CLI 支持以下三个 TRON 网络（默认连接主网）： + +| 网络 | 标识符 | 用途 | 区块浏览器 | +| :--- | :--- | :--- | :--- | +| **主网** | `mainnet` | 生产环境，真实资产 | [tronscan.org](https://tronscan.org) | +| **Nile 测试网** | `nile` | 开发测试（推荐） | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta 测试网** | `shasta` | 开发测试 | [shasta.tronscan.org](https://shasta.tronscan.org) | + +通过 `--network` 标志指定目标网络。**强烈建议每次新操作先在 Nile 测试网上验证**——主网操作涉及真实资产，错误无法撤回。 + +--- + +## 安全注意事项 + +:::warning +DeFi 操作直接涉及链上资产，错误操作无法撤回。请牢记以下原则： + +- **切勿硬编码私钥**：使用环境变量或 [agent-wallet](https://github.com/BofAI/agent-wallet) 的加密存储，不要在共享环境中使用命令行参数传递密钥。 +- **先在测试网验证**：使用 `--network nile` 在主网执行前验证每个写操作。 +- **最小资金原则**：CLI 配置的钱包只存放当前任务所需的最低金额。 +- **使用 dry-run 模式**：高价值操作前运行 `--dry-run` 预览意图而不广播交易。 +- **验证代币地址**：不使用内置符号时，仔细核对合约地址。 +- **报价不等于保证**：在波动市场中，实际执行结果可能与报价不同。 +::: + +--- + +## 下一步 + +- 想最快速度上手？ → [快速开始](./QuickStart.md) +- 需要完整命令参考？ → [命令指南](./CommandGuide.md) +- 遇到问题？ → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/QuickStart.md new file mode 100644 index 0000000..a5a906c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/QuickStart.md @@ -0,0 +1,147 @@ +# 快速开始 + +这一页的目标很简单：**安装 SUN CLI，在 1 分钟内完成第一次 DeFi 查询。** + +只读命令不需要钱包——安装即用。 + +--- + +## 准备工作 + +开始之前，确保你已安装： + +1. **Node.js** >= 20.0.0（[下载链接](https://nodejs.org/)） +2. **npm**（随 Node.js 一起安装） + +--- + +## 第一步：安装 + +运行一行命令全局安装 SUN CLI： + +```bash +npm install -g @bankofai/sun-cli +``` + +安装完成后，终端里就能使用 `sun` 命令了。 + +--- + +## 第二步：你的第一次查询 + +查一下 TRX 当前的实时价格。运行： + +```bash +sun price TRX +``` + +你会看到类似这样的输出： + +```text +✔ Fetching prices... +┌───────┬────────────────┐ +│ Token │ Price (USD) │ +├───────┼────────────────┤ +│ TRX │ 0.301739439813 │ +└───────┴────────────────┘ +``` + +就这么简单——你已经连上 SunSwap 了。 + +--- + +## 第三步：探索更多数据 + +再试几个只读命令，看看还能查什么： + +**查看 APY 最高的池子：** + +```bash +sun pool top-apy --page-size 5 +``` + +**获取兑换报价（不需要钱包）：** + +```bash +sun swap:quote TRX USDT 1000000 +``` + +这会显示将 1 TRX（1,000,000 sun）兑换为 USDT 的最佳路径和预期输出——不会执行任何交易。 + +**获取 JSON 格式输出（适合脚本）：** + +```bash +sun --json price USDT +``` + +--- + +## 配置钱包（用于写入操作） + +只读命令开箱即用。要执行兑换、管理流动性或发送合约交易，需要配置钱包。 + +SUN CLI 使用 [`agent-wallet`](https://github.com/BofAI/agent-wallet) 进行钱包管理。先安装： + +```bash +npm install -g @bankofai/agent-wallet +``` + +然后按照 [agent-wallet 快速开始指南](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) 配置你的钱包。 + +:::caution 保管好你的密钥 +切勿将私钥或助记词硬编码在配置文件或 Shell 历史记录中。使用环境变量或 agent-wallet 的加密存储。测试时请始终使用 Nile 测试网。 +::: + +钱包配置完成后，验证一下： + +```bash +sun wallet address +``` + +你会看到你的钱包地址和当前网络： + +```json +{ "address": "TNmoJ...xxxxx", "network": "mainnet" } +``` + +--- + +## 在测试网执行第一笔兑换 + +钱包配置好后，在 Nile 测试网上试一笔兑换： + +```bash +sun swap TRX USDT 1000000 --network nile --yes +``` + +`--yes` 标志跳过确认提示。输出包含交易 ID 和 Tronscan 链接，可以在链上查证。 + +:::tip 先在 Nile 测试网验证 +在主网执行任何写操作前，先在 Nile 测试网上跑通。主网操作涉及真实资产，错误无法撤回。 +::: + +--- + +## 网络与 API 配置 + +可选的环境变量自定义： + +```bash +export TRON_NETWORK=mainnet +``` + +```bash +export TRONGRID_API_KEY="" +``` + +```bash +export TRON_RPC_URL=https://your-rpc +``` + +--- + +## 下一步 + +- **[命令指南](./CommandGuide.md)** — 所有命令的完整参考：钱包、价格、兑换、流动性、协议、合约操作 +- **[常见问题](./FAQ.md)** — 常见问题排查 +- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — 更喜欢 AI 驱动的 DeFi？用 SUN MCP Server 实现自然语言交互 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js index 1edc900..dfae07c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -134,6 +134,17 @@ const sidebars = { 'McpServer-Skills/MCP/BSCMCPServer/Installation', ], }, + { + type: 'category', + label: 'SUN CLI', + collapsed: true, + items: [ + 'McpServer-Skills/MCP/SUNCli/Intro', + 'McpServer-Skills/MCP/SUNCli/QuickStart', + 'McpServer-Skills/MCP/SUNCli/CommandGuide', + 'McpServer-Skills/MCP/SUNCli/FAQ', + ], + }, ], }, { diff --git a/sidebars.js b/sidebars.js index 96a41ef..9380f2e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -130,6 +130,17 @@ const sidebars = { 'McpServer-Skills/MCP/BSCMCPServer/Installation', ], }, + { + type: 'category', + label: 'SUN CLI', + collapsed: true, + items: [ + 'McpServer-Skills/MCP/SUNCli/Intro', + 'McpServer-Skills/MCP/SUNCli/QuickStart', + 'McpServer-Skills/MCP/SUNCli/CommandGuide', + 'McpServer-Skills/MCP/SUNCli/FAQ', + ], + }, ], }, { From 5a8e32076a4f95c7c2316c8d28d697883cde2e6e Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Thu, 2 Apr 2026 17:37:50 +0800 Subject: [PATCH 02/33] fix --- docs/McpServer-Skills/MCP/SUNCli/FAQ.md | 3 +++ .../current/McpServer-Skills/MCP/SUNCli/FAQ.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/McpServer-Skills/MCP/SUNCli/FAQ.md b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md index b49bf66..b9f8c18 100644 --- a/docs/McpServer-Skills/MCP/SUNCli/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -112,6 +112,9 @@ Use the token's full TRON contract address instead of a symbol: ```bash sun price --address TYourTokenAddress +``` + +```bash sun swap TYourTokenAddress TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md index 405a377..81411e6 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -112,6 +112,9 @@ SUN CLI 是直接调用的命令行工具。SUN MCP Server 是一个 MCP 兼容 ```bash sun price --address TYourTokenAddress +``` + +```bash sun swap TYourTokenAddress TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t 1000000 ``` From 33352407e79fc6b5145b31abbc5cedb3e3791949 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 7 Apr 2026 15:37:52 +0800 Subject: [PATCH 03/33] add gas free --- .../network-and-token-support.md | 26 +++++++++++++------ docs/x402/faq.md | 5 +++- .../getting-started/quickstart-for-agent.md | 6 ++--- .../getting-started/quickstart-for-human.md | 23 +++++++++++++--- .../getting-started/quickstart-for-sellers.md | 4 +-- docs/x402/index.md | 2 +- docs/x402/sdk-features.md | 4 +++ .../network-and-token-support.md | 17 +++++++++--- .../current/x402/faq.md | 5 +++- .../getting-started/quickstart-for-agent.md | 6 ++--- .../getting-started/quickstart-for-human.md | 19 ++++++++++++-- .../getting-started/quickstart-for-sellers.md | 4 +-- .../current/x402/index.md | 2 +- .../current/x402/sdk-features.md | 8 ++++-- 14 files changed, 98 insertions(+), 33 deletions(-) diff --git a/docs/x402/core-concepts/network-and-token-support.md b/docs/x402/core-concepts/network-and-token-support.md index 8acbca2..d4d6ca8 100644 --- a/docs/x402/core-concepts/network-and-token-support.md +++ b/docs/x402/core-concepts/network-and-token-support.md @@ -100,29 +100,39 @@ When configuring an `HTTP 402` payment request on the server side, you must expl ## Payment Scheme -x402 supports two payment schemes: `exact_permit` and `exact`. +x402 supports three payment schemes: `exact_permit`, `exact`, and `exact_gasfree`. ### `exact_permit` Scheme The `exact_permit` scheme transfers tokens via the `PaymentPermit` contract, suitable for: -- **Pay-per-use APIs** (e.g., LLM token generation, image generation services) -- **Metered resources** (cloud compute time, storage usage, bandwidth consumption) -- **Dynamic pricing services** based on actual usage +- **Pay-per-use APIs** (e.g., LLM token generation, image generation services) +- **Metered resources** (cloud compute time, storage usage, bandwidth consumption) +- **Dynamic pricing services** based on actual usage ### `exact` Scheme The `exact` scheme is for tokens that natively support `transferWithAuthorization`. It does not require the `PaymentPermit` contract. +### `exact_gasfree` Scheme + +The `exact_gasfree` scheme is a TRON-specific payment mechanism that allows users to pay with USDT/USDD **without holding TRX for gas fees**. Settlement is handled via the official GasFree Proxy through the BankOfAI facilitator endpoint. + +Key characteristics: + +- **Zero gas cost for buyers**: Buyers do not need to hold TRX — gas is covered by the GasFree infrastructure +- **No API keys required**: All GasFree API calls route through the BankOfAI proxy at `https://facilitator.bankofai.io/{mainnet,nile}`, so clients do not need to configure `GASFREE_API_KEY` or `GASFREE_API_SECRET` +- **TRON only**: Available on `tron:mainnet` and `tron:nile` + ### How Payment Schemes Work -1. **Authorize** +1. **Authorize** The client signs a message authorizing a **maximum amount**. -2. **Execute** +2. **Execute** The server performs the requested task and calculates the **actual cost**. -3. **Settle** +3. **Settle** The Facilitator submits the on-chain transaction based on the actual cost. --- @@ -154,7 +164,7 @@ You may deploy your own Facilitator node to gain full control over payment verif | **Networks** | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97` | | **Token Standard** | TRC-20 (built-in USDT & USDD support), BEP-20 | | **Signing Mechanism** | Typed data signing | -| **Payment Scheme** | `exact_permit`, `exact` | +| **Payment Scheme** | `exact_permit`, `exact`, `exact_gasfree` (TRON only) | --- diff --git a/docs/x402/faq.md b/docs/x402/faq.md index 519950a..b0f4c17 100644 --- a/docs/x402/faq.md +++ b/docs/x402/faq.md @@ -67,7 +67,10 @@ Common pricing models include: #### What payment schemes does x402 support? -x402 supports `exact_permit` and `exact` payment schemes. Both allow the client to authorize a **maximum payment amount**, and the server to settle the **actual cost incurred** (up to the authorized limit). This is ideal for **metered billing**, **LLM token usage**, and similar use cases. +x402 supports three payment schemes: + +- **`exact_permit`** and **`exact`**: Both allow the client to authorize a **maximum payment amount**, and the server to settle the **actual cost incurred** (up to the authorized limit). This is ideal for **metered billing**, **LLM token usage**, and similar use cases. +- **`exact_gasfree`** (TRON only): Allows buyers to pay with USDT/USDD without holding TRX for gas. All GasFree API calls are routed through the BankOfAI proxy — no API keys required on the client side. --- diff --git a/docs/x402/getting-started/quickstart-for-agent.md b/docs/x402/getting-started/quickstart-for-agent.md index e3fc4cb..198272d 100644 --- a/docs/x402/getting-started/quickstart-for-agent.md +++ b/docs/x402/getting-started/quickstart-for-agent.md @@ -60,10 +60,10 @@ Set your agent wallet's private key as environment variables so the x402-payment ```bash export TRON_PRIVATE_KEY="your_agent_wallet_private_key_here" -export TRON_GRID_API_KEY="your_trongrid_api_key_here" # Recommended to avoid RPC rate limits +export TRON_GRID_API_KEY="your_trongrid_api_key_here" # Recommended for production workloads ``` -> 💡 **How to get a TronGrid API Key:** Register for free at [TronGrid](https://www.trongrid.io/), create an API Key, and paste it above. You can leave this blank during testnet testing, but it is required for mainnet. +> 💡 **How to get a TronGrid API Key:** Register for free at [TronGrid](https://www.trongrid.io/), create an API Key, and paste it above. When `TRON_GRID_API_KEY` is not set, mainnet RPC calls are automatically routed to a BankOfAI-operated fallback endpoint. Setting this key is recommended for production workloads to ensure optimal performance. @@ -194,7 +194,7 @@ Before deploying your agent to production, make sure to review the following: | Agent doesn't initiate payment, errors immediately | Skill not installed correctly | Re-run the installation command in Step 2 | | `Private key not found` or signing fails | Environment variable not set or misconfigured | Re-run Step 1, and make sure you run the agent **in the same terminal session** | | Insufficient balance error | No test tokens in the agent wallet | Go back to Prerequisites and claim test tokens from the faucet | -| Request times out | Network issue or RPC rate limiting | Configure `TRON_GRID_API_KEY` to avoid rate limits | +| Request times out | Network issue or RPC rate limiting | Configure `TRON_GRID_API_KEY` for better performance (a fallback endpoint is used automatically when not set) | | Agent accesses successfully but balance doesn't change | May have accessed a free endpoint | Confirm the URL path is `/protected-nile`, not another path | --- diff --git a/docs/x402/getting-started/quickstart-for-human.md b/docs/x402/getting-started/quickstart-for-human.md index c3f1a54..95657cc 100644 --- a/docs/x402/getting-started/quickstart-for-human.md +++ b/docs/x402/getting-started/quickstart-for-human.md @@ -212,7 +212,10 @@ import httpx from bankofai.x402.clients import X402Client, X402HttpClient, SufficientBalancePolicy from bankofai.x402.mechanisms.tron.exact_permit import ExactPermitTronClientMechanism +from bankofai.x402.mechanisms.tron.exact_gasfree.client import ExactGasFreeClientMechanism from bankofai.x402.signers.client import TronClientSigner +from bankofai.x402.utils.gasfree import GasFreeAPIClient +from bankofai.x402.config import NetworkConfig # ========== Configuration ========== @@ -221,14 +224,21 @@ from bankofai.x402.signers.client import TronClientSigner SERVER_URL = "https://x402-demo.bankofai.io/protected-nile" # ==================================== +# GasFree API clients (routed through BankOfAI proxy — no API keys needed) +gasfree_clients = { + "tron:nile": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:nile")), + "tron:mainnet": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:mainnet")), +} + async def main(): # Initialize signer with your private key (network is resolved dynamically) signer = TronClientSigner.from_private_key(os.getenv("TRON_PRIVATE_KEY")) - # Create x402 client and register the payment mechanism and balance policy + # Create x402 client and register payment mechanisms and balance policy x402_client = X402Client() x402_client.register("tron:*", ExactPermitTronClientMechanism(signer)) + x402_client.register("tron:*", ExactGasFreeClientMechanism(signer, clients=gasfree_clients)) x402_client.register_policy(SufficientBalancePolicy) async with httpx.AsyncClient(timeout=60.0) as http_client: @@ -264,8 +274,9 @@ Response: {"data": "This is premium content!"} import 'dotenv/config' import { X402Client, X402FetchClient, - ExactPermitTronClientMechanism, TronClientSigner, - SufficientBalancePolicy, + ExactPermitTronClientMechanism, ExactGasFreeClientMechanism, + TronClientSigner, SufficientBalancePolicy, + GasFreeAPIClient, getGasFreeApiBaseUrl, } from '@bankofai/x402' const TRON_PRIVATE_KEY = process.env.TRON_PRIVATE_KEY! @@ -280,9 +291,13 @@ async function main(): Promise { // Initialize signer with your private key const signer = new TronClientSigner(TRON_PRIVATE_KEY) - // Create x402 client and register the payment mechanism and balance policy + // Create x402 client and register payment mechanisms and balance policy const x402 = new X402Client() x402.register('tron:*', new ExactPermitTronClientMechanism(signer)) + x402.register('tron:*', new ExactGasFreeClientMechanism(signer, { + 'tron:nile': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:nile')), + 'tron:mainnet': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:mainnet')), + })) x402.registerPolicy(SufficientBalancePolicy) const client = new X402FetchClient(x402) diff --git a/docs/x402/getting-started/quickstart-for-sellers.md b/docs/x402/getting-started/quickstart-for-sellers.md index 91e44de..db47558 100644 --- a/docs/x402/getting-started/quickstart-for-sellers.md +++ b/docs/x402/getting-started/quickstart-for-sellers.md @@ -396,7 +396,7 @@ Open the `.env` file in the `x402-demo` directory with a text editor and fill in # How to get it: TronLink → Settings → Account Management → Export Private Key TRON_PRIVATE_KEY=paste_your_facilitator_private_key_here -# TronGrid API Key (required for mainnet, can be left blank for testnet) +# TronGrid API Key (recommended for production; when not set, a BankOfAI fallback endpoint is used automatically) # Apply at: https://www.trongrid.io/ TRON_GRID_API_KEY= ``` @@ -545,7 +545,7 @@ Modify the `network` parameter in the `@x402_protected` decorator in `server.py` -1. **Apply for a TronGrid API Key**: go to [TronGrid](https://www.trongrid.io/) to register and create an API Key, then fill it into the `TRON_GRID_API_KEY` field in `.env` (required for mainnet) +1. **Apply for a TronGrid API Key**: go to [TronGrid](https://www.trongrid.io/) to register and create an API Key, then fill it into the `TRON_GRID_API_KEY` field in `.env` (recommended for production; a BankOfAI fallback endpoint is used automatically when not set) 2. **Replace the private key**: update the private key in `.env` to the mainnet Facilitator wallet's private key 3. **Fund the fee wallet**: transfer sufficient real TRX to the Facilitator mainnet wallet (to pay Energy and Bandwidth fees) 4. **Update the network config**: change the network configuration in the Facilitator code to `NetworkConfig.TRON_MAINNET` diff --git a/docs/x402/index.md b/docs/x402/index.md index 2ac6828..29ef3cf 100644 --- a/docs/x402/index.md +++ b/docs/x402/index.md @@ -9,7 +9,7 @@ description: >- x402 is an open blockchain payment standard built on the HTTP `402 Payment Required` status code. It enables web services to charge for APIs or content through a “pay-before-response” mechanism — without relying on traditional account systems or session management. -x402 currently supports the TRON and BSC networks, with plans to expand to a broader multi-chain ecosystem in the future. +x402 currently supports the **TRON** and **BSC** networks, with plans to expand to a broader multi-chain ecosystem in the future. **Interested in contributing to the documentation?** Feel free to submit a PR to the [GitHub repository](https://github.com/BofAI/docs). Our only principle is to maintain neutrality — aside from essential resource links, please avoid promotional or branded content. diff --git a/docs/x402/sdk-features.md b/docs/x402/sdk-features.md index 05f280a..94493b0 100644 --- a/docs/x402/sdk-features.md +++ b/docs/x402/sdk-features.md @@ -46,6 +46,7 @@ This page tracks the implementation progress and feature support status of the x | exact_permit/bsc | ✅ | ✅ | | exact/tron | ✅ | ✅ | | exact/bsc | ✅ | ✅ | +| exact_gasfree/tron | ✅ | ✅ | --- @@ -69,6 +70,8 @@ This page tracks the implementation progress and feature support status of the x | Allowance check | ✅ | ✅ | | Signing (TRON) | ✅ | ✅ | | Signing (EVM) | ✅ | ✅ | +| SufficientBalancePolicy | ✅ | ✅ | +| GasFree (zero-gas TRON payments) | ✅ | ✅ | --- @@ -101,6 +104,7 @@ This page tracks the implementation progress and feature support status of the x | Token | Python | TypeScript | |--------|--------|------------| | USDT (TRC-20) | ✅ | ✅ | +| USDD (TRC-20) | ✅ | ✅ | | Custom TRC-20 | ✅ | ✅ | | USDT (BEP-20) | ✅ | ✅ | | Custom BEP-20 | ✅ | ✅ | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md index b4ae2f4..206ef87 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md @@ -40,6 +40,7 @@ x402 专为区块链生态设计，实现了原生的链上支付验证与结算 | **TRON Shasta** | **Testnet** | **备用测试网**：长期稳定的测试环境。 | | **BSC Mainnet** | **Mainnet** | **生产网络**：用于处理真实价值资产。 | | **BSC Testnet** | **Testnet** | **推荐测试网**：BSC 首选的开发与调试环境。 | + ### 支持的代币 x402 协议全面支持 **TRC-20/BEP-20** 标准代币，并默认将 **USDT** 和 **USDD** 作为主要结算货币。 @@ -81,7 +82,7 @@ x402 采用类型化数据签名来处理所有支付相关的签名授权。 ### 支付方案 -x402 支持两种支付方案：`exact_permit` 和 `exact`。 +x402 支持三种支付方案：`exact_permit`、`exact` 和 `exact_gasfree`。 #### `exact_permit` 方案 @@ -95,6 +96,16 @@ x402 支持两种支付方案：`exact_permit` 和 `exact`。 `exact` 方案适用于原生支持 `transferWithAuthorization` 的代币，无需 `PaymentPermit` 合约。 +#### `exact_gasfree` 方案 + +`exact_gasfree` 是 TRON 专属的支付机制，允许用户使用 USDT/USDD 付款而**无需持有 TRX 来支付 gas 费用**。结算通过 BankOfAI Facilitator 端点的官方 GasFree 代理完成。 + +核心特性： + +- **买家零 gas 成本**：买家无需持有 TRX，gas 费用由 GasFree 基础设施承担 +- **无需 API 密钥**：所有 GasFree API 调用通过 BankOfAI 代理路由至 `https://facilitator.bankofai.io/{mainnet,nile}`，客户端无需配置 `GASFREE_API_KEY` 或 `GASFREE_API_SECRET` +- **仅限 TRON**：支持 `tron:mainnet` 和 `tron:nile` + #### 工作原理 1. **预授权 (Authorize)**：客户端签署消息，授权支付**最大金额** (Max Amount)。 @@ -123,10 +134,10 @@ Facilitator 作为协议的中间件，承担以下核心职责： | 核心组件 | TRON/BSC 实现详情 | | :----------- | :----------------------------------------- | -| **网络环境** | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97`| +| **网络环境** | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97` | | **代币标准** | TRC-20 代币（默认内置 USDT 和 USDD 支持）,BEP-20 代币 | | **签名机制** | 类型化数据签名 | -| **支付方案** | `exact_permit`, `exact` | +| **支付方案** | `exact_permit`, `exact`, `exact_gasfree`（仅限 TRON） | ### 添加自定义代币 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md index efcc807..eb1559b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md @@ -59,7 +59,10 @@ x402 目前提供以下 SDK： #### x402 支持哪些支付方案？ -x402 支持 `exact_permit` 和 `exact` 两种支付方案。两种方案均允许客户端授权一个**最高支付金额**，服务端结算**实际产生的费用**（不超过授权上限）。此方案非常适用于**按量计费 (Metered Billing)**、**LLM Token 消耗**等场景。 +x402 支持三种支付方案： + +- **`exact_permit`** 和 **`exact`**：两种方案均允许客户端授权一个**最高支付金额**，服务端结算**实际产生的费用**（不超过授权上限）。此方案非常适用于**按量计费 (Metered Billing)**、**LLM Token 消耗**等场景。 +- **`exact_gasfree`**（仅限 TRON）：允许买家使用 USDT/USDD 付款而无需持有 TRX 来支付 gas。所有 GasFree API 调用通过 BankOfAI 代理路由，客户端无需配置 API 密钥。 ### 资产、网络及费用 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md index e4b5d56..70414b1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md @@ -60,10 +60,10 @@ x402 专为 Agentic Web 设计。通过安装 `x402-payment` 技能，AI 代理 ```bash export TRON_PRIVATE_KEY="在此填入代理钱包私钥" -export TRON_GRID_API_KEY="在此填入TronGrid API Key" # 推荐配置，防止 RPC 限速 +export TRON_GRID_API_KEY="在此填入TronGrid API Key" # 生产环境推荐配置 ``` -> 💡 **如何获取 TronGrid API Key：** 前往 [TronGrid 官网](https://www.trongrid.io/) 免费注册，创建 API Key 后粘贴到上方。测试网阶段可暂时留空，但主网阶段必须配置。 +> 💡 **如何获取 TronGrid API Key：** 前往 [TronGrid 官网](https://www.trongrid.io/) 免费注册，创建 API Key 后粘贴到上方。未配置 `TRON_GRID_API_KEY` 时，主网 RPC 调用会自动路由至 BankOfAI 运营的备用 RPC 端点。生产环境建议配置此 Key 以获得最佳性能。 @@ -194,7 +194,7 @@ https://x402-demo.bankofai.io/protected-nile | 代理未发起付款，直接报错 | 技能未正确安装 | 重新执行第二步的安装命令 | | `私钥未找到` 或签名失败 | 环境变量未配置或配置错误 | 重新执行第一步，在**同一终端**中运行代理 | | 余额不足错误 | 测试钱包中没有测试代币 | 回到前置准备，从水龙头领取测试代币 | -| 请求超时 | 网络问题或 RPC 限速 | 配置 `TRON_GRID_API_KEY` 以避免限速 | +| 请求超时 | 网络问题或 RPC 限速 | 配置 `TRON_GRID_API_KEY` 以获得更好的性能（未配置时会自动使用备用 RPC 端点） | | 代理访问成功但余额没有变化 | 可能访问的是免费接口 | 确认 URL 是 `/protected-nile` 而非其他路径 | --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md index e9e03c1..4bdef1c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md @@ -216,7 +216,10 @@ import httpx from bankofai.x402.clients import X402Client, X402HttpClient, SufficientBalancePolicy from bankofai.x402.mechanisms.tron.exact_permit import ExactPermitTronClientMechanism +from bankofai.x402.mechanisms.tron.exact_gasfree.client import ExactGasFreeClientMechanism from bankofai.x402.signers.client import TronClientSigner +from bankofai.x402.utils.gasfree import GasFreeAPIClient +from bankofai.x402.config import NetworkConfig # ========== 配置项 ========== @@ -225,6 +228,12 @@ from bankofai.x402.signers.client import TronClientSigner SERVER_URL = "https://x402-demo.bankofai.io/protected-nile" # =========================== +# GasFree API 客户端（通过 BankOfAI 代理路由，无需 API 密钥） +gasfree_clients = { + "tron:nile": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:nile")), + "tron:mainnet": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:mainnet")), +} + async def main(): # 用私钥初始化签名器（网络由服务器响应动态确定） @@ -233,6 +242,7 @@ async def main(): # 创建 x402 客户端，注册付款机制和余额检查策略 x402_client = X402Client() x402_client.register("tron:*", ExactPermitTronClientMechanism(signer)) + x402_client.register("tron:*", ExactGasFreeClientMechanism(signer, clients=gasfree_clients)) x402_client.register_policy(SufficientBalancePolicy) async with httpx.AsyncClient(timeout=60.0) as http_client: @@ -268,8 +278,9 @@ python client.py import 'dotenv/config' import { X402Client, X402FetchClient, - ExactPermitTronClientMechanism, TronClientSigner, - SufficientBalancePolicy, + ExactPermitTronClientMechanism, ExactGasFreeClientMechanism, + TronClientSigner, SufficientBalancePolicy, + GasFreeAPIClient, getGasFreeApiBaseUrl, } from '@bankofai/x402' const TRON_PRIVATE_KEY = process.env.TRON_PRIVATE_KEY! @@ -287,6 +298,10 @@ async function main(): Promise { // 创建 x402 客户端，注册付款机制和余额检查策略 const x402 = new X402Client() x402.register('tron:*', new ExactPermitTronClientMechanism(signer)) + x402.register('tron:*', new ExactGasFreeClientMechanism(signer, { + 'tron:nile': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:nile')), + 'tron:mainnet': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:mainnet')), + })) x402.registerPolicy(SufficientBalancePolicy) const client = new X402FetchClient(x402) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md index f31500d..7a70735 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md @@ -397,7 +397,7 @@ cp .env.sample .env # 获取方式：TronLink → 设置 → 账户管理 → 导出私钥 TRON_PRIVATE_KEY=在此填入Facilitator专用钱包的私钥 -# TronGrid API Key（主网必填，测试网可暂时留空） +# TronGrid API Key（生产环境推荐配置；未配置时会自动使用 BankOfAI 备用 RPC 端点） # 申请地址：https://www.trongrid.io/ TRON_GRID_API_KEY= ``` @@ -546,7 +546,7 @@ curl http://localhost:8000/protected -1. **申请 TronGrid API Key**：前往 [TronGrid](https://www.trongrid.io/) 注册并创建 API Key，填入 `.env` 的 `TRON_GRID_API_KEY` 字段（主网必须） +1. **申请 TronGrid API Key**：前往 [TronGrid](https://www.trongrid.io/) 注册并创建 API Key，填入 `.env` 的 `TRON_GRID_API_KEY` 字段（生产环境推荐；未配置时会自动使用 BankOfAI 备用 RPC 端点） 2. **替换私钥**：将 `.env` 中的私钥替换为主网 Facilitator 钱包的私钥 3. **充值手续费**：向 Facilitator 主网钱包转入足够的真实 TRX（用于支付 Energy 和 Bandwidth 费用） 4. **更新网络配置**：将 Facilitator 代码中的网络配置改为 `NetworkConfig.TRON_MAINNET` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md index 48b78cc..f8902d7 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md @@ -7,7 +7,7 @@ description: >- # 欢迎使用 x402 -x402 是一种基于 HTTP `402 Payment Required` 状态码的区块链开放支付标准。它允许 Web 服务通过“先付费后响应”的机制直接对 API 或内容进行收费，无需依赖传统的账户或会话体系。目前，x402 已在 TRON 和 BSC 网络上支持，并计划在未来扩展至多链生态，实现广泛的区块链网络覆盖。 +x402 是一种基于 HTTP `402 Payment Required` 状态码的区块链开放支付标准。它允许 Web 服务通过“先付费后响应”的机制直接对 API 或内容进行收费，无需依赖传统的账户或会话体系。目前，x402 已在 **TRON** 和 **BSC** 网络上支持，并计划在未来扩展至多链生态，实现广泛的区块链网络覆盖。 **有意参与文档共建？** 欢迎在 [GitHub 仓库](https://github.com/BofAI/docs)提交 PR！我们唯一的原则是保持文档的中立性：除必要的资源链接外，请避免包含任何品牌推广内容。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md index b80fb22..fc285b1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md @@ -24,8 +24,8 @@ | tron:mainnet | ✅ | ✅ | | tron:nile | ✅ | ✅ | | tron:shasta | ✅ | ✅ | -| bsc:mainnet | ✅ | ✅ | -| bsc:testnet | ✅ | ✅ | +| eip155:56 (BSC Mainnet) | ✅ | ✅ | +| eip155:97 (BSC Testnet) | ✅ | ✅ | ## 机制 @@ -36,6 +36,7 @@ | exact_permit/bsc | ✅ | ✅ | | exact/tron | ✅ | ✅ | | exact/bsc | ✅ | ✅ | +| exact_gasfree/tron | ✅ | ✅ | ## 签名器 @@ -55,6 +56,8 @@ | 额度检查 | ✅ | ✅ | | 签名 (TRON) | ✅ | ✅ | | 签名 (EVM) | ✅ | ✅ | +| SufficientBalancePolicy（余额检查策略） | ✅ | ✅ | +| GasFree（TRON 零 gas 支付） | ✅ | ✅ | ## 服务端功能 @@ -81,6 +84,7 @@ | 代币 | Python | TypeScript | |-------|--------|------------| | USDT (TRC-20) | ✅ | ✅ | +| USDD (TRC-20) | ✅ | ✅ | | 自定义 TRC-20 | ✅ | ✅ | | USDT (BEP-20) | ✅ | ✅ | | 自定义 BEP-20 | ✅ | ✅ | From d69c9ebbfeca4d1a815dd3cf7922d5c17e37ed59 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 7 Apr 2026 16:17:09 +0800 Subject: [PATCH 04/33] add cuncli --- .../MCP/SUNCli/CommandGuide.md | 30 +++++++++++++++++-- docs/McpServer-Skills/MCP/SUNCli/FAQ.md | 2 +- docs/McpServer-Skills/MCP/SUNCli/Intro.md | 2 +- .../MCP/SUNCli/CommandGuide.md | 30 +++++++++++++++++-- .../McpServer-Skills/MCP/SUNCli/FAQ.md | 2 +- .../McpServer-Skills/MCP/SUNCli/Intro.md | 2 +- 6 files changed, 58 insertions(+), 10 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md index 97654f4..24b9881 100644 --- a/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md +++ b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md @@ -230,54 +230,78 @@ sun swap:exact-input --router --args '[...]' --value 1000000 ### V2 +Create a new liquidity pool (both token amounts required): + ```bash sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 ``` +Add liquidity to an existing pool (the other token amount is calculated automatically): + +```bash +sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 +``` + +Remove liquidity: + ```bash sun liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 ``` ### V3 +Mint a new concentrated liquidity position: + ```bash sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 ``` +Increase liquidity of an existing position: + ```bash sun liquidity v3:increase --token-id 123 --amount0 500000 ``` +Decrease liquidity of an existing position: + ```bash sun liquidity v3:decrease --token-id 123 --liquidity 1000 ``` +Collect accrued fees: + ```bash sun liquidity v3:collect --token-id 123 ``` ### V4 -```bash -sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 -``` +Mint a new concentrated liquidity position (`--create-pool` creates the pool automatically if it does not exist): ```bash sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool ``` +Increase liquidity of an existing position: + ```bash sun liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000 ``` +Decrease liquidity of an existing position: + ```bash sun liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT ``` +Collect accrued fees: + ```bash sun liquidity v4:collect --token-id 123 ``` +Query position info: + ```bash sun liquidity v4:info --pm --token-id 123 ``` diff --git a/docs/McpServer-Skills/MCP/SUNCli/FAQ.md b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md index b9f8c18..8c229fc 100644 --- a/docs/McpServer-Skills/MCP/SUNCli/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -130,4 +130,4 @@ export TRON_RPC_URL=https://your-tron-rpc.example ## Still Need Help? -If your question isn't covered here, check the [Command Guide](./CommandGuide.md) for detailed usage, or file an issue on the [GitHub repository](https://github.com/nicholaskarlson/sun-cli). +If your question isn't covered here, check the [Command Guide](./CommandGuide.md) for detailed usage, or file an issue on the [GitHub repository](https://github.com/BofAI/sun-cli). diff --git a/docs/McpServer-Skills/MCP/SUNCli/Intro.md b/docs/McpServer-Skills/MCP/SUNCli/Intro.md index 939bd6a..03dd8a9 100644 --- a/docs/McpServer-Skills/MCP/SUNCli/Intro.md +++ b/docs/McpServer-Skills/MCP/SUNCli/Intro.md @@ -43,7 +43,7 @@ SUN CLI covers the full range of SunSwap DEX interactions, from real-time market | Capability | Description | Example Command | | :--- | :--- | :--- | | **Token Swap** | Execute optimal-route swaps via the Universal Router | `sun swap TRX USDT 1000000` | -| **V2 Liquidity** | Add/remove V2 pool liquidity | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000` | +| **V2 Liquidity** | Create pools or add/remove V2 pool liquidity | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000` | | **V3 Liquidity** | Mint, increase, decrease concentrated positions, collect fees | `sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000` | | **V4 Liquidity** | V4 concentrated liquidity with Permit2 authorization | `sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000` | | **Contract Interaction** | Read or write to any TRON smart contract | `sun contract read
balanceOf --args '[...]'` | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md index c18f733..74fdd90 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md @@ -230,54 +230,78 @@ sun swap:exact-input --router --args '[...]' --value 1000000 ### V2 +创建流动性池（需要输入两个代币数量）： + ```bash sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000 ``` +向已有池子添加流动性（另一个代币数量会根据输入的第一个代币数量自动计算）： + +```bash +sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 +``` + +移除流动性： + ```bash sun liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 ``` ### V3 +创建集中流动性仓位： + ```bash sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 ``` +增加已有仓位的流动性： + ```bash sun liquidity v3:increase --token-id 123 --amount0 500000 ``` +移除已有仓位的流动性： + ```bash sun liquidity v3:decrease --token-id 123 --liquidity 1000 ``` +领取累积的手续费奖励： + ```bash sun liquidity v3:collect --token-id 123 ``` ### V4 -```bash -sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 -``` +创建集中流动性仓位（`--create-pool` 会在池子不存在时自动创建）： ```bash sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool ``` +增加已有仓位的流动性： + ```bash sun liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000 ``` +移除已有仓位的流动性： + ```bash sun liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT ``` +领取累积的手续费奖励： + ```bash sun liquidity v4:collect --token-id 123 ``` +查询仓位信息： + ```bash sun liquidity v4:info --pm --token-id 123 ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md index 81411e6..2a7265c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/FAQ.md @@ -130,4 +130,4 @@ export TRON_RPC_URL=https://your-tron-rpc.example ## 还有其他问题？ -如果这里没有覆盖你的问题，查看 [命令指南](./CommandGuide.md) 了解详细用法，或在 [GitHub 仓库](https://github.com/nicholaskarlson/sun-cli) 提交 Issue。 +如果这里没有覆盖你的问题，查看 [命令指南](./CommandGuide.md) 了解详细用法，或在 [GitHub 仓库](https://github.com/BofAI/sun-cli) 提交 Issue。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md index a97d480..5217ef4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/Intro.md @@ -43,7 +43,7 @@ SUN CLI 覆盖了与 SunSwap DEX 交互的完整操作，从实时行情数据 | 能力 | 描述 | 示例命令 | | :--- | :--- | :--- | | **代币兑换** | 通过 Universal Router 执行最优路径兑换 | `sun swap TRX USDT 1000000` | -| **V2 流动性** | 向 V2 池添加/移除流动性 | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b 290000` | +| **V2 流动性** | 创建流动性池或向 V2 池添加/移除流动性 | `sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000` | | **V3 流动性** | 铸造、增加、减少集中流动性仓位，收取手续费 | `sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000` | | **V4 流动性** | V4 集中流动性操作，支持 Permit2 授权 | `sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000` | | **合约交互** | 读取或写入任意 TRON 智能合约 | `sun contract read
balanceOf --args '[...]'` | From 0712c70f0557865188b21c717c4446daf32541ee Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 7 Apr 2026 17:20:22 +0800 Subject: [PATCH 05/33] add suncli --- .../MCP/SUNCli/CommandGuide.md | 671 +++++++++++++++--- docs/McpServer-Skills/MCP/SUNCli/Intro.md | 2 +- .../MCP/SUNCli/CommandGuide.md | 669 ++++++++++++++--- .../McpServer-Skills/MCP/SUNCli/Intro.md | 2 +- 4 files changed, 1123 insertions(+), 221 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md index 24b9881..a4dd6e3 100644 --- a/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md +++ b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md @@ -1,6 +1,9 @@ # Command Guide -This page is the complete reference for all SUN CLI commands. Commands are organized by category: wallet management, market data, trading, liquidity, protocol analytics, and contract interaction. +This page is the complete reference for all SUN CLI commands. Commands are organized by category: wallet management, price, token, swap, pool, liquidity, position, pair, farm, protocol, transaction, and contract. + +> Legend: `` = required argument, `[arg]` = optional argument. +> Options marked with **(required)** must be provided. All others are optional. --- @@ -36,6 +39,10 @@ sun --output tsv pool top-apy --page-size 10 sun --fields address,network wallet address ``` +```bash +sun -p your_agent_wallet_password wallet address +``` + ```bash sun -k your_private_key --network nile --yes swap TRX USDT 1000000 ``` @@ -48,59 +55,42 @@ sun --dry-run contract send TContract transfer --args '["TRecipient","1000000"]' ## Wallet & Portfolio -Inspect the active wallet and on-chain balances. +### `wallet address` (read) -### `wallet address` - -Display the configured wallet address and current network. +Print the active wallet address. ```bash sun wallet address ``` -### `wallet balances` - -Query token balances for the active wallet or any address. - -```bash -sun wallet balances -``` - -```bash -sun wallet balances --owner TYourAddress --tokens TRX,TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t -``` - -### `position list` +### `wallet balances` (read) -View SunSwap liquidity positions for an address. +Fetch wallet token balances. ```bash -sun position list --owner TYourAddress +sun wallet balances [options] ``` -### `position tick` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--owner
` | Wallet address to query | Active wallet | +| `--tokens ` | Comma-separated token list: `TRX,,...` | `TRX` | -Query tick data for a specific pool. +--- -```bash -sun position tick -``` +## Price -### `farm positions` +### `price [token]` (read) -View yield farm positions. +Get token prices from SUN.IO. Accepts a built-in symbol or address. ```bash -sun farm positions --owner TYourAddress +sun price [token] [options] ``` ---- - -## Price & Discovery - -### `price` - -Query real-time token prices on SunSwap. +| Option | Description | Default | +| :--- | :--- | :--- | +| `--address ` | Comma-separated token contract addresses | — | ```bash sun price TRX @@ -114,121 +104,226 @@ sun price USDT sun price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t ``` -### `token list` +--- + +## Token -List tokens by protocol version. +### `token list` (read) + +Fetch tokens by address or protocol. ```bash -sun token list --protocol V3 +sun token list [options] ``` -### `token search` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--address ` | Filter by token contract address | — | +| `--protocol ` | Protocol filter (V2, V3, V4) | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | +| `--sort ` | Sort field | — | +| `--no-blacklist` | Include blacklisted tokens | `false` | + +### `token search ` (read) -Search for tokens by name or symbol. +Fuzzy search for tokens by name or symbol. ```bash -sun token search USDT +sun token search [options] ``` -### `pool list` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +--- -List pools filtered by token. +## Swap + +### `swap ` (write) + +Execute a token swap via SunSwap Universal Router. ```bash -sun pool list --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +sun swap [options] ``` -### `pool search` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--slippage ` | Slippage tolerance as decimal (e.g. 0.005 = 0.5%) | `0.005` | -Search for pools by token pair. +```bash +sun swap TRX USDT 1000000 +``` ```bash -sun pool search "TRX USDT" +sun swap TRX USDT 1000000 --slippage 0.01 ``` -### `pool top-apy` +### `swap:quote ` (read) -List pools ranked by APY. +Get a swap quote without executing. ```bash -sun pool top-apy --page-size 10 +sun swap:quote [options] ``` -### `pool hooks` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--all` | Show all available routes | `false` | -List pools with hooks enabled. +```bash +sun swap:quote TRX USDT 1000000 +``` ```bash -sun pool hooks +sun swap:quote TRX USDT 1000000 --all ``` -### `pair info` +### `swap:quote-raw` (read) -Get pair-level information for a token. +Low-level router quote call. ```bash -sun pair info --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +sun swap:quote-raw [options] ``` -### `farm list` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--router
` | **(required)** Smart router contract address | — | +| `--fn ` | Quote function name | `quoteExactInput` | +| `--args ` | **(required)** Arguments as JSON array | — | +| `--abi ` | Router ABI as JSON array | — | + +### `swap:exact-input` (write) -List available yield farms. +Low-level router swap execution. ```bash -sun farm list +sun swap:exact-input [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--router
` | **(required)** Smart router contract address | — | +| `--fn ` | Swap function name | `swapExactInput` | +| `--args ` | **(required)** Arguments as JSON array | — | +| `--value ` | TRX call value in Sun | — | +| `--abi ` | Router ABI as JSON array | — | + --- -## Swap +## Pool -### `swap` +### `pool list` (read) -Execute a token swap via the optimal route. Requires a configured wallet. +List pools with filters. ```bash -sun swap TRX USDT 1000000 --slippage 0.005 +sun pool list [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--address ` | Filter by pool address | — | +| `--token ` | Filter by token (symbol or address) | — | +| `--protocol ` | Protocol filter (V2, V3, V4) | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | +| `--sort ` | Sort field | — | +| `--no-blacklist` | Include blacklisted pools | `false` | + +### `pool search ` (read) + +Search pools by keyword. + ```bash -sun -k your_private_key --network nile --yes swap TRX USDT 1000000 +sun pool search [options] ``` -Successful responses include `txid`, route details, and a `tronscanUrl` link. +| Option | Description | Default | +| :--- | :--- | :--- | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | -### `swap:quote` +### `pool top-apy` (read) -Get a read-only swap quote without executing. No wallet needed. +List top APY pools. ```bash -sun swap:quote TRX USDT 1000000 +sun pool top-apy [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +### `pool hooks` (read) + +List registered pool hooks. + ```bash -sun swap:quote TRX USDT 1000000 --all +sun pool hooks ``` -### `swap:quote-raw` +### `pool vol-history ` (read) -Low-level router quote with raw arguments. +Pool volume history over a date range. ```bash -sun swap:quote-raw --router --args '[...]' +sun pool vol-history [options] ``` -### `swap:exact-input` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--start ` | Start date (YYYY-MM-DD) | — | +| `--end ` | End date (YYYY-MM-DD) | — | + +### `pool liq-history ` (read) -Low-level exact-input swap via a specific router. +Pool liquidity history over a date range. ```bash -sun swap:exact-input --router --args '[...]' --value 1000000 +sun pool liq-history [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--start ` | Start date (YYYY-MM-DD) | — | +| `--end ` | End date (YYYY-MM-DD) | — | + --- ## Liquidity -### V2 +### `liquidity v2:add` (write) + +Add V2 liquidity. Router address is auto-detected by network. + +```bash +sun liquidity v2:add [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-a ` | **(required)** Token A (symbol or address) | — | +| `--token-b ` | **(required)** Token B (symbol or address) | — | +| `--amount-a ` | Amount of token A (raw units) | — | +| `--amount-b ` | Amount of token B (raw units) | — | +| `--min-a ` | Minimum amount A | — | +| `--min-b ` | Minimum amount B | — | +| `--router
` | V2 router address | Auto by network | +| `--to
` | LP token recipient | Active wallet | +| `--deadline ` | Transaction deadline | — | +| `--abi ` | Custom router ABI | — | + +> Provide at least one of `--amount-a` or `--amount-b`. When only one is given, the other is auto-calculated from pool reserves. Create a new liquidity pool (both token amounts required): @@ -239,68 +334,246 @@ sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 --amount-b Add liquidity to an existing pool (the other token amount is calculated automatically): ```bash -sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000 +sun liquidity v2:add --token-a TRX --token-b USDT --amount0 1000000 ``` -Remove liquidity: +### `liquidity v2:remove` (write) + +Remove V2 liquidity. + +```bash +sun liquidity v2:remove [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-a ` | **(required)** Token A | — | +| `--token-b ` | **(required)** Token B | — | +| `--liquidity ` | **(required)** LP token amount to remove | — | +| `--min-a ` | Minimum amount A | — | +| `--min-b ` | Minimum amount B | — | +| `--router
` | V2 router address | Auto by network | +| `--to
` | Token recipient | Active wallet | +| `--deadline ` | Transaction deadline | — | +| `--abi ` | Custom router ABI | — | ```bash sun liquidity v2:remove --token-a TRX --token-b USDT --liquidity 500000 ``` -### V3 +### `liquidity v3:mint` (write) -Mint a new concentrated liquidity position: +Mint a new V3 concentrated liquidity position. Position Manager is auto-detected by network. + +```bash +sun liquidity v3:mint [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token0 ` | **(required)** Token 0 (symbol or address) | — | +| `--token1 ` | **(required)** Token 1 (symbol or address) | — | +| `--fee ` | Pool fee tier | `3000` | +| `--tick-lower ` | Lower tick boundary | Auto | +| `--tick-upper ` | Upper tick boundary | Auto | +| `--amount0 ` | Amount of token 0 | — | +| `--amount1 ` | Amount of token 1 | — | +| `--min0 ` | Minimum amount 0 | — | +| `--min1 ` | Minimum amount 1 | — | +| `--pm
` | Position Manager address | Auto by network | +| `--recipient
` | NFT recipient | Active wallet | +| `--deadline ` | Transaction deadline | — | +| `--abi ` | Custom ABI | — | + +> Provide at least one of `--amount0` or `--amount1`. When only one is given, the other is auto-calculated. TRX is automatically converted to WTRX for V3 pool lookup. ```bash sun liquidity v3:mint --token0 TRX --token1 USDT --amount0 1000000 ``` -Increase liquidity of an existing position: +### `liquidity v3:increase` (write) + +Increase liquidity on an existing V3 position. + +```bash +sun liquidity v3:increase [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--amount0 ` | Amount of token 0 | — | +| `--amount1 ` | Amount of token 1 | — | +| `--min0 ` | Minimum amount 0 | — | +| `--min1 ` | Minimum amount 1 | — | +| `--token0 ` | Token 0 (needed for single-sided auto-compute) | — | +| `--token1 ` | Token 1 (needed for single-sided auto-compute) | — | +| `--fee ` | Pool fee (needed for single-sided auto-compute) | `3000` | +| `--pm
` | Position Manager address | Auto by network | +| `--deadline ` | Transaction deadline | — | +| `--abi ` | Custom ABI | — | + +> When providing only one amount, `--token0`, `--token1`, and `--fee` are required for auto-calculation. ```bash sun liquidity v3:increase --token-id 123 --amount0 500000 ``` -Decrease liquidity of an existing position: +### `liquidity v3:decrease` (write) + +Decrease liquidity on an existing V3 position. + +```bash +sun liquidity v3:decrease [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--liquidity ` | **(required)** Liquidity amount to remove | — | +| `--min0 ` | Minimum amount 0 | — | +| `--min1 ` | Minimum amount 1 | — | +| `--pm
` | Position Manager address | Auto by network | +| `--deadline ` | Transaction deadline | — | +| `--abi ` | Custom ABI | — | ```bash sun liquidity v3:decrease --token-id 123 --liquidity 1000 ``` -Collect accrued fees: +### `liquidity v3:collect` (write) + +Collect accumulated fees from a V3 position. + +```bash +sun liquidity v3:collect [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--recipient
` | Fee recipient | Active wallet | +| `--pm
` | Position Manager address | Auto by network | +| `--abi ` | Custom ABI | — | ```bash sun liquidity v3:collect --token-id 123 ``` -### V4 +### `liquidity v4:mint` (write) + +Mint a new V4 concentrated liquidity position. + +```bash +sun liquidity v4:mint [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token0 ` | **(required)** Token 0 | — | +| `--token1 ` | **(required)** Token 1 | — | +| `--fee ` | Pool fee tier | — | +| `--tick-lower ` | Lower tick boundary | Auto | +| `--tick-upper ` | Upper tick boundary | Auto | +| `--amount0 ` | Amount of token 0 | — | +| `--amount1 ` | Amount of token 1 | — | +| `--slippage ` | Slippage tolerance | — | +| `--sqrt-price ` | Initial sqrtPriceX96 (for pool creation) | — | +| `--create-pool` | Create the pool if it doesn't exist | `false` | +| `--recipient
` | NFT recipient | Active wallet | +| `--deadline ` | Transaction deadline | — | + +In an existing pool: + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 +``` -Mint a new concentrated liquidity position (`--create-pool` creates the pool automatically if it does not exist): +Create pool if it does not exist: ```bash sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool ``` -Increase liquidity of an existing position: +### `liquidity v4:increase` (write) + +Increase liquidity on an existing V4 position. + +```bash +sun liquidity v4:increase [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--token0 ` | **(required)** Token 0 | — | +| `--token1 ` | **(required)** Token 1 | — | +| `--fee ` | Pool fee tier | — | +| `--amount0 ` | Amount of token 0 | — | +| `--amount1 ` | Amount of token 1 | — | +| `--slippage ` | Slippage tolerance | — | +| `--deadline ` | Transaction deadline | — | ```bash sun liquidity v4:increase --token-id 123 --token0 TRX --token1 USDT --amount0 500000 ``` -Decrease liquidity of an existing position: +### `liquidity v4:decrease` (write) + +Decrease liquidity on an existing V4 position. + +```bash +sun liquidity v4:decrease [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--liquidity ` | **(required)** Liquidity amount to remove | — | +| `--token0 ` | **(required)** Token 0 | — | +| `--token1 ` | **(required)** Token 1 | — | +| `--fee ` | Pool fee tier | — | +| `--min0 ` | Minimum amount 0 | — | +| `--min1 ` | Minimum amount 1 | — | +| `--slippage ` | Slippage tolerance | — | +| `--deadline ` | Transaction deadline | — | ```bash sun liquidity v4:decrease --token-id 123 --liquidity 1000 --token0 TRX --token1 USDT ``` -Collect accrued fees: +### `liquidity v4:collect` (write) + +Collect accumulated fees from a V4 position. + +```bash +sun liquidity v4:collect [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token-id ` | **(required)** Position NFT token ID | — | +| `--token0 ` | Token 0 | — | +| `--token1 ` | Token 1 | — | +| `--fee ` | Pool fee tier | — | +| `--deadline ` | Transaction deadline | — | ```bash sun liquidity v4:collect --token-id 123 ``` -Query position info: +### `liquidity v4:info` (read) + +Get details about a V4 position. + +```bash +sun liquidity v4:info [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--pm
` | **(required)** Position Manager address | — | +| `--token-id ` | **(required)** Position NFT token ID | — | ```bash sun liquidity v4:info --pm --token-id 123 @@ -308,69 +581,244 @@ sun liquidity v4:info --pm --token-id 123 --- -## Protocol & History +## Position + +### `position list` (read) -### Protocol Analytics +List liquidity positions. ```bash -sun protocol info +sun position list [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--owner
` | Owner wallet address | — | +| `--pool ` | Filter by pool | — | +| `--protocol ` | Protocol filter (V2, V3, V4) | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +### `position tick ` (read) + +Get tick data for a pool. + ```bash -sun protocol vol-history --start 2026-01-01 --end 2026-03-01 +sun position tick [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +--- + +## Pair + +### `pair info` (read) + +Get token pair information. + ```bash -sun protocol users-history --start 2026-01-01 --end 2026-03-01 +sun pair info [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--token ` | Token contract address | — | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +--- + +## Farm + +### `farm list` (read) + +List farming pools. + ```bash -sun protocol tx-history --start 2026-01-01 --end 2026-03-01 +sun farm list [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--farm ` | Filter by farm address | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +### `farm tx` (read) + +List farming transaction history. + ```bash -sun protocol pools-history --start 2026-01-01 --end 2026-03-01 +sun farm tx [options] ``` +| Option | Description | Default | +| :--- | :--- | :--- | +| `--owner
` | Owner address | — | +| `--farm ` | Filter by farm | — | +| `--type ` | Transaction type | — | +| `--start