diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index 661627b6..6dbb65f8 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -24,6 +24,16 @@ The system walks you through choosing a wallet type, generating keys, and settin The interactive wizard may offer a `raw_secret` option. This type stores your private key **unencrypted** on disk — any program with file system access can read it directly. Only use `raw_secret` in fully isolated test environments. For any wallet holding real funds, always choose `local_secure`. ::: +:::tip Privy wallet type +The wizard also offers a `privy` option for Privy-managed server wallets. This type delegates key custody to Privy's infrastructure — no local private key is stored on disk. You'll need a Privy App ID, App Secret, and Wallet ID to configure it: + +```bash +agent-wallet start # then choose "privy" when prompted +``` + +The default wallet ID for Privy wallets is `default_privy`. +::: + **Custom password:** ```bash agent-wallet start -p Abc12345! @@ -59,11 +69,13 @@ When signing with a `local_secure` wallet, the CLI will prompt for the master pa **Sign a message:** ```bash agent-wallet sign msg "Hello" -n tron +# Output: Signature: d220de880cbc1c3f... ``` **Sign a transaction** (build the unsigned tx via RPC first): ```bash agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron +# Output: Signed tx: { "txID": "abc123...", "signature": ["..."], ... } ``` **Sign EIP-712 typed data:** @@ -81,6 +93,30 @@ agent-wallet sign typed-data '{ --- +### `agent-wallet init` (Initialize Secrets Directory) + +Initialize the secrets directory and set the master password — without creating a wallet yet. This is useful for advanced scenarios where you want to prepare the directory before adding wallets. + +```bash +agent-wallet init +``` + +**Non-interactive mode:** +```bash +agent-wallet init -p 'Abc12345!' +``` + +| Flag | Description | +| :--- | :--- | +| `--password, -p ` | Master password (skip prompt) | +| `--save-runtime-secrets` | Persist password to `runtime_secrets.json` | + +:::tip When to use `init` vs `start` +`start` = `init` + create a wallet in one step. If you just need to set up the directory and password first (e.g., for a CI pipeline or when importing keys later), use `init` alone. +::: + +--- + ## Wallet Management Manage multiple wallets — add, switch, inspect, remove. @@ -105,6 +141,15 @@ agent-wallet use my-bsc-wallet agent-wallet inspect my-bsc-wallet ``` +Show wallet metadata along with derived addresses: +```bash +agent-wallet inspect my-bsc-wallet --show-address +``` + +| Flag | Description | +| :--- | :--- | +| `--show-address` | Derive and display EVM + TRON addresses (requires password for `local_secure` wallets) | + **Sign with a specific wallet** (without switching the active one): ```bash agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!' @@ -115,6 +160,34 @@ agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!' agent-wallet remove my-bsc-wallet ``` +| Flag | Short | Description | +| :--- | :--- | :--- | +| `--yes` | `-y` | Skip confirmation prompt (**required in non-interactive / agent contexts**) | + +### `agent-wallet resolve-address` (Resolve Wallet Addresses) + +Display the on-chain addresses associated with a wallet. For wallets derived from a mnemonic, this shows addresses for all supported networks (EVM and TRON). For private-key-based wallets, it shows the single address for the configured network. + +```bash +agent-wallet resolve-address my-wallet +``` + +If you omit the wallet ID, the CLI will present an interactive list to choose from: + +```bash +agent-wallet resolve-address +``` + +Example output: +``` + Wallet │ my-wallet + Type │ local_secure + +Addresses + EVM │ 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 + TRON │ TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC +``` + --- ## Non-Interactive Execution (For Automation & Background Services) @@ -227,10 +300,26 @@ agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet After changing, **all key files are re-encrypted with the new password**. The old password becomes invalid immediately — make sure to update your password manager. +**Interactive mode (default):** ```bash agent-wallet change-password ``` +**Non-interactive mode** (for automation scripts): +```bash +agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!' +``` + +| Flag | Description | +| :--- | :--- | +| `--password, -p ` | Current master password (skip prompt) | +| `--new-password ` | New master password (skip prompt) | +| `--save-runtime-secrets` | Update cached password in `runtime_secrets.json` | + +:::caution +Both `-p` and `--new-password` will be recorded in shell history. For production use, prefer interactive mode or pipe passwords from a secrets manager. +::: + ### `agent-wallet reset` (Reset All Data) Deletes everything under `~/.agent-wallet/`. **This is a nuclear option — once executed, all wallets, keys, and configuration are gone, with no recovery.** The system will ask for confirmation. diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index 601753ef..5681424d 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -560,6 +560,24 @@ The x402 SDK automatically constructs the PaymentPermit data and calls the signi --- +## More Examples + +The Agent-wallet repository includes additional ready-to-run examples covering more advanced scenarios: + +| Example | Description | +| :--- | :--- | +| `dual-sign-typed-data-from-private-key` | Sign EIP-712 typed data on both TRON and EVM from a single private key | +| `switch-active-wallet` | Programmatically switch between multiple wallets | +| `create-wallet-provider` | Direct provider instantiation without auto-resolution | +| `tron-x402-sign-typed-data` | x402 PaymentPermit signing on TRON | +| `bsc-x402-sign-typed-data` | x402 PaymentPermit signing on BSC | +| `verify-tron-privy-typed-data` | Verify Privy TRON EIP-712 signatures | +| `compare-sign-consistency` | Cross-wallet signature consistency testing | + +Browse the full set in the [TypeScript examples](https://github.com/BofAI/agent-wallet/tree/main/packages/typescript/examples) and [Python examples](https://github.com/BofAI/agent-wallet/tree/main/packages/python/examples) directories. + +--- + ## Next Steps - Prefer the command line? → [CLI Reference](./CLI-Reference.md) diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md index 1ccdd993..0358ad39 100644 --- a/docs/Agent-Wallet/Developer/SDK-Guide.md +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -22,13 +22,13 @@ Both installation instructions and code examples are provided for TypeScript and **Check Your Node.js Version** -Requires Node.js ≥ 18. Check your current version: +Requires Node.js ≥ 20. Check your current version: ```bash node -v ``` -If the output is `v18.0.0` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. +If the output is `v20.0.0` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. :::tip Install / Upgrade Node.js @@ -41,9 +41,9 @@ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # Reload shell config source ~/.bashrc # or source ~/.zshrc -# Install and switch to Node.js 18 LTS -nvm install 18 -nvm use 18 +# Install and switch to Node.js 20 LTS +nvm install 20 +nvm use 20 ``` You can also download the **LTS** installer directly from [nodejs.org](https://nodejs.org). @@ -513,12 +513,16 @@ Error type hierarchy: ``` WalletError -├── WalletNotFoundError # Specified wallet not found -├── DecryptionError # Wrong password or corrupted key file -├── SigningError # Signing operation failed -├── NetworkError # Network identifier mismatch -├── InsufficientBalanceError # Insufficient balance -└── UnsupportedOperationError # Operation not supported by this wallet type +├── WalletNotFoundError # Specified wallet not found +├── DecryptionError # Wrong password or corrupted key file +├── SigningError # Signing operation failed +├── NetworkError # Network identifier mismatch +├── InsufficientBalanceError # Insufficient balance +├── UnsupportedOperationError # Operation not supported by this wallet type +├── PrivyConfigError # Privy wallet configuration error +├── PrivyRequestError # Privy API request failed +├── PrivyRateLimitError # Privy API rate limit exceeded +└── PrivyAuthError # Privy authentication failed ``` :::tip About InsufficientBalanceError diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index 44306967..41a17965 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -68,18 +68,23 @@ No limit. You can create separate wallets for different AI agents, different cha ## Wallet Types -### What's the difference between `local_secure` and `raw_secret`? +### What's the difference between `local_secure`, `raw_secret`, and `privy`? -| | `local_secure` | `raw_secret` | -| :--- | :---: | :---: | -| **Key encryption** | ✅ Strong encryption | ❌ Plaintext | -| **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly | -| **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev environments only | +| | `local_secure` | `raw_secret` | `privy` | +| :--- | :---: | :---: | :---: | +| **Key storage** | ✅ Encrypted locally | ❌ Plaintext locally | ☁️ Privy cloud custody | +| **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly | ✅ No local key file | +| **Requires master password** | ✅ Yes | ❌ No | ❌ No (uses API credentials) | +| **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev only | ✅ Server-side agents with Privy | :::danger `raw_secret` exposes your private key as plaintext `raw_secret` stores your key unencrypted — the exact exposure `local_secure` mode is designed to prevent. If any other process on your machine can read files, your key can be stolen instantly. **Always use `local_secure`** unless you're 100% certain no other agent is running on that machine and it's a fully isolated, offline test environment. ::: +:::tip Privy wallets +The `privy` type delegates key custody to [Privy](https://privy.io)'s server-side wallet infrastructure. No private key is stored on your local disk — signing requests are sent to Privy's API. This is ideal for server-side AI agents that already use Privy for wallet management. You'll need a Privy App ID, App Secret, and Wallet ID to set it up. +::: + ### What values does the `network` parameter accept? | Value | Description | @@ -136,7 +141,7 @@ Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), th ### What operating systems are supported? -macOS and Linux. As long as you can run Node.js >= 18 or Python >= 3.11, you're good to go. Windows is not currently supported. +macOS, Linux, and Windows. As long as you can run Node.js >= 20 or Python >= 3.11, you're good to go. Windows support was added in v2.3.x — file permission features (like `chmod 600`) are gracefully skipped on Windows since it doesn't support Unix-style permissions. ### `npm install -g` gives a permission error? diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index ee00767f..1a92242e 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -15,7 +15,7 @@ This page only walks you through the shortest path. For password-free configurat ### 1.1 Prepare Your Environment: Install Node.js -Agent-wallet requires Node.js (a runtime environment, version >= 18) on your computer. +Agent-wallet requires Node.js (a runtime environment, version >= 20) on your computer. Open a terminal (Mac users press `Command + Space` and search for "Terminal"), then type: @@ -23,7 +23,7 @@ Open a terminal (Mac users press `Command + Space` and search for "Terminal"), t node -v ``` -- **If the output shows `v18.x.x` or higher:** Great, skip straight to 1.2! +- **If the output shows `v20.x.x` or higher:** Great, skip straight to 1.2! - **If there's no output or an error:** Don't panic — go to the **[Node.js official website](https://nodejs.org)** and download the latest **LTS** installer. Install it like any regular software — double-click and follow the prompts. After installation, close and reopen your terminal, then run `node -v` again to confirm.
@@ -36,8 +36,8 @@ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 2. Reload your terminal config source ~/.bashrc # zsh users: source ~/.zshrc -# 3. Install and switch to Node.js 18 -nvm install 18 && nvm use 18 +# 3. Install and switch to Node.js 20 +nvm install 20 && nvm use 20 ```
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 42d75768..6494e046 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -85,19 +85,12 @@ This page collects frequently asked questions when using SUN MCP Server and thei **Solution:** -1. **Configure [Agent Wallet](../../../Agent-Wallet/Intro)** (recommended) — set `AGENT_WALLET_PASSWORD` - -2. **Or Configure Private Key (Testnet Only)** +1. **Configure [Agent Wallet](../../../Agent-Wallet/Intro.md)** — set `AGENT_WALLET_PASSWORD` ```bash - export TRON_PRIVATE_KEY="your_64_hex_char_private_key" + export AGENT_WALLET_PASSWORD='your_password' ``` -3. **Or Configure Mnemonic** - ```bash - export TRON_MNEMONIC="word1 word2 ... word12" - ``` - -4. **Restart server** and reconnect MCP client +2. **Restart server** and reconnect MCP client Verify successful configuration by checking [Full Capability List](ToolList.md) for Full Capability List. @@ -135,46 +128,30 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **Verify password is set**: Run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` to confirm the variable is set without revealing the value. 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. -3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. +3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ.md) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. -### "Conflicting Wallet Modes" +### "Wallet Not Found" or Initialization Error -**Symptom:** Error "Conflicting wallet modes detected". +**Symptom:** Server cannot find or initialize wallet. -**Cause:** Multiple wallet environment variables set simultaneously. +**Cause:** Agent Wallet not properly configured. -**Solution:** Set only one of the following: +**Solution:** Ensure Agent Wallet is installed and configured: ```bash -# Option 1: Agent Wallet (recommended for production) +# Set Agent Wallet password export AGENT_WALLET_PASSWORD='your_password' -unset TRON_PRIVATE_KEY -unset TRON_MNEMONIC - -# Option 2: Private Key (testnet only) -export TRON_PRIVATE_KEY='your_64_hex_chars' -unset AGENT_WALLET_PASSWORD -unset TRON_MNEMONIC - -# Option 3: Mnemonic -export TRON_MNEMONIC='word1 word2 ... word12' -unset AGENT_WALLET_PASSWORD -unset TRON_PRIVATE_KEY -``` -**Verify Configuration:** -```bash -# Clear all wallet-related environment variables -unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC - -# Set only one -export AGENT_WALLET_PASSWORD='your_password' +# Optional: specify custom wallet directory +export AGENT_WALLET_DIR="$HOME/.agent-wallet" # Restart server sun-mcp-server ``` +If you haven't initialized Agent Wallet yet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md) for setup instructions. + ## DeFi Operation Errors ### "Swap Failed" @@ -271,7 +248,7 @@ sun-mcp-server - Check Permit2 request structured data - Confirm chain ID, token address, deadline correct -3. **Reinitialize Wallet** — run `agent-wallet reset` to wipe and start over. See [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) for details. +3. **Reinitialize Wallet** — run `agent-wallet reset` to wipe and start over. See [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data) for details. 4. **Use Alternate Authorization Method** ``` @@ -414,7 +391,7 @@ Check transaction hash details on https://tronscan.org for error message "args": ["--port", "8081"], "env": { "TRON_NETWORK": "nile", - "TRON_PRIVATE_KEY": "your_testnet_private_key" + "AGENT_WALLET_PASSWORD": "your_testnet_password" } } } diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index d93472e7..fef556dc 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -44,66 +44,61 @@ Without wallet configuration, SUN MCP Server will run in **read-only mode**, all ## Installation Steps ### Step 1: Configure Wallet -The wallet determines which identity the AI assistant uses to perform on-chain operations. SUN MCP Server supports three wallet modes; if no wallet is configured, the server automatically runs in read-only mode. +The wallet determines which identity the AI assistant uses to perform on-chain operations. SUN MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for secure wallet management. If no wallet is configured, the server automatically runs in read-only mode. -#### There are three wallet options — choose based on your needs +#### Agent Wallet -| Feature | Agent Wallet | Private Key | Mnemonic | -| :--- | :--- | :--- | :--- | -| Security Level | High (encrypted storage) | Low (plaintext) | Low (plaintext) | -| Multi-Wallet Support | Yes | No | No | -| Runtime Wallet Switching | Yes | No | No | -| Setup Complexity | Medium | Simple | Simple | -| Recommended For | Production, significant funds | Development, small amounts | Development, small amounts | +SUN MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for wallet management. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. -#### Option 1: Agent Wallet (Recommended) +| Feature | Description | +| :--- | :--- | +| Security Level | High (encrypted storage) | +| Multi-Wallet Support | Yes | +| Runtime Wallet Switching | Yes | +| Recommended For | All use cases | -This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md). -> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). - -**Set environment variables after initializing Agent Wallet:** +First, install Agent Wallet: ```bash -# Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD='' - -# Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="$HOME/.agent-wallet" +npm install -g @bankofai/agent-wallet ``` +Then, choose one of the following two options depending on your situation: +#### Option A: Generate a New Wallet (Recommended for New Users) -#### Option 2: Private Key - -Provide the private key directly via environment variable. Simplest setup, but lower security. +If you don't have an existing private key, use `agent-wallet start` to generate a new wallet with an encrypted keystore and master password: ```bash -# Add to ~/.zshrc or ~/.bashrc -export TRON_PRIVATE_KEY="" +agent-wallet start ``` -The private key can be in hex format with or without the `0x` prefix. +Follow the interactive prompts to set your master password and generate a wallet. Once complete, the wallet is ready to use — **no additional environment variables are needed**. Agent Wallet will automatically manage the encrypted keystore. -:::warning -Using a plaintext private key in environment variables carries a **real risk of fund theft** — environment variables can be leaked via shell history, process listings (`ps aux`), or log files. **Only keep small amounts of funds** in wallets configured this way. -::: - -#### Option 3: Mnemonic Phrase +#### Option B: Import an Existing Private Key -Use a BIP-39 mnemonic phrase for HD wallet derivation. +If you already have a private key you want to use, set it via the `AGENT_WALLET_PRIVATE_KEY` environment variable: ```bash -# Add to ~/.zshrc or ~/.bashrc -export TRON_MNEMONIC="word1 word2 word3 ... word12" +export AGENT_WALLET_PRIVATE_KEY=your_private_key_here +``` -# Optional: specify HD wallet derivation index (default: 0) -# Derivation path: m/44'/195'/0'/0/{index} -export TRON_ACCOUNT_INDEX="0" +:::tip +To make this persist across terminal sessions, add it to your shell configuration file: + +```bash +echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default) +echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default) +source ~/.zshrc # or source ~/.bashrc — takes effect immediately without restarting the terminal ``` -:::warning -Same security risks as the private key option. Mnemonic phrases stored in plaintext are vulnerable to exposure. Use this only for development/testing wallets with small balances. +Verify the environment variable is set: + +```bash +echo $AGENT_WALLET_PRIVATE_KEY +``` ::: diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index e628182e..ae697473 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -47,49 +47,41 @@ When using HTTP mode (`npm run start:http`) and clients cannot connect, the usua 3. **Firewall blocking**. If you're accessing the local HTTP service from another machine, check whether the firewall allows inbound connections on that port. -### Only read tools in the tool list, no write tools +### Write tools appear but return "Wallet not configured" error -This is not an error — it's by design. Write tools (transfers, staking, etc.) are only registered into the AI's tool list after a wallet is configured. If you haven't set any wallet environment variables, the server automatically runs in read-only mode. +As of v1.1.7, write tools (transfers, staking, etc.) are always visible in the AI's tool list, but wallet availability is checked at execution time. If you call a write tool without a configured wallet, it will return an error prompting you to set up a wallet. -To unlock write tools, configure one of the three wallet modes: +To enable write operations, configure [Agent Wallet](../../../Agent-Wallet/Intro.md): -- Set `AGENT_WALLET_PASSWORD` ([Agent Wallet](../../../Agent-Wallet/Intro) mode, recommended) -- Set `TRON_PRIVATE_KEY` (Private Key mode) -- Set `TRON_MNEMONIC` (Mnemonic mode) +- Set `AGENT_WALLET_PASSWORD` environment variable with your master password +- Optionally set `AGENT_WALLET_DIR` if using a custom wallet directory After configuring, restart your AI client. For detailed instructions, see [Local Private Deployment](./LocalPrivatizedDeployment.md). +:::info +If you're connected via the official cloud service or using `--readonly` mode, write tools will not appear at all — this is expected behavior. +::: + --- ## Authentication & Key Issues -### "Invalid private key" error - -If the server reports an invalid private key at startup, it's usually a format issue: +### "Wallet not configured" error -1. **Check key format**. The private key should be a 64-character hex string, with or without the `0x` prefix: - ``` - # Valid formats: - abc123def456... (64 hex characters) - 0xabc123def456... (0x + 64 hex characters) - ``` +This means no wallet has been set up for signing transactions. TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for all wallet management. To resolve: -2. **Avoid extra spaces or quotes**. Environment variable values must not contain extra spaces, nested quotes, or newline characters: +1. **Install and initialize Agent Wallet** following the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md). +2. **Set the environment variable**: ```bash - # Correct - export TRON_PRIVATE_KEY=abc123def456... - - # Wrong (quotes become part of the value) - export TRON_PRIVATE_KEY="'abc123def456...'" + export AGENT_WALLET_PASSWORD='' ``` - -3. **Verify the key is valid**. Import the same private key into a TRON wallet (like TronLink) to confirm it works. +3. **Restart your AI client** for the changes to take effect. ### "Agent wallet password incorrect" error `AGENT_WALLET_PASSWORD` must exactly match the master password generated when you ran `agent-wallet start`. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. -If the password is lost, you'll need to re-initialize. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +If the password is lost, you'll need to re-initialize. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ.md) for details. ### TronGrid API Key not working @@ -209,3 +201,4 @@ npm run build ### What MCP protocol version is supported? TRON MCP Server supports MCP protocol version **2025-11-25**, using `@modelcontextprotocol/sdk` 1.22.0 or higher. + diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md index f79c1f28..2f0a0fc6 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -10,14 +10,14 @@ This means different things to different people: - If you are an **AI application user**, it lets you operate blockchain directly in MCP-compatible AI tools — as easy as everyday chat. - If you are a **Web3 developer**, it's your rapid on-chain prototyping tool — debug contracts and query state in natural language, saving vast amounts of boilerplate code. -- If you are an **AI Agent builder**, it provides 95 standardized on-chain tools that can be orchestrated directly into your automation workflows. +- If you are an **AI Agent builder**, it provides 97 standardized on-chain tools that can be orchestrated directly into your automation workflows. - If you are a **data analyst**, it turns on-chain data queries into conversation — no more writing scripts to scrape and parse. --- ## What Can It Do? -TRON MCP Server covers almost all common TRON blockchain operations, from read-only queries to asset management, providing **95 tools**, **6 prompt templates**, and **1 resource definition**. +TRON MCP Server covers almost all common TRON blockchain operations, from read-only queries to asset management, providing **97 tools**, **6 prompt templates**, and **1 resource definition**. Here is an overview of core capabilities — each one can be triggered via natural language: @@ -51,8 +51,8 @@ The core distinction comes down to one point: **whether you need to sign transac | Comparison Item | Official Cloud Service | Local Private Deployment | | :--- | :--- | :--- | | **Feature Scope** | Read-only (queries only) | Full features (read + write) | -| **Setup Difficulty** | Just add one config line | Requires local installation and build | -| **Private Key Required** | No | Yes (for write operations) | +| **Setup Difficulty** | Just add one config line | Requires Agent Wallet setup | +| **Wallet Required** | No | Yes (Agent Wallet for write operations) | | **Transfer/Contract Writing** | Not supported | Supported | | **Suitable For** | Quick queries, getting started | Development, debugging, automated trading | | **Security** | High (no private key exposure) | Depends on your key management | @@ -95,4 +95,4 @@ Before getting started, keep these security principles in mind — especially fo - Want the fastest way to get started? → [Quick Start](./QuickStart.md) - Only need to query on-chain data? → [Official Cloud Service Access](./OfficialServerAccess.md) - Need transfers, contract calls, and full functionality? → [Local Private Deployment](./LocalPrivatizedDeployment.md) -- Want to see all 95 tools? → [Full Capability List](./ToolList.md) +- Want to see all 97 tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 75375324..f1a59cfa 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -50,66 +50,61 @@ Before configuring your wallet, make sure to understand the following security p ## Installation Steps ### Step 1: Configure Wallet -The wallet determines which identity the AI assistant uses to perform on-chain operations. TRON MCP Server supports three wallet modes; if no wallet is configured, the server automatically runs in read-only mode. +The wallet determines which identity the AI assistant uses to perform on-chain operations. TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for secure wallet management. If no wallet is configured, write tools will return an error prompting you to set up a wallet. -#### There are three wallet options — choose based on your needs +#### Agent Wallet -| Feature | Agent Wallet | Private Key | Mnemonic | -| :--- | :--- | :--- | :--- | -| Security Level | High (encrypted storage) | Low (plaintext) | Low (plaintext) | -| Multi-Wallet Support | Yes | No | No | -| Runtime Wallet Switching | Yes | No | No | -| Setup Complexity | Medium | Simple | Simple | -| Recommended For | Production, significant funds | Development, small amounts | Development, small amounts | +TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for wallet management. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. -#### Option 1: Agent Wallet (Recommended) - -This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. +| Feature | Description | +| :--- | :--- | +| Security Level | High (encrypted storage) | +| Multi-Wallet Support | Yes | +| Runtime Wallet Switching | Yes | +| Recommended For | All use cases | -> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md). -**Set environment variables after initializing Agent Wallet:** +First, install Agent Wallet: ```bash -# Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD='' - -# Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="$HOME/.agent-wallet" +npm install -g @bankofai/agent-wallet ``` +Then, choose one of the following two paths depending on your situation: +#### Path 1: Generate a New Wallet (Recommended for New Users) -#### Option 2: Private Key - -Provide the private key directly via environment variable. Simplest setup, but lower security. +If you don't have an existing private key, use `agent-wallet start` to generate a new wallet with an encrypted keystore and master password: ```bash -# Add to ~/.zshrc or ~/.bashrc -export TRON_PRIVATE_KEY="" +agent-wallet start ``` -The private key can be in hex format with or without the `0x` prefix. - -:::warning -Using a plaintext private key in environment variables carries a **real risk of fund theft** — environment variables can be leaked via shell history, process listings (`ps aux`), or log files. **Only keep small amounts of funds** in wallets configured this way. -::: +Follow the interactive prompts to set your master password and generate a wallet. Once complete, the wallet is ready to use — **no additional environment variables are needed**. Agent Wallet will automatically manage the encrypted keystore. -#### Option 3: Mnemonic Phrase +#### Path 2: Import an Existing Private Key -Use a BIP-39 mnemonic phrase for HD wallet derivation. +If you already have a private key you want to use, set it via the `AGENT_WALLET_PRIVATE_KEY` environment variable: ```bash -# Add to ~/.zshrc or ~/.bashrc -export TRON_MNEMONIC="word1 word2 word3 ... word12" +export AGENT_WALLET_PRIVATE_KEY=your_private_key_here +``` + +:::tip +To make this persist across terminal sessions, add it to your shell configuration file: -# Optional: specify HD wallet derivation index (default: 0) -# Derivation path: m/44'/195'/0'/0/{index} -export TRON_ACCOUNT_INDEX="0" +```bash +echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default) +echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default) +source ~/.zshrc # or source ~/.bashrc — takes effect immediately without restarting the terminal ``` -:::warning -Same security risks as the private key option. Mnemonic phrases stored in plaintext are vulnerable to exposure. Use this only for development/testing wallets with small balances. +Verify the environment variable is set: + +```bash +echo $AGENT_WALLET_PRIVATE_KEY +``` ::: @@ -134,7 +129,7 @@ Register for free at [trongrid.io](https://www.trongrid.io/). The server still w ### Step 3: Local Private Deployment -Two options are available. For most users, Option A is sufficient. +Multiple deployment options are available. For most users, Option A is sufficient. #### Option A: Run directly with npx (Recommended) @@ -163,14 +158,52 @@ Start the server in HTTP mode, then connect your MCP client via the HTTP endpoin npm run start:http ``` -This will start a local HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. +This will start a local stateless Streamable HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. Each request is handled independently — no session state is maintained between requests. + +You can customize the port and host via environment variables: + +```bash +export MCP_PORT=3001 # default: 3001 +export MCP_HOST=0.0.0.0 # default: 0.0.0.0 +``` + +#### Option D: Docker Deployment + +Run TRON MCP Server in a Docker container for isolated, reproducible environments. The Docker image runs in **read-only HTTP mode** by default. + +```bash +# 1. Create a .env file for sensitive variables (never commit this file) +cat > .env.docker << 'EOF' +TRONGRID_API_KEY=your-key-here +EOF + +# 2. Build the image +docker build -t mcp-server-tron . + +# 3. Run the container with --env-file +docker run -d \ + -p 3001:3001 \ + -v $(pwd)/logs:/app/logs \ + --env-file .env.docker \ + mcp-server-tron +``` + +:::warning +Never pass API keys with `-e KEY=value` on the command line — the value will appear in shell history and `docker inspect` output. Always use `--env-file` with a file excluded from version control (add `.env.docker` to your `.gitignore`). +::: + +The container exposes port 3001 and writes date-stamped logs to the mounted `logs/` directory. A health check endpoint is available at `http://localhost:3001/health`. + +:::tip +The Docker image is designed for read-only cloud deployments. For local write operations (transfers, staking, etc.), use Option A, B, or C with a configured Agent Wallet. +::: #### Configuration Notes If you're configuring an MCP client to point to your local server: - **If running via npx or source**: Use the appropriate command in your MCP client's configuration (e.g., `command: npx` with `args: ["-y", "@bankofai/mcp-server-tron"]`) -- **If running in HTTP mode**: Point your client to `http://localhost:3001/mcp` via the HTTP URL configuration option +- **If running in HTTP mode or Docker**: Point your client to `http://localhost:3001/mcp` via the HTTP URL configuration option If your MCP client does not inherit system environment variables, you'll need to configure them explicitly in the client settings. **Make sure any configuration file storing credentials is never shared or committed to version control**. diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index ae00d6d4..18f0a6d4 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -169,4 +169,4 @@ For the Full Capability List, please refer to [Full Capability List](./ToolList. ## Next Steps - Need transfers, staking, or contract writes? → [Local Private Deployment](./LocalPrivatizedDeployment.md) -- Want the detailed description of all 95 tools? → [Full Capability List](./ToolList.md) +- Want the detailed description of all 97 tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index 75702bfe..b4b3b722 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -72,7 +72,7 @@ Once connected, try a few more prompts to get a feel for what TRON MCP Server ca | "Get the ABI of contract TXyz..." | Read a smart contract interface definition | | "Query the latest events triggered by contract TXyz..." | Get contract event logs | -These are just the tip of the iceberg. For the full list of 95 tools and 6 prompt templates, see [Full Capability List](./ToolList.md). +These are just the tip of the iceberg. For the full list of 97 tools and 6 prompt templates, see [Full Capability List](./ToolList.md). --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index f71eddb4..8f5b581a 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -1,6 +1,6 @@ # Full Capability List -TRON MCP Server provides **95 tools**, **6 prompts**, and **1 resource** for interacting with the TRON blockchain. Tools are the core capability — they are the actual functions the AI calls on your behalf. +TRON MCP Server provides **97 tools**, **6 prompts**, and **1 resource** for interacting with the TRON blockchain. Tools are the core capability — they are the actual functions the AI calls on your behalf. ## Understand Two Key Concepts First @@ -10,9 +10,9 @@ Before exploring the tool list, there are two important things you should know: Each tool is labeled with a **mode** — "read" or "write": - **Read tools**: Only query on-chain data and do not affect any state. They can be used in both cloud services and local deployments. -- **Write tools**: Modify blockchain state (e.g., transfers, staking, contract interactions). These are only available in local deployments with a configured wallet. +- **Write tools**: Modify blockchain state (e.g., transfers, staking, contract interactions). These require a configured wallet (via [Agent Wallet](../../../Agent-Wallet/Intro.md)) to execute. -If you have not configured a wallet, write tools will not appear in the AI’s available tool list — they are automatically hidden, so there’s no risk of triggering them by mistake. +Write tools are always visible in the AI’s tool list, but wallet availability is checked at execution time. If no wallet is configured, calling a write tool will return an error prompting you to set up a wallet. In **read-only mode** (cloud service or `--readonly` flag), write tools are not registered. ::: :::tip `network` parameter @@ -22,15 +22,15 @@ During testing, it is recommended to explicitly set `nile` each time to avoid un ::: --- -## Tools (95 total) +## Tools (97 total) ### Wallet & Address | Tool Name | Description | Key Parameters | Mode | | :--- | :--- | :--- | :--- | | `get_wallet_address` | Get the address (Base58 & Hex) of the currently configured wallet. | - | Read | -| `list_wallets` | List all available wallets with IDs and addresses ([Agent Wallet](../../../Agent-Wallet/Intro) mode). | - | Read | -| `select_wallet` | Switch the active wallet at runtime ([Agent Wallet](../../../Agent-Wallet/Intro) mode). | `walletId` | Write | +| `list_wallets` | List all available wallets with IDs and addresses ([Agent Wallet](../../../Agent-Wallet/Intro.md) mode). | - | Read | +| `select_wallet` | Switch the active wallet at runtime ([Agent Wallet](../../../Agent-Wallet/Intro.md) mode). | `walletId` | Write | | `sign_message` | Sign an arbitrary message using the configured wallet. | `message` | Write | | `convert_address` | Convert addresses between Hex (`41...`/`0x...`) and Base58 (`T...`) formats. | `address` | Read | diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 5ddbd385..98a0ab21 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -16,6 +16,7 @@ BANK OF AI SKILLS can operate on **real on-chain assets**. Blockchain transactio | Skill | What It Does | What Key/Credential Do I Need? | | :--- | :--- | :--- | +| **agent-wallet** | Create wallets, sign transactions/messages, manage multiple wallets — supports EVM and TRON | `AGENT_WALLET_PASSWORD` (encrypted mode) or none (interactive) | | **sunswap** | Check prices, get quotes, swap tokens, manage liquidity pools | Read-only: none. Trading: wallet credentials | | **sunperp-skill** | Market data, open/close positions, withdrawals | Market data: none. Trading: SunPerp API keys | | **tronscan-skill** | Look up accounts, transactions, tokens, blocks, network stats | Recommended: TronScan API key (may throttle without one) | @@ -62,6 +63,46 @@ Head over to **[Quick Start](./QuickStart.md)** — it takes about 1 minute. Com --- +## agent-wallet {#agent-wallet} + +Your AI's secure signing engine. This skill creates and manages encrypted wallets for your AI agent, letting it sign transactions and messages on both EVM (BSC, Ethereum, Polygon, etc.) and TRON networks — without ever exposing your private key. Think of it as the "keychain" that all other trading and payment skills rely on. + +**Completely safe — looking only, no spending:** + +> List all my agent wallets. + +> Show the EVM and TRON addresses for my wallet. + +> What wallet is currently active? + +**Requires your confirmation:** + +> Create a new encrypted wallet for me. + +> Switch to my BSC wallet. + +> Sign this message: "Hello World" on TRON mainnet. + +**Real-world scenarios:** + +> Setting up for the first time? Try: "Create a new agent wallet" — the AI walks you through choosing a wallet type, generating keys, and saving your master password. + +> Managing multiple chains? Try: "Show me all my wallets and their addresses" — one wallet derives both EVM and TRON addresses from the same key. + +> Need to sign something? Try: "Sign this transaction on BSC" — the AI handles the signing locally without broadcasting. + +:::tip Why use Agent Wallet instead of raw private keys? +Agent Wallet encrypts your private key with a master password. Even if someone accesses your files, they can't use the key without the master password. This is the recommended way to configure wallet credentials for all other skills (sunswap, x402-payment, etc.). +::: + +:::caution Dangerous operations are agent-restricted +`remove`, `reset`, and `change-password` cannot be executed by the AI — you must run these commands yourself in the terminal. This protects against accidental or irreversible loss of wallet access. +::: + +For detailed setup instructions, see [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md). + +--- + ## sunswap {#sunswap} Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. @@ -168,6 +209,21 @@ Need to check balances, transfer tokens, or manage approvals for any TRC20 token > Approve 100 USDT for spender TSpenderAddress. +**Advanced features:** + +> Check all my token balances at once: "Show my balances for USDT, USDD, SUN, JST, and BTT." (uses batch mode — invalid tokens won't abort the entire query) + +> Test before sending: "Do a dry-run transfer of 50 USDT to TXX...." (validates everything without broadcasting) + +> Fetch token metadata: "What are the name, symbol, decimals, and total supply of token TXX...?" + +**Safety built in:** + +- Self-transfers are automatically rejected +- Unlimited (MAX_UINT256) approvals are blocked — only exact amounts allowed +- Recipient and spender addresses are validated as proper TRON addresses +- Amounts must be greater than 0, even in dry-run mode + **Real-world scenarios:** > Quick portfolio check? Try: "Show my balances for USDT, USDD, SUN, JST, and BTT." @@ -206,10 +262,21 @@ Want to add multi-signature protection to your TRON account? This skill manages > Co-signing a pending proposal? Try: "Review all pending proposals and co-sign proposal prop_xxx." +**Key details:** + +- Proposals expire after **24 hours** by default — co-signers must approve within this window +- Active permission operations can be scoped to specific transaction types: TransferContract, TriggerSmartContract, FreezeBalanceV2Contract, DelegateResourceContract, VoteWitnessContract, and more +- Supports **hybrid signature workflows** — combine human approval keys with an agent signing key for co-signing +- Pending proposals are stored locally at `~/.clawdbot/multisig/pending/` and can be shared for distributed signing + :::tip Templates make it easy You don't need to configure every key and threshold manually. Built-in templates like `basic-2of3`, `agent-restricted`, `team-tiered`, and `weighted-authority` handle the common setups — just provide the key addresses. ::: +:::danger Lockout warning +Changing Owner permissions is **irreversible** without the new keys. The skill validates thresholds to prevent lockout, but always double-check key addresses before confirming Owner permission changes. +::: + --- ## x402-payment {#x402-payment} diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index ed090277..4df5b376 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -57,7 +57,15 @@ No. Skills use an **on-demand, lightweight architecture** — the AI only loads ## What Can Skills Do for You? -Seven core skills covering the most common scenarios in the TRON ecosystem. Each one comes with a ready-to-use sample prompt — copy it into your AI chat and hit enter to try it out. +Eight core skills covering the most common scenarios in the TRON ecosystem. Each one comes with a ready-to-use sample prompt — copy it into your AI chat and hit enter to try it out. + +### 🔑 Secure Wallet Management + +Create encrypted wallets, sign transactions and messages, manage multiple wallets — all without exposing your private key. This is the foundation that other trading and payment skills rely on. Supports both EVM (BSC, Ethereum, Polygon, etc.) and TRON networks. + +> 🗣️ "Create a new agent wallet for me" or "List all my wallets and show their addresses." + +💡 For setup and advanced usage, see: [**agent-wallet**](./BANKOFAISkill.md#agent-wallet) ### 💱 Execute DEX Trades diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 1b746eff..207209f9 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -47,10 +47,10 @@ Ok to proceed? (y) y The installer automatically fetches all available Skills from the repo and lists them for selection. Press **Space** to toggle each one — we recommend selecting all: ``` -◇ Found 7 skills +◇ Found 8 skills │ ◇ Select skills to install (space to toggle) -│ Multi-Sig & Account Permissions, recharge-skill, +│ agent-wallet, Multi-Sig & Account Permissions, recharge-skill, │ SunPerp Perpetual Futures Trading, SunSwap DEX Trading, │ TRC20 Token Toolkit, TronScan Data Lookup, x402-payment ``` @@ -84,18 +84,19 @@ Select `Project` (current project only) or `User` (globally available across all The installer runs a security scan on each Skill and shows the results. Review them and select `Yes` to proceed: ``` -◇ Security Risk Assessments ──────────────────────────────╮ -│ │ -│ Gen Socket Snyk │ -│ Multi-Sig & Account Permissions -- -- -- │ -│ recharge-skill -- -- -- │ -│ SunPerp Perpetual Futures Trading -- -- -- │ -│ SunSwap DEX Trading -- -- -- │ -│ TRC20 Token Toolkit -- -- -- │ -│ TronScan Data Lookup -- -- -- │ -│ x402-payment Med 1 alert Med │ -│ │ -├──────────────────────────────────────────────────────────╯ +◇ Security Risk Assessments ──────────────────────────────────────╮ +│ │ +│ Gen Socket Snyk │ +│ agent-wallet Med Risk 1 alert High Risk │ +│ Multi-Sig & Account Permissions -- -- -- │ +│ recharge-skill Safe 1 alert Med Risk │ +│ SunPerp Perpetual Futures Trading -- -- -- │ +│ SunSwap DEX Trading -- -- -- │ +│ TRC20 Token Toolkit -- -- -- │ +│ TronScan Data Lookup -- -- -- │ +│ x402-payment Safe 1 alert Med Risk │ +│ │ +├──────────────────────────────────────────────────────────────────╯ ◇ Proceed with installation? │ Yes @@ -106,8 +107,9 @@ The installer runs a security scan on each Skill and shows the results. Review t When you see output like this, all Skills have been successfully installed to your selected AI tools: ``` -◇ Installed 7 skills ────────────────────────╮ +◇ Installed 8 skills ────────────────────────╮ │ │ +│ ✓ agent-wallet (copied) │ │ ✓ Multi-Sig & Account Permissions (copied) │ │ ✓ recharge-skill (copied) │ │ ✓ SunPerp Perpetual Futures Trading (copied)│ diff --git a/docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md b/docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md new file mode 100644 index 00000000..d7441571 --- /dev/null +++ b/docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md @@ -0,0 +1,860 @@ +# Complete Capabilities + +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. + +--- + +## 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 | + +:::caution Private Key Security +The `-k` / `--private-key` and `-m` / `--mnemonic` flags pass sensitive +material as command-line arguments, which may be recorded in shell history +and process listings. Prefer environment variables (`AGENT_WALLET_PRIVATE_KEY`, +`AGENT_WALLET_MNEMONIC`) or [agent-wallet](https://github.com/BofAI/agent-wallet) +encrypted storage for all non-throwaway keys. +::: + +**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 -p your_agent_wallet_password 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 + +### `wallet address` (read) + +Print the active wallet address. + +```bash +sun wallet address +``` + +### `wallet balances` (read) + +Fetch wallet token balances. + +```bash +sun wallet balances [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--owner
` | Wallet address to query | Active wallet | +| `--tokens ` | Comma-separated token list: `TRX,,...` | `TRX` | + +--- + +## Price + +### `price [token]` (read) + +Get token prices from SUN.IO. Accepts a built-in symbol or address. + +```bash +sun price [token] [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--address ` | Comma-separated token contract addresses | — | + +```bash +sun price TRX +``` + +```bash +sun price USDT +``` + +```bash +sun price --address TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t +``` + +--- + +## Token + +### `token list` (read) + +Fetch tokens by address or protocol. + +```bash +sun token list [options] +``` + +| 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) + +Fuzzy search for tokens by name or symbol. + +```bash +sun token search [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +--- + +## Swap + +### `swap ` (write) + +Execute a token swap via SunSwap Universal Router. + +```bash +sun swap [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--slippage ` | Slippage tolerance as decimal (e.g. 0.005 = 0.5%) | `0.005` | + +```bash +sun swap TRX USDT 1000000 +``` + +```bash +sun swap TRX USDT 1000000 --slippage 0.01 +``` + +### `swap:quote ` (read) + +Get a swap quote without executing. + +```bash +sun swap:quote [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--all` | Show all available routes | `false` | + +```bash +sun swap:quote TRX USDT 1000000 +``` + +```bash +sun swap:quote TRX USDT 1000000 --all +``` + +### `swap:quote-raw` (read) + +Low-level router quote call. + +```bash +sun swap:quote-raw [options] +``` + +| 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) + +Low-level router swap execution. + +```bash +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 | — | + +--- + +## Pool + +### `pool list` (read) + +List pools with filters. + +```bash +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 pool search [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--protocol ` | Protocol filter | — | +| `--page ` | Page number | `1` | +| `--page-size ` | Page size | `20` | + +### `pool top-apy` (read) + +List top APY pools. + +```bash +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 pool hooks +``` + +### `pool vol-history ` (read) + +Pool volume history over a date range. + +```bash +sun pool vol-history [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--start ` | Start date (YYYY-MM-DD) | — | +| `--end ` | End date (YYYY-MM-DD) | — | + +### `pool liq-history ` (read) + +Pool liquidity history over a date range. + +```bash +sun pool liq-history [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--start ` | Start date (YYYY-MM-DD) | — | +| `--end ` | End date (YYYY-MM-DD) | — | + +--- + +## Liquidity + +### `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): + +```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 +``` + +### `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 +``` + +### `liquidity v3:mint` (write) + +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 +``` + +### `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 +``` + +### `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 +``` + +### `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 +``` + +### `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 +``` + +Create pool if it does not exist: + +```bash +sun liquidity v4:mint --token0 TRX --token1 USDT --amount0 1000000 --create-pool +``` + +### `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 +``` + +### `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 +``` + +### `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 +``` + +### `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 +``` + +--- + +## Position + +### `position list` (read) + +List liquidity positions. + +```bash +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 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 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 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 farm tx [options] +``` + +| Option | Description | Default | +| :--- | :--- | :--- | +| `--owner
` | Owner address | — | +| `--farm ` | Filter by farm | — | +| `--type ` | Transaction type | — | +| `--start