diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 0882e992..5e67525d 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -5,15 +5,15 @@ on: branches: - main - master - - ai-bankofai-patch-1 + - update-mcp-server tags: - 'test' pull_request: branches: - main - master - - ai-bankofai-patch-1 - workflow_dispatch: + - update-mcp-server + workflow_dispatch: # Intentionally unrestricted — allows manual builds from any branch for flexibility env: IMAGE_NAME: bankofai/docs @@ -31,15 +31,6 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - - name: Debug Docker Hub secrets - if: github.event_name != 'pull_request' - env: - DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} - DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - run: | - echo "username=[$DOCKERHUB_USERNAME]" - echo "token_length=${#DOCKERHUB_TOKEN}" - - name: Log in to Docker Hub if: github.event_name != 'pull_request' env: diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md new file mode 100644 index 00000000..bc7a2ff7 --- /dev/null +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -0,0 +1,274 @@ +# CLI Reference + +A complete reference for every Agent-wallet command. Whether you're reviewing the basics or configuring automation scripts, you'll find the answer here. + +:::tip Just getting started? +If you haven't created a wallet yet, head to [Quick Start](../QuickStart.md) first — three steps, under a minute. +::: + +--- + +## Basic Commands + +The core operations you'll use most often — creating wallets and signing. + +### `agent-wallet start` (Initialize / Create Wallet) + +**Interactive creation (recommended):** +```bash +agent-wallet start +``` +The system walks you through choosing a wallet type, generating keys, and setting a master password. Just follow the prompts. + +:::danger Avoid the `raw_secret` wallet type for real funds +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`. +::: + +**Custom password:** +```bash +agent-wallet start -p Abc12345! +``` +Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. + +:::caution Shell history risk +Passing `-p` inline records the password in your terminal's history file. For production wallets, prefer interactive mode (`agent-wallet start` without `-p`) or set `AGENT_WALLET_PASSWORD` as an environment variable — see [Non-Interactive Execution](#non-interactive-execution-for-automation--background-services). +::: + +**Import an existing private key:** +```bash +agent-wallet start -p Abc12345! -k your-private-key-hex +``` + +**Import a mnemonic:** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." +``` + +### `agent-wallet sign` (Core Signing Operations) + +Every `sign` subcommand requires `--network` / `-n` to specify the chain. + +**Sign a message:** +```bash +agent-wallet sign msg "Hello" -n tron +``` + +**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 +``` + +**Sign EIP-712 typed data:** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 +``` + +--- + +## Wallet Management + +Manage multiple wallets — add, switch, inspect, remove. + +**Add a new wallet:** +```bash +agent-wallet add +``` + +**List all wallets:** +```bash +agent-wallet list +``` + +**Switch the active wallet:** +```bash +agent-wallet use my-bsc-wallet +``` + +**Inspect a wallet:** +```bash +agent-wallet inspect my-bsc-wallet +``` + +**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!' +``` + +**Remove a wallet:** +```bash +agent-wallet remove my-bsc-wallet +``` + +--- + +## Non-Interactive Execution (For Automation & Background Services) + +By default, signing commands pause and prompt you to type your password interactively. But if an AI agent is running in the background, or you're running an automation script, this "stop and wait for input" behavior will cause the program to hang or error out. + +To let the program run silently from start to finish (non-interactive mode), you need to pre-supply the password. Depending on your use case, there are three approaches: + +### Method A: Environment Variable Injection (Recommended for AI Agents / CI Pipelines) + +Store the password in the current system environment. When the program needs the password, it automatically retrieves it — fully silent: + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +``` + +Once set, all signing commands in the current window return results instantly, no more pausing: + +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` + +:::tip Prevent this command from being recorded in shell history +To prevent the command from being recorded in shell history, edit `~/.zshrc` / `~/.bashrc` directly in a text editor rather than running the command in the terminal. Alternatively, prefix the command with a space — but only if you have verified that `HISTCONTROL=ignorespace` is active in Bash (`echo $HISTCONTROL`) or `HIST_IGNORE_SPACE` is active in Zsh (`setopt | grep HIST_IGNORE_SPACE`). These settings are **not** enabled by default on most systems and must be configured explicitly. +::: + +:::caution Password contains special characters? Always use single quotes +```bash +# ✅ Correct — shell treats it literally +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong — $ gets expanded by the shell, password silently breaks +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +
+GitHub Actions / CI example + +In CI/CD environments, never hardcode the password in workflow files. Use repository secrets instead: + +```yaml +# .github/workflows/sign.yml +jobs: + sign: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: agent-wallet sign msg "Hello" -n tron + env: + AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }} +``` + +
+ +### Method B: Local Password Cache (Convenience vs. Security Trade-off) + +After running a command once with the `--save-runtime-secrets` flag, the password is cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: + +```bash +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets +``` + +:::danger This disables the dual-lock protection +Caching the password next to the wallet file means a single file system compromise grants full access to your funds — defeating Agent-wallet's core "physical file + password separation" security model. **Only use this for throwaway test wallets.** + +`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Make sure this file is never committed to git or synced to the cloud. + +The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`. + +To remove the cached password and restore full dual-lock protection: + +```bash +rm ~/.agent-wallet/runtime_secrets.json +``` + +After deletion, signing commands will prompt for the password interactively again (or read from `AGENT_WALLET_PASSWORD` if set). +::: + +### Method C: Inline `-p` Flag (For One-Off Commands) + +Pass the password directly at the end of the command. The program takes the password and runs immediately — no prompts: + +```bash +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' +``` + +:::danger Security Warning +When using `-p` to pass the password inline, the plaintext password is recorded in your terminal's `history`. Only use this method in fully isolated test environments! +::: + +### Custom Storage Directory + +All commands support the `--dir` flag to specify a custom Agent-wallet storage path (default: `~/.agent-wallet`). For example, you can store your Agent-wallet directly on an encrypted USB drive — plug and play, unplug and go: + +```bash +agent-wallet start --dir /Volumes/MyUSB/agent-wallet +agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet +``` + +--- + +## Dangerous Operations + +:::danger The following operations are irreversible — use with extreme caution! +::: + +### `agent-wallet change-password` (Change Master Password) + +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. + +```bash +agent-wallet change-password +``` + +### `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. + +```bash +agent-wallet reset +``` + +--- + +## Real-World Example: Signing in a Shell Script + +The CLI isn't just for manual typing — it integrates perfectly into your automation scripts. + +This minimal example demonstrates how to perform a non-interactive signing operation in a Bash script, cleanly capturing the signature result into a variable for subsequent use (no complex network request code involved): + +```bash +#!/bin/bash +# Enable strict mode: stop immediately on any error +set -e + +# 1. Password should already be set in the environment before running this script. +# e.g. via ~/.zshrc / ~/.bashrc — see "Save and Activate the Password" in QuickStart. +# NEVER hardcode a real password in a script file (it will end up in git history). +if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then + echo "Error: AGENT_WALLET_PASSWORD not set" >&2 + exit 1 +fi + +echo "Calling local Agent-wallet for signing..." + +# 2. Core operation: execute signing, capture the hash output into the SIGNATURE variable +SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) + +# 3. Got the clean signature result — continue with downstream logic +echo "✅ Signing successful!" +echo "Extracted signature: $SIGNATURE" + +# From here, you can use $SIGNATURE to build requests, construct JSON, or pass it to other pipeline tasks... +``` + +--- + +## Next Steps + +- New to this? → [Quick Start](../QuickStart.md) +- Building your own agent? → [SDK Guide](./SDK-Guide.md) +- Looking for ready-made code? → [SDK Cookbook](./SDK-Cookbook.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md new file mode 100644 index 00000000..601753ef --- /dev/null +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -0,0 +1,568 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SDK Cookbook + +:::tip Why read this page? +In the [SDK Guide](./SDK-Guide.md), you learned how to use Agent-wallet for "offline signing." But in real-world scenarios, an AI agent can't just sign — it needs to: **1. Query the node to build a transaction → 2. Agent-wallet signs → 3. Broadcast to the blockchain.** + +Agent-wallet focuses on doing the core secure signing step (step 2) well. This page provides a set of **"ready-to-use"** complete scripts that combine TronGrid and Ethers.js / Web3.py to walk you through the full end-to-end flow. You can copy these scripts directly into your production environment! +::: + +This page walks through three real-world scenarios end to end: sending TRX on TRON, sending BNB on BSC, and signing an x402 payment permit. Each example is complete and runnable — copy, configure your addresses, and go. + +All examples are available in both TypeScript and Python — use the tabs to switch. + +--- + +## Prerequisites + +Before running any example below, make sure you have: + +1. Installed the Agent-wallet SDK (see [SDK Guide](./SDK-Guide.md)) +2. Initialized a local wallet via the CLI, or configured static mode environment variables +3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode — strongly recommended) + +:::danger Avoid static mode (`AGENT_WALLET_PRIVATE_KEY`) for real funds +Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local Agent-wallet. +::: + +--- + +## TRON Transfer + +**Use case**: An AI agent needs to initiate a TRX transfer on the TRON network — for example, paying API call fees, sweeping funds to another address, or settling a reward after completing an automated task. + +**How it works**: + +TRON transactions cannot be constructed directly by the client from scratch. The flow must start with a call to TronGrid's `createtransaction` endpoint, which returns an unsigned transaction object containing `txID` and `raw_data` generated by the network node. That object is then passed to Agent-wallet for local signing — the signing process is fully offline and the private key never leaves the machine. Finally, the signed transaction is submitted to TronGrid's `broadcasttransaction` endpoint to be published on-chain. + +``` +TronGrid (build) → Agent-wallet (sign) → TronGrid (broadcast) +``` + +Agent-wallet only participates in the middle signing step. It requires no RPC connection and has no awareness of the transaction's business meaning. + +### Install Dependencies + + + + +```bash +npm install @bankofai/agent-wallet axios +``` + + + + +This example uses `aiohttp` (a third-party HTTP library) and `asyncio` (Python standard library — no install needed): + +```bash +pip install aiohttp +``` + +:::caution If you see missing standard library module errors +If importing `asyncio` or other standard library modules fails, it's usually because system dependencies were missing when pyenv built Python from source. Install the following packages and then re-run `pyenv install 3.11`: + +```bash +# CentOS / RHEL / Amazon Linux +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` +::: + + + + + + +### Full Code + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import axios from "axios"; + +const TRONGRID_API = "https://nile.trongrid.io"; // Nile testnet; change to https://api.trongrid.io for mainnet + +async function transferTRX( + fromAddress: string, + toAddress: string, + amountSun: number // 1 TRX = 1_000_000 SUN +) { + // Step 1: Initialize Agent-wallet + const provider = resolveWalletProvider({ network: "tron:nile" }); + const wallet = await provider.getActiveWallet(); + + // Ensure fromAddress matches the wallet — a mismatch will cause a TronGrid error + const walletAddress = await wallet.getAddress(); + if (fromAddress !== walletAddress) { + throw new Error(`fromAddress mismatch: expected ${walletAddress}, got ${fromAddress}`); + } + + // Step 2: Build the unsigned transaction via TronGrid + const { data: unsignedTx } = await axios.post( + `${TRONGRID_API}/wallet/createtransaction`, + { + owner_address: fromAddress, + to_address: toAddress, + amount: amountSun, + visible: true, + } + ); + + if (!unsignedTx.txID) { + throw new Error("Failed to build transaction: " + JSON.stringify(unsignedTx)); + } + + console.log("Unsigned txID:", unsignedTx.txID); + + // Step 3: Sign locally with Agent-wallet + let signedTx: Record; + try { + signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + } catch (e) { + throw new Error(`signTransaction returned invalid JSON: ${e}`); + } + if (!signedTx.signature) { + throw new Error("Signed transaction is missing the signature field"); + } + if (!signedTx.txID) { + throw new Error("Signed transaction is missing the txID field"); + } + console.log("Signed, signature:", signedTx.signature); + + // Step 4: Broadcast via TronGrid + const { data: broadcastResult } = await axios.post( + `${TRONGRID_API}/wallet/broadcasttransaction`, + signedTx + ); + + if (broadcastResult.result) { + console.log("Broadcast successful! txID:", signedTx.txID); + } else { + console.error("Broadcast failed:", broadcastResult); + } + + return signedTx.txID; +} + +// Example usage +transferTRX( + "YOUR_TRON_ADDRESS", // replace with your wallet address + "RECIPIENT_TRON_ADDRESS", // replace with the recipient address + 1_000_000 // 1 TRX +).catch(console.error); +``` + + + + +```python +import asyncio +import json +import aiohttp +from agent_wallet import resolve_wallet_provider + +TRONGRID_API = "https://nile.trongrid.io" # Nile testnet; change to https://api.trongrid.io for mainnet + +async def transfer_trx( + from_address: str, + to_address: str, + amount_sun: int, # 1 TRX = 1_000_000 SUN +): + # Step 1: Initialize Agent-wallet + provider = resolve_wallet_provider(network="tron:nile") + wallet = await provider.get_active_wallet() + + async with aiohttp.ClientSession() as session: + # Step 2: Build the unsigned transaction via TronGrid + async with session.post( + f"{TRONGRID_API}/wallet/createtransaction", + json={ + "owner_address": from_address, + "to_address": to_address, + "amount": amount_sun, + "visible": True, + }, + ) as resp: + unsigned_tx = await resp.json() + + if "txID" not in unsigned_tx: + raise ValueError(f"Failed to build transaction: {unsigned_tx}") + + print("Unsigned txID:", unsigned_tx["txID"]) + + # Step 3: Sign locally with Agent-wallet + raw_signed = await wallet.sign_transaction(unsigned_tx) + try: + signed_tx = json.loads(raw_signed) + except json.JSONDecodeError as e: + raise ValueError(f"signTransaction returned invalid JSON: {e}") from e + if "signature" not in signed_tx: + raise ValueError("Signed transaction is missing the signature field") + print("Signed, signature:", signed_tx["signature"]) + + # Step 4: Broadcast via TronGrid + async with session.post( + f"{TRONGRID_API}/wallet/broadcasttransaction", + json=signed_tx, + ) as resp: + broadcast_result = await resp.json() + + if broadcast_result.get("result"): + print("Broadcast successful! txID:", signed_tx["txID"]) + else: + print("Broadcast failed:", broadcast_result) + + return signed_tx["txID"] + +# Example usage +asyncio.run( + transfer_trx( + from_address="YOUR_TRON_ADDRESS", # replace with your wallet address + to_address="RECIPIENT_TRON_ADDRESS", # replace with the recipient address + amount_sun=1_000_000, # 1 TRX + ) +) +``` + + + + +:::caution Notes +- Use the Nile testnet for testing. Get test tokens from the [Nile Faucet](https://nileex.io/join/getJoinPage). +- For mainnet, change `TRONGRID_API` to `https://api.trongrid.io` and `network` to `tron:mainnet`. +::: + +:::tip `visible: true` and address format +The code passes `visible: true` to TronGrid. This parameter affects the address format the API expects: + +- **`visible: true`**: the API expects addresses in **Base58 format** (the standard human-readable TRON address, e.g. `TNmo...`) +- **`visible: false` (or omitted)**: the API expects addresses in **hex format** (e.g. `41b9f...`) + +The example uses Base58 addresses, consistent with `visible: true`. +::: + +--- + +## EVM Transfer (BSC / Ethereum) + +**Use case**: An AI agent needs to initiate a native token transfer on BSC, Ethereum, or any other EVM-compatible chain — for example, paying gas, transferring to a contract to trigger business logic, or settling a payment on-chain after completing a task. + +**How it works**: + +EVM transactions require the caller to construct the transaction object themselves. Unlike TRON, the fields of an EVM transaction (`nonce`, `gas`, `chainId`, etc.) must be queried from the current chain state via RPC and filled in manually — there is no centralized API that generates them for you. Once the unsigned transaction is built, it is passed to Agent-wallet for local signing, which returns a hex-encoded signed transaction. That signed transaction is then broadcast to the network via `sendRawTransaction`. + +``` +RPC query nonce/gas (build) → Agent-wallet (sign) → RPC sendRawTransaction (broadcast) +``` + +The example uses BSC Testnet, but switching to Ethereum, Polygon, Base, or any other EVM chain only requires changing `RPC_URL` and `CHAIN_ID` — the Agent-wallet calling code stays exactly the same. + +### Install Dependencies + + + + +```bash +npm install @bankofai/agent-wallet ethers +``` + + + + +```bash +pip install web3 +``` + + + + +### Full Code + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { ethers } from "ethers"; + +// BSC Testnet +const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; +const CHAIN_ID = 97; // BSC testnet; use 56 for mainnet + +async function transferBNB( + toAddress: string, + amountEther: string // e.g. "0.001" +) { + // Step 1: Initialize Agent-wallet + const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); + const wallet = await provider.getActiveWallet(); + const fromAddress = await wallet.getAddress(); + + // Step 2: Query nonce and gas info via RPC + const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); + const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); + const feeData = await rpcProvider.getFeeData(); + + if (!feeData.maxFeePerGas || !feeData.maxPriorityFeePerGas) { + throw new Error("Chain does not support EIP-1559 fee data"); + } + + // Step 3: Build the unsigned transaction + const unsignedTx = { + to: toAddress, + value: ethers.parseEther(amountEther), + gas: 21000n, + maxFeePerGas: feeData.maxFeePerGas, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas, + nonce, + chainId: CHAIN_ID, + type: 2, // EIP-1559 + }; + + console.log("Transaction built, nonce:", nonce); + + // Step 4: Sign locally with Agent-wallet + const signedTxHex = await wallet.signTransaction(unsignedTx); + console.log("Signed"); + + // Step 5: Broadcast + // signTransaction returns hex without '0x' prefix; ethers requires it + const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); + console.log("Broadcast successful! txHash:", txResponse.hash); + + // Wait for confirmation (optional — add timeout to avoid hanging) + try { + const receipt = await txResponse.wait(1); // wait 1 confirmation, throws on timeout + console.log("Confirmed in block:", receipt?.blockNumber); + } catch (e) { + console.warn("Receipt wait timed out or failed:", e); + } + + return txResponse.hash; +} + +// Example usage +transferBNB( + "0xYOUR_RECIPIENT_ADDRESS", // replace with the recipient address + "0.001" // send 0.001 BNB +).catch(console.error); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider +from web3 import AsyncWeb3 + +# BSC Testnet +RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" +CHAIN_ID = 97 # BSC testnet; use 56 for mainnet + +async def transfer_bnb(to_address: str, amount_ether: str): + # Step 1: Initialize Agent-wallet + provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") + wallet = await provider.get_active_wallet() + from_address = await wallet.get_address() + + # Step 2: Query nonce and gas info via RPC + w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) + nonce = await w3.eth.get_transaction_count(from_address, "latest") + fee_data = await w3.eth.fee_history(1, "latest", [50]) + base_fee = fee_data["baseFeePerGas"][-1] + priority_fee = await w3.eth.max_priority_fee + + # Step 3: Build the unsigned transaction + unsigned_tx = { + "to": to_address, + "value": w3.to_wei(amount_ether, "ether"), + "gas": 21000, + "maxFeePerGas": base_fee + priority_fee, + "maxPriorityFeePerGas": priority_fee, + "nonce": nonce, + "chainId": CHAIN_ID, + "type": 2, # EIP-1559 + } + + print("Transaction built, nonce:", nonce) + + # Step 4: Sign locally with Agent-wallet + signed_tx_hex = await wallet.sign_transaction(unsigned_tx) + print("Signed") + + # Step 5: Broadcast + tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) + print("Broadcast successful! txHash:", tx_hash.hex()) + + # Optional: wait for confirmation + # NOTE: This blocks the event loop for up to `timeout` seconds. + # For production AI agents, consider running this in a background task + # or using asyncio.wait_for() with a shorter timeout and retry logic. + import asyncio + try: + receipt = await asyncio.wait_for( + w3.eth.wait_for_transaction_receipt(tx_hash), + timeout=120 + ) + print("Confirmed in block:", receipt["blockNumber"]) + except asyncio.TimeoutError: + print("Confirmation timed out — the transaction may still confirm. txHash:", tx_hash.hex()) + + return tx_hash.hex() + +# Example usage +asyncio.run( + transfer_bnb( + to_address="0xYOUR_RECIPIENT_ADDRESS", # replace with the recipient address + amount_ether="0.001", + ) +) +``` + + + + +:::caution Notes +- Use BSC Testnet (chainId=97) for testing. Get test tokens from the [BSC Faucet](https://testnet.binance.org/faucet-smart). +- For mainnet, change `RPC_URL` to a mainnet RPC endpoint, `CHAIN_ID` to `56`, and `network` to `eip155:56`. +::: + +--- + +## x402 PaymentPermit Signing + +**Use case**: An AI agent is accessing a paid API protected by the x402 protocol — such as fetching real-time data, calling an AI inference service, or triggering an on-chain operation. The server responds with HTTP 402, requiring the agent to provide a payment authorization before it can retrieve the content. + +**How it works**: + +x402 payments do not work by sending a direct transfer. Instead, they use a "sign first, verify to proceed" model. The agent signs a `TransferWithAuthorization` structure (EIP-712 format), and the resulting signature is sent alongside the request as a payment credential. The server verifies the signature and returns the content only if it is valid. The agent never has to wait for on-chain confirmation — latency is minimal. + +``` +Server returns 402 → Agent builds PaymentPermit → Agent-wallet signs → Resend request with signature → Server verifies and responds +``` + +The PaymentPermit data is automatically constructed by the x402 SDK based on the payment parameters returned by the server. Agent-wallet is only responsible for the final signing step. The example below shows the underlying signing logic, useful for scenarios that require custom integration or bypassing the x402 SDK. + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +async function signPaymentPermit(authorization: { + from: string; + to: string; + value: string; + validAfter: string; + validBefore: string; + nonce: string; +}) { + // Initialize Agent-wallet (EVM wallet, network must match the x402 payment network) + const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base mainnet + const wallet = await provider.getActiveWallet(); + + // Build EIP-712 typed data (aligned with the x402 protocol spec) + const typedData = { + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "version", type: "string" }, + { name: "chainId", type: "uint256" }, + { name: "verifyingContract", type: "address" }, + ], + TransferWithAuthorization: [ + { name: "from", type: "address" }, + { name: "to", type: "address" }, + { name: "value", type: "uint256" }, + { name: "validAfter", type: "uint256" }, + { name: "validBefore", type: "uint256" }, + { name: "nonce", type: "bytes32" }, + ], + }, + primaryType: "TransferWithAuthorization", + domain: { + name: "USD Coin", + version: "2", + chainId: 8453, + verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC + }, + message: authorization, + }; + + // Sign locally with Agent-wallet + const signature = await wallet.signTypedData(typedData); + console.log("PaymentPermit signature:", signature); + + return signature; +} +``` + + + + +```python +from agent_wallet import resolve_wallet_provider + +async def sign_payment_permit(authorization: dict) -> str: + # Initialize Agent-wallet (EVM wallet, network must match the x402 payment network) + provider = resolve_wallet_provider(network="eip155:8453") # Base mainnet + wallet = await provider.get_active_wallet() + + # Build EIP-712 typed data (aligned with the x402 protocol spec) + typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"}, + ], + "TransferWithAuthorization": [ + {"name": "from", "type": "address"}, + {"name": "to", "type": "address"}, + {"name": "value", "type": "uint256"}, + {"name": "validAfter", "type": "uint256"}, + {"name": "validBefore", "type": "uint256"}, + {"name": "nonce", "type": "bytes32"}, + ], + }, + "primaryType": "TransferWithAuthorization", + "domain": { + "name": "USD Coin", + "version": "2", + "chainId": 8453, + "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # Base USDC + }, + "message": authorization, + } + + # Sign locally with Agent-wallet + signature = await wallet.sign_typed_data(typed_data) + print("PaymentPermit signature:", signature) + + return signature +``` + + + + +:::tip +The x402 SDK automatically constructs the PaymentPermit data and calls the signing interface, so you typically won't need to write this code manually. The example above shows the underlying signing logic, which is useful for custom integration scenarios. See the [x402 Protocol documentation](../../x402/index.md) for details. +::: + +--- + +## Next Steps + +- Prefer the command line? → [CLI Reference](./CLI-Reference.md) +- Building your own agent? → [SDK Guide](./SDK-Guide.md) +- Learn how x402 and Agent-wallet work together → [x402 Introduction](../../x402/index.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md new file mode 100644 index 00000000..2423e119 --- /dev/null +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -0,0 +1,531 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SDK Guide + +You've tried the CLI and can sign from the command line. Now you want signing inside your own code — an MCP Server, an automation script, an AI agent workflow. + +This page shows you how. By the end, you'll be able to initialize a wallet provider, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data — all in a few lines of TypeScript or Python. + +:::tip New here? +If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md) first (takes under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. +::: + +Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch. + +--- + +## Step 1: Install + + + + +**Check Your Node.js Version** + +Requires Node.js ≥ 18. 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. + +:::tip Install / Upgrade Node.js + +We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions: + +```bash +# Install nvm (skip if already installed) +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 +``` + +You can also download the **LTS** installer directly from [nodejs.org](https://nodejs.org). + +::: + +**Install the SDK** + +```bash +npm install @bankofai/agent-wallet +``` + + + + +**Check Your Python Version** + +Requires Python ≥ 3.11 (the SDK uses 3.11+ features): + +```bash +python3 --version +``` + +If the output is `3.11.x` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. + +:::tip Install / Upgrade Python + +We recommend using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions: + +```bash +# Step 1: Install pyenv +curl https://pyenv.run | bash +``` + +After installation, you need to add pyenv to your shell config manually — otherwise the terminal won't find the `pyenv` command: + +```bash +# Append these three lines to ~/.bashrc (or ~/.zshrc for zsh users) +echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc +echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(pyenv init -)"' >> ~/.bashrc + +# Reload config to apply changes in the current terminal +source ~/.bashrc +``` + +Once pyenv is available, install the required system dependencies first. **Skipping this step will cause modules like `_ctypes` and `ssl` to be missing, which can break standard library imports including `asyncio`.** + +```bash +# CentOS / RHEL / Amazon Linux / Fedora +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` + +Then build Python: + +```bash +pyenv install 3.11 +pyenv global 3.11 +``` + +You can also download an installer from [python.org](https://www.python.org/downloads/), selecting **3.11 or higher**. + +::: + +**Install the SDK** + +```bash +pip install 'bankofai-agent-wallet[evm,tron]' +``` + +If you only need one chain, install the corresponding extra: + +```bash +pip install 'bankofai-agent-wallet[tron]' # TRON only +pip install 'bankofai-agent-wallet[evm]' # EVM only +``` + +Verify the installation: + +```bash +python3 -c "import agent_wallet; print('Installation successful')" +``` + + + + +--- + +## Step 2: Configure a Mode + +Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. + +Don't be intimidated by the concepts — `resolveWalletProvider()` is extremely smart. It automatically detects which environment variables you've set and decides the mode for you. No `if/else` logic needed in your code. + +It supports two modes: + +### 🛡️ Core Usage: Local Agent-wallet Mode (Strongly Recommended) + +If you've already followed the [Quick Start](../QuickStart.md), your private key is already safely locked inside a hidden file on your machine. + +**In this mode, you never need to (and shouldn't) touch your plaintext private key.** Just tell the SDK your "unlock password" and you're good to go. + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +# Optional: if you changed the wallet storage directory, tell the SDK where to look +export AGENT_WALLET_DIR="$HOME/.agent-wallet" +``` + +:::caution Always use single quotes when the password contains special characters +Auto-generated strong passwords may contain `$`, `!`, or other shell-special characters. Always use single quotes to prevent the shell from expanding and corrupting the password: + +```bash +# ✅ Correct: single quotes, password passed as-is +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong: double quotes, $ gets expanded by the shell +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +### ⚠️ Fallback: Static Injection Mode (Test Environments Only) + +If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local Agent-wallet and feed the private key directly to the SDK. + +```bash +export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex' +# or +export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' +``` + +:::danger Extremely Dangerous: Violates Core Security Principles! +Static mode reads your private key in plaintext, which means you forfeit Agent-wallet's encryption protection and fall back to the "single point of failure" approach described in the introduction. Only use this mode in fully isolated test environments or one-off CI/CD scripts! For mainnet operations with real funds, always use local Agent-wallet mode. +::: + +:::tip What if environment variables conflict? +If both a password and a private key exist in your environment variables, the SDK prioritizes security: it forces `AGENT_WALLET_PASSWORD` to enter local Agent-wallet mode and ignores the plaintext private key. +::: + +### Environment Variable Reference + +| Variable | Purpose | Mode | Required | +| :--- | :--- | :--- | :--- | +| `AGENT_WALLET_PASSWORD` | Master password, unlocks the local hidden file | 🛡️ Local Agent-wallet | Core required | +| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | 🛡️ Local Agent-wallet | Optional | +| `AGENT_WALLET_PRIVATE_KEY` | Plaintext private key (hex) | ⚠️ Static Injection | Choose one (with mnemonic) | +| `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | ⚠️ Static Injection | Choose one (with private key) | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 derivation index (default `0`) | ⚠️ Static Injection | Optional | + +--- + +## Usage Examples + +### Initialize the Wallet Provider + +The starting point for all operations is `resolveWalletProvider()`. It reads the environment variables, selects the appropriate mode, and returns a wallet provider. Call `getActiveWallet()` to get the active wallet. + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); + +// Check the current wallet address +const address = await wallet.getAddress(); +console.log("Address:", address); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + wallet = await provider.get_active_wallet() + + # Check the current wallet address + address = await wallet.get_address() + print("Address:", address) + +asyncio.run(main()) +``` + + + + +Once you have `wallet`, you can call any of the three signing methods below. All signing methods return a hex-encoded signature string (without the `0x` prefix). + +### Sign a Message + + + + +```typescript +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_message(b"Hello") +print("Signature:", sig) +``` + + + + +### Sign a Transaction + +Agent-wallet only handles signing — not building or broadcasting. You need to construct the unsigned transaction via RPC (e.g. TronGrid, Infura) first, then pass it to the SDK for signing. + +#### TRON Transaction + + + + +```typescript +// 1. Caller builds the unsigned transaction via TronGrid +const unsignedTx = { + txID: "abc123...", + raw_data_hex: "0a02...", + raw_data: { /* raw data returned by TronGrid */ }, +}; + +// 2. SDK signs locally (no network call) +const signedTxJson = await wallet.signTransaction(unsignedTx); +console.log("Signed transaction:", signedTxJson); + +// 3. Caller is responsible for broadcasting +``` + + + + +```python +# 1. Caller builds the unsigned transaction via TronGrid +unsigned_tx = { + "txID": "abc123...", + "raw_data_hex": "0a02...", + "raw_data": {}, # raw data returned by TronGrid +} + +# 2. SDK signs locally (no network call) +signed_tx_json = await wallet.sign_transaction(unsigned_tx) +print("Signed transaction:", signed_tx_json) + +# 3. Caller is responsible for broadcasting +``` + + + + +#### EVM Transaction (BSC, Ethereum, etc.) + + + + +```typescript +const sig = await wallet.signTransaction({ + to: "0xRecipient...", + value: 0n, + gas: 21000n, + maxFeePerGas: 20000000000n, + nonce: 0, + chainId: 56, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_transaction({ + "to": "0xRecipient...", + "value": 0, + "gas": 21000, + "maxFeePerGas": 20000000000, + "nonce": 0, + "chainId": 56, +}) +print("Signature:", sig) +``` + + + + +### Sign EIP-712 Typed Data + +Used for x402 protocol PaymentPermit signatures, Permit2, and similar scenarios: + + + + +```typescript +const sig = await wallet.signTypedData({ + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "chainId", type: "uint256" }, + ], + Transfer: [ + { name: "to", type: "address" }, + { name: "amount", type: "uint256" }, + ], + }, + primaryType: "Transfer", + domain: { name: "MyDApp", chainId: 1 }, + message: { to: "0x...", amount: 1000000 }, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_typed_data({ + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + ], + "Transfer": [ + {"name": "to", "type": "address"}, + {"name": "amount", "type": "uint256"}, + ], + }, + "primaryType": "Transfer", + "domain": {"name": "MyDApp", "chainId": 1}, + "message": {"to": "0x...", "amount": 1000000}, +}) +print("Signature:", sig) +``` + + + + +--- + +### Manage Multiple Wallets + +If you need to manage multiple wallets in code, use `resolveWalletProvider()` in local mode. The provider reads the wallet configuration and lets you switch the active wallet: + + + + +```typescript +import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet"; + +// Local mode: AGENT_WALLET_PASSWORD must be set +const provider = resolveWalletProvider({ network: "tron:nile" }); + +if (provider instanceof ConfigWalletProvider) { + // List all wallets — returns [walletId, config, isActive] tuples + const wallets = provider.listWallets(); + for (const [id, config, isActive] of wallets) { + console.log(`${id} (${config.type})${isActive ? " ← active" : ""}`); + } + + // Switch the active wallet + provider.setActive("my-evm-wallet"); +} + +// Get and use +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider, ConfigWalletProvider + +# AGENT_WALLET_PASSWORD must be set +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + if isinstance(provider, ConfigWalletProvider): + # List all wallets — returns [(wallet_id, config, is_active)] tuples + wallets = provider.list_wallets() + for wallet_id, config, is_active in wallets: + print(f"{wallet_id} ({config.type}){' ← active' if is_active else ''}") + + # Switch the active wallet + provider.set_active("my-evm-wallet") + + # Get and use + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) + +asyncio.run(main()) +``` + + + + +--- + +### Error Handling + +When a signing operation fails, the SDK throws specific error types. It's recommended to catch and handle them explicitly in your code to avoid runtime crashes. + + + + +```typescript +import { + WalletNotFoundError, + SigningError, + DecryptionError, +} from "@bankofai/agent-wallet"; + +try { + const wallet = await provider.getActiveWallet(); + const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); + console.log("Signature:", sig); +} catch (e) { + if (e instanceof WalletNotFoundError) { + console.error("Wallet not found — check that an active wallet is set"); + } else if (e instanceof DecryptionError) { + console.error("Decryption failed — check that the master password is correct"); + } else if (e instanceof SigningError) { + console.error("Signing failed:", e.message); + } else { + throw e; + } +} +``` + + + + +```python +from agent_wallet import WalletNotFoundError, SigningError, DecryptionError + +try: + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) +except WalletNotFoundError: + print("Wallet not found — check that an active wallet is set") +except DecryptionError: + print("Decryption failed — check that the master password is correct") +except SigningError as e: + print(f"Signing failed: {e}") +``` + + + + +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 (thrown by caller) +└── UnsupportedOperationError # Operation not supported by this wallet type +``` + +--- + +## Next Steps + +- Prefer the command line? → [CLI Reference](./CLI-Reference.md) +- Looking for ready-made code? → [SDK Cookbook](./SDK-Cookbook.md) +- Understand Agent-wallet's design → [Introduction](../Intro.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md new file mode 100644 index 00000000..44306967 --- /dev/null +++ b/docs/Agent-Wallet/FAQ.md @@ -0,0 +1,218 @@ +# FAQ + +Let's answer the three things you're probably most worried about, then cover the day-to-day details. + +--- + +## 💰 Will AI drain my entire wallet? + +This is the most common question, and the answer is: **even if your AI agent gets compromised, your core assets stay safe.** + +We strongly recommend creating a dedicated wallet just for your AI agent, topped up with only the small amount it actually needs (e.g., enough to cover gas fees). Your main wallet and large holdings never get touched. Worst case, the loss is limited to whatever was in that small agent wallet. + +```bash +# Create a dedicated small wallet for your AI agent +agent-wallet add +``` + +And your wallet file is protected by strong encryption. Even if someone gets hold of the file, without the master password it's just garbage — brute-forcing it is economically worthless. + +--- + +## 🔌 Can my AI still sign if I go offline? + +Yes. **All Agent-wallet signing operations complete 100% on your local machine.** + +There's no network dependency by design — no RPC calls, no cloud services, no remote API requests. Your private key never touches the network. + +Going offline only affects transaction building and broadcasting (that's the MCP Server's job). Signing itself is fully offline. + +--- + +## 🔑 What if I forget my password? + +**It's gone.** + +The master password is the only credential for decrypting all private keys. There's no "forgot password" flow, no backdoor. + +If you forget your password: +- Have another backup of your private key or mnemonic? Run `agent-wallet reset`, reinitialize, and reimport. +- No backup at all? Access to that wallet is lost. + +**So do this right now**: open your password manager and store the master password. Seriously. + +--- + +## Everyday Use + +### What exactly is Agent-wallet? + +A purely local encrypted signing tool. It does two things: 1) encrypts and stores your private keys; 2) signs locally. No internet, no cloud. It has no standalone UI of its own — instead, it operates as an invisible security hub that integrates seamlessly into AI frontends like OpenClaw. + +### CLI vs SDK — which do I need? + +- **CLI** — command-line tool for creating wallets, managing keys, and manually testing signatures +- **SDK** — TypeScript / Python library for calling signing directly from your own code + +Most users don't need the SDK. If you're using OpenClaw and MCP Server, creating a wallet with the CLI and setting the environment variable is all you need. The SDK is for developers building their own agents. + +### What's the difference between Agent-wallet and MetaMask? + +MetaMask is a browser wallet designed for humans, with a graphical interface that requires you to manually click "Confirm" for every signature. Agent-wallet is a command-line wallet designed for AI agents, purpose-built for non-interactive use — AI can silently invoke signing in the background without anyone watching the screen. Both use similar encryption under the hood (Keystore V3), but they serve completely different use cases. + +### How many wallets can I create on one machine? + +No limit. You can create separate wallets for different AI agents, different chains, or different purposes. Use `agent-wallet add` to create and `agent-wallet use` to switch between them. + +--- + +## Wallet Types + +### What's the difference between `local_secure` and `raw_secret`? + +| | `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 | + +:::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. +::: + +### What values does the `network` parameter accept? + +| Value | Description | +| :--- | :--- | +| `tron:mainnet` | TRON Mainnet | +| `tron:nile` | TRON Nile Testnet | +| `tron:shasta` | TRON Shasta Testnet | +| `eip155:1` | Ethereum Mainnet | +| `eip155:56` | BSC Mainnet | +| `eip155:137` | Polygon Mainnet | +| `eip155:8453` | Base Mainnet | +| `eip155:42161` | Arbitrum Mainnet | + +--- + +## Security + +### The password is also stored in an environment variable — how is that different from a plaintext private key? + +The difference is enormous! It's the difference between leaving cash on the table and locking it in a double-layered safe. + +When you use a Web3 wallet like MetaMask, you never copy-paste your raw private key every time — you unlock it with a short password. Agent-wallet is essentially a command-line MetaMask built for AI agents. + +* Traditional approach (plaintext private key): It's like leaving cash right on the table. Any malicious browser extension, one careless code commit, or a background log scan — one glance at your environment variables and the money is gone instantly. A classic single point of failure. +* Agent-wallet approach: It splits the risk into two locks. + 1. Physical safe: Your private key is encrypted with industry-grade algorithms and locked in a hidden folder deep in your system (`~/.agent-wallet`). + 2. Unlock password: What you put in your environment variable is merely the password to open this safe. + +This means if a leak occurs: + +* If a hacker only steals your password (e.g., by scanning environment variables), they don't have your encrypted wallet file — the password is just a useless string. +* If a hacker only steals your encrypted wallet file, they don't have your master password — the file is uncrackable gibberish that would take millennia to brute-force. + +A hacker would need to simultaneously break into your computer, locate and steal the hidden wallet file, AND steal the password from your environment variables to touch your funds. The difficulty of this attack is orders of magnitude higher than simply scanning environment variables! + +### Does the private key ever leave my machine? + +Never. Agent-wallet makes zero network requests. Zero RPC calls, zero cloud services. Your private key never leaves your machine. + +### How should I store the master password securely? + +- ✅ Use a password manager (1Password, Bitwarden) +- ✅ Pass it via the `AGENT_WALLET_PASSWORD` environment variable +- ❌ Don't hardcode it in source code +- ❌ Don't commit environment variable files containing the password to git + +### Is the encryption algorithm secure? Can it be brute-forced? + +Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), the exact same encryption scheme used by official Ethereum wallets. The scrypt algorithm is specifically designed to make brute-force attacks extremely expensive in both computation and memory — even with dedicated hardware, cracking a strong password would take tens of thousands of years. + +--- + +## Installation & Environment + +### 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. + +### `npm install -g` gives a permission error? + +This is common on macOS / Linux. Two solutions: + +**Method 1 (Recommended): Use nvm to manage Node.js** — it installs global packages in your user directory, no `sudo` needed. + +**Method 2: Fix npm global directory permissions:** +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc +source ~/.zshrc +``` + +### I configured the password but AI says "wallet not found" or "wrong password"? + +The three most common causes: + +1. **Password didn't take effect**: You ran `export` in Terminal A, but the AI runs in Terminal B. Solution: restart the AI backend service (see [Quick Start](./QuickStart.md) Step 2). +2. **Shell ate the password**: A password wrapped in double quotes contains `$` or `!`, which the shell expanded. Solution: switch to single quotes. +3. **Wrong storage directory**: You previously used `--dir` to specify a custom path, but the AI is looking at the default path. Solution: `export AGENT_WALLET_DIR="/your/custom/path"`. + +### `agent-wallet` command not found? + +The global installation didn't take effect. Check: +```bash +# Confirm the npm global bin directory is in your PATH +npm prefix -g +# The global bin directory is: $(npm prefix -g)/bin +``` +If the output path isn't in your `$PATH`, add it manually: +```bash +echo "export PATH=$(npm prefix -g)/bin:$PATH" >> ~/.zshrc +source ~/.zshrc +``` + +--- + +## Cross-language + +### Are key files compatible between Python and TypeScript? + +Yes. Both implementations use exactly the same encryption format. A wallet created with the CLI works directly with the Python SDK, and vice versa. + +### Do both languages produce the same signature? + +Identical. Same private key + same data = same signature. + +--- + +## OpenClaw Integration + +### Is OpenClaw required? + +No. Agent-wallet is a standalone signing tool that can be used independently via CLI or SDK. OpenClaw is simply the most convenient frontend — it lets you invoke signing using natural language, without writing any code. + +### OpenClaw says "signing failed" or "wallet not connected"? + +Troubleshoot in this order: + +1. Confirm the `AGENT_WALLET_PASSWORD` environment variable is set (run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` in the terminal where OpenClaw is running) +2. Confirm the MCP Server was started **after** the environment variable was set +3. Confirm a wallet has been initialized: `agent-wallet list` should show at least one wallet +4. If everything above checks out, try signing manually via CLI: `agent-wallet sign msg "test" -n tron` + +### Does signing in OpenClaw cost gas fees? + +Signing itself costs zero gas. Signing is purely a local cryptographic operation using your private key — it's completed entirely on your machine. Gas fees are only incurred when a signed transaction is broadcast to the blockchain. Operations like checking addresses or signing messages are always free. + +--- + +## Next Steps + +- Never written code? → [Quick Start](./QuickStart.md) +- Prefer the command line? → [CLI Reference](./Developer/CLI-Reference.md) +- Building your own agent? → [SDK Guide](./Developer/SDK-Guide.md) +- Looking for ready-made code? → [SDK Cookbook](./Developer/SDK-Cookbook.md) +- Learn about OpenClaw Extension → [OpenClaw Introduction](../Openclaw-extension/Intro.md) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md new file mode 100644 index 00000000..691c6abb --- /dev/null +++ b/docs/Agent-Wallet/Intro.md @@ -0,0 +1,177 @@ +# Introduction + +## Enjoy the Convenience of AI Agents Without the Private Key Risk + +### Your Private Key Is One File Read Away from Being Stolen + +You want your AI agent to handle on-chain work automatically — airdrop farming, token swaps, paying gas fees, scheduled transfers. To do any of that, the agent needs a "key" (your private key) to sign transactions on your behalf. + +So you save your private key as plaintext in a configuration file on your computer — anyone who can read that file has your key. + +**That's like writing your bank card number and PIN on a sticky note and walking into a room full of strangers.** + +That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read that file. Your private key has no password protection, no encryption, no access control — it's just plaintext, one app away from being gone. + +--- + +### This Isn't Hypothetical — It's Already Happening + +- **Dependency chain poisoning.** You install a useful MCP server. Three months later, one of its 200 npm dependencies gets a malicious update — quietly scanning all files for anything that looks like a private key, then sending it out. You never see it happen. By the time you notice, your wallet is empty. + +- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your configuration file is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. + +- **Git's perfect memory.** You hardcoded a key during development and deleted it later. But you committed it once, three weeks ago. It's still in `git log -p`. If that repo ever touched GitHub, even for 30 seconds, automated scrapers already found it. + +The common thread: **your private key is always exposed somewhere** — on disk, in logs, or in git history. + +--- + +## The Breakthrough: Agent-wallet — The Web3 Wallet Designed Exclusively for AI + +When you use a Web3 wallet like TronLink/MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf. + +**Agent-wallet is a local TronLink/MetaMask purpose-built for AI agents.** + +It minimizes your risk through a **"physical + password separation"** dual-lock mechanism: + +1. **Lock #1 (Physical file):** Your private key is encrypted with industry-grade algorithms and stored in a hidden folder deep in your system (`~/.agent-wallet`). +2. **Lock #2 (Authorization password):** Your AI agent only needs the "unlock password" (which you can set in an environment variable) to operate. + +**🤔 You might ask: "What if the AI leaks my unlock password?"** + +This is the most elegant part of Agent-wallet: **a leaked password ≠ stolen assets.** + +If a hacker steals only your password through a malicious plugin, they can't do anything — because they don't have your encrypted wallet file. If they steal only the wallet file without the password, it's just uncrackable gibberish. + +**A hacker would need to simultaneously break into your system, locate the hidden wallet file, AND steal the password from your environment variables to touch your funds.** The difficulty and cost of this kind of attack is orders of magnitude higher than simply scanning a plaintext private key in environment variables! + +**Bottom line: steal the file — it's useless without the password. Leak the password — it's useless without the file.** + +--- + +## How It Compares + +| | :x: Traditional (plaintext key in configuration files) | :white_check_mark: Agent-wallet | +| :--- | :--- | :--- | +| **How it works** | :x: Hand your card and PIN directly to the AI | :white_check_mark: **Give AI the password, file stays locked locally** | +| **Log / env variable leak** | :rotating_light: **Total loss** | :shield: **Only the password leaks — no file, hacker gets nothing** | +| **Encrypted file stolen** | :x: Plaintext key, stolen instantly | :shield: **No password, hacker can't open the file** | +| **Works offline?** | :warning: Depends | :white_check_mark: **100% offline signing** | + +--- + +## Three Commands, Under a Minute + +No need to understand everything first — get it running, then explore: + +**Step 1 — Install Agent-wallet:** +```bash +npm install -g @bankofai/agent-wallet +``` + +**Step 2 — Create your Agent-wallet wallet:** +```bash +agent-wallet start +``` +The wizard will initialize your Agent-wallet wallet and generate a **master password**. This password is your only "unlock key": every time your AI agent needs to sign, it uses this password to unlock the wallet. **Save it immediately in a password manager (e.g. 1Password, Bitwarden)** — it won't be shown again, and if lost, there's no way to recover it or access your assets. + +**Step 3 — Your first signature:** +```bash +agent-wallet sign msg "Hello from my AI agent" -n tron +``` + +When a hash string appears on screen — congratulations, your Agent-wallet is live. + +> Want the full step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. + +--- + +## Next: Connect Your AI Agent + +Agent-wallet is set up and signing works. Now the question is: **how do I get my AI agent to actually use this wallet?** + +Pick the path that fits you: + +### 🎮 I'm a casual user — using existing tools + +You don't need to know any code! You can directly use our ready-made "all-in-one" suite: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. + +#### 🤝 How do they work together? + +To give you total peace of mind, we designed your AI assistant as a well-organized little "company" with clear division of labor: + +- 🧠 **The Business Team (OpenClaw + Skills + MCP):** They do the legwork out in the field — quick-thinking and well-equipped, they know how to check prices, calculate slippage, and find the best quotes. But most importantly: they have zero authority to touch your funds. +- 🏦 **The CFO (Agent Wallet):** The one guarding the vault. Your private key (think: bank card PIN) is locked tight inside their local safe, completely invisible to the Business Team outside. + +Here's how a perfect secure pipeline works: + +1. You sit back in the boss's chair and say: "Buy 100 USDT worth of TRX." +2. The Business Team rushes off to check prices, calculate fees, and dutifully drafts a "transaction request form." +3. They hand the form to the **CFO (Agent Wallet)**, who sits right next to the safe. +4. The CFO verifies everything and never takes the private key out of the safe — instead, they stamp the form right there with an "approved" seal (technically called "signing"), then pass only the stamped form back out. +5. The Business Team takes the stamped form and gets it done on the blockchain. + +✨ **The key takeaway:** Throughout the entire process, the AI tools doing the legwork only ever receive the "stamped paper" — they never even catch a glimpse of the private key! This ensures AI agent can handle extremely complex tasks for you while keeping your assets absolutely secure. + +#### ⚙️ Sounds great — how do I connect them? + +Dead simple! No complex programming needed — just one thing: give the Business Team an internal passphrase to wake up the CFO. + +Just tell the tools the "master password" you generated when creating your Agent Wallet, like this: + +```bash +export AGENT_WALLET_PASSWORD='your-master-password' +``` + +That's it — one line of config! Once the passphrase is set, the entire system works seamlessly and automatically. Your AI agent will transform into a top-tier Web3 personal assistant that's both brilliantly capable and absolutely secure! + +> Can't wait to try it? Head to 👉 **[Quick Start](./QuickStart.md)** and follow along. + +### ⌨️ I'm an advanced user — managing wallets via CLI + +Need password-free signing, managing multiple wallets, or custom storage directories? Head to **[CLI Reference](./Developer/CLI-Reference.md)**. + +### 👨‍💻 I'm a developer — building my own agent + +
+Expand developer path — TypeScript / Python SDK + +Agent-wallet ships a complete SDK with TypeScript and Python support — both sharing the same interface: + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); +``` + +Same key file, same data, same signature — across both languages. + +> **[SDK Guide](./Developer/SDK-Guide.md)** — step-by-step integration guide. +> **[SDK Cookbook](./Developer/SDK-Cookbook.md)** — end-to-end real transactions: TRON transfers, BSC transfers, x402 payment signing. + +
+ +--- + +## Supported Chains + +| Chain Type | Networks | +| :--- | :--- | +| **EVM** | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain (mainnet & testnet supported) | +| **TRON** | TRON Mainnet, Nile Testnet, Shasta Testnet | + +Both chain types share the same interface — learn it once, use it everywhere. + +--- + +## Still Have Questions? + +| I'm wondering… | Go here | +| :--- | :--- | +| Will AI drain my wallet? | [FAQ](./FAQ.md) — we have a dedicated risk isolation solution | +| Never written code? | [Quick Start](./QuickStart.md) | +| Prefer the command line? | [CLI Reference](./Developer/CLI-Reference.md) | +| Building your own agent? | [SDK Guide](./Developer/SDK-Guide.md) | +| Looking for ready-made code? | [SDK Cookbook](./Developer/SDK-Cookbook.md) | diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md new file mode 100644 index 00000000..8227db33 --- /dev/null +++ b/docs/Agent-Wallet/QuickStart.md @@ -0,0 +1,188 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Quick Start + +Three steps, from zero to invoking your Agent-wallet in the OpenClaw chat box. No coding required, no gas fees — just copy and paste. + +:::tip Want CLI command details? +This page only walks you through the shortest path. For password-free configuration, managing multiple wallets, signature types, and other advanced topics, see the [CLI Reference](./Developer/CLI-Reference.md). +::: + +--- + +## Step 1: Install and Initialize Your Wallet + +### 1.1 Prepare Your Environment: Install Node.js + +Agent-wallet requires Node.js (a runtime environment, version >= 18) on your computer. + +Open a terminal (Mac users press `Command + Space` and search for "Terminal"), then type: + +```bash +node -v +``` + +- **If the output shows `v18.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. + +
+Developer preferred: Install via nvm (beginners can skip this) + +```bash +# 1. Install nvm (skip if already installed) +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 +``` + +
+ +### 1.2 Install Agent-wallet + +```bash +npm install -g @bankofai/agent-wallet +``` + +Verify the installation: +```bash +agent-wallet --help +``` + +If you see the help output, you're good to go. + +### 1.3 Create Your Agent-wallet Wallet + +Run: +```bash +agent-wallet start +``` + +The system will guide you through initializing your **Agent-wallet wallet**. The process is interactive — just follow the prompts: + +``` +? Quick start type: local_secure — Encrypted key stored locally (recommended) +Wallet ID (e.g. my_wallet_1) (default): + +Wallet initialized! +? Import source: generate — Generate a new random private key + +Wallets: +┌───────────┬──────────────┐ +│ Wallet ID │ Type │ +├───────────┼──────────────┤ +│ default │ local_secure │ +└───────────┴──────────────┘ + +Your master password: + Save this password! You'll need it for signing and other operations. + +Active wallet: default +``` + +:::caution Master password = the only key to all your assets +This password is the sole credential for decrypting all your private keys. **Lose it and it's gone forever — no backup, no backdoor, no recovery.** + +Do this right now: +1. Open your password manager (1Password, Bitwarden, etc.) +2. Create a new entry and paste in the master password +3. Don't screenshot it, don't put it in a desktop sticky note, don't text it to yourself +::: + +--- + +## Step 2: Feed the Password to Your AI (Critical!) + +For OpenClaw to automatically use your wallet, you must configure the password in its runtime environment. Select the tab matching your operating system and **just copy-paste**: + +### 2.1 Save and Activate the Password + + + + +**Step 1:** Open `~/.zshrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): + +```bash +open -e ~/.zshrc +``` + +Add this line at the very end, then save and close: + +```bash +export AGENT_WALLET_PASSWORD='your-master-password' +``` + +**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately: + +```bash +source ~/.zshrc +``` + +:::tip Why not use the echo command? +While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history. +::: + + + + +**Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): + +```bash +nano ~/.bashrc +``` + +Add this line at the very end, then save and close (in nano, press `Ctrl + O` to save, `Ctrl + X` to exit): + +```bash +export AGENT_WALLET_PASSWORD='your-master-password' +``` + +**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately: + +```bash +source ~/.bashrc +``` + + + + + + + + + +:::caution Password has special characters? Don't touch the single quotes! +Auto-generated passwords often contain `$`, `!`, and other special characters. The commands above already use single quotes to wrap the password — **just replace the text inside the quotes, never switch to double quotes**, or the shell will silently mangle the value: + +```bash +# ✅ Correct — single quotes, password saved as-is +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong — double quotes, $w0rd gets shell-expanded to empty string, password silently breaks +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # actual value becomes "P@ss!" +``` +::: + +### 2.2 Restart Your AI Backend Service + +:::danger Many people forget this step, then wonder why AI can't find the password! +You just saved a new password, but the AI assistant running in the background hasn't refreshed yet — it's still blind to the change! You need to shut it down and restart it for the new password to take effect. +::: + +Whether or not you currently have the OpenClaw backend service running, make sure to **shut it down**, then **restart it** from the same terminal window where you ran the commands above. + +--- + +## You've Completed the Full Flow + +| I want to… | Go here | +| :--- | :--- | +| Prefer the command line? | [CLI Reference](./Developer/CLI-Reference.md) | +| Building your own agent? | [SDK Guide](./Developer/SDK-Guide.md) | +| Looking for ready-made code? | [SDK Cookbook](./Developer/SDK-Cookbook.md) | +| Understand the security design | [Introduction](./Intro.md) | +| Check common questions | [FAQ](./FAQ.md) | diff --git a/docs/McpServer-Skills/MCP/Intro.md b/docs/McpServer-Skills/MCP/Intro.md index 1bd3b19d..76da6657 100644 --- a/docs/McpServer-Skills/MCP/Intro.md +++ b/docs/McpServer-Skills/MCP/Intro.md @@ -6,7 +6,7 @@ The MCP Server is designed to provide a standardized framework for interaction b MCP follows a **client-server** architecture, primarily comprising the following three core participants: -* **MCP Host**: Typically the AI application itself (e.g., Claude Code or Claude Desktop). It is responsible for coordinating and managing one or more MCP Clients. +* **MCP Host**: Typically the AI application itself. It is responsible for coordinating and managing one or more MCP Clients. * **MCP Client**: Instantiated by the MCP Host for each MCP Server. Each client maintains a dedicated connection with its corresponding MCP Server and obtains context information from the MCP Server for the host to use. * **MCP Server**: A program responsible for providing context data to MCP Clients. Servers can run locally (e.g., a filesystem server) or remotely (e.g., a TRON MCP/SUN MCP server). diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 45160178..42d75768 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -9,9 +9,9 @@ This page collects frequently asked questions when using SUN MCP Server and thei ## Connection Issues -### Claude Desktop "Cannot Connect to MCP Server" +### MCP client "Cannot Connect to MCP Server" -**Symptom:** Claude Desktop shows server unresponsive or connection refused. +**Symptom:** MCP client shows server unresponsive or connection refused. **Resolution Steps:** @@ -31,12 +31,12 @@ This page collects frequently asked questions when using SUN MCP Server and thei ``` 3. **Check JSON Format** - - Verify JSON format of `stdio.json` in Claude Desktop configuration + - Verify JSON format of `stdio.json` in MCP client configuration - Common errors: trailing commas, unmatched brackets -4. **Restart Claude Desktop** +4. **Restart MCP client** - Completely close application - - Clear cache: delete temporary files in `~/.claude` directory + - Clear client cache (method depends on your specific MCP client) - Restart application 5. **Check Server Logs** @@ -85,10 +85,7 @@ This page collects frequently asked questions when using SUN MCP Server and thei **Solution:** -1. **Configure Agent Wallet** - ```bash - export AGENT_WALLET_PASSWORD="your_secure_password" - ``` +1. **Configure [Agent Wallet](../../../Agent-Wallet/Intro)** (recommended) — set `AGENT_WALLET_PASSWORD` 2. **Or Configure Private Key (Testnet Only)** ```bash @@ -100,7 +97,7 @@ This page collects frequently asked questions when using SUN MCP Server and thei export TRON_MNEMONIC="word1 word2 ... word12" ``` -4. **Restart server** and reconnect Claude Desktop +4. **Restart server** and reconnect MCP client Verify successful configuration by checking [Full Capability List](ToolList.md) for Full Capability List. @@ -136,32 +133,9 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **Resolution Steps:** -1. **Verify Password Environment Variable** - ```bash - echo $AGENT_WALLET_PASSWORD - # Should output your password - ``` - -2. **Check Agent Wallet Directory** - ```bash - # Default location - ls ~/.agent-wallet/ - # Should contain wallet.json and other files - ``` - -3. **Reinitialize Wallet** - ```bash - # Delete existing wallet (backup important data!) - rm -rf ~/.agent-wallet/ - - # Restart server with correct password - export AGENT_WALLET_PASSWORD="your_new_password" - sun-mcp-server - ``` - -4. **Verify Password Complexity** - - Use strong password (minimum 8 characters) - - Avoid special characters, use alphanumeric combination +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. ### "Conflicting Wallet Modes" @@ -174,17 +148,17 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' ```bash # Option 1: Agent Wallet (recommended for production) -export AGENT_WALLET_PASSWORD="your_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" +export TRON_PRIVATE_KEY='your_64_hex_chars' unset AGENT_WALLET_PASSWORD unset TRON_MNEMONIC # Option 3: Mnemonic -export TRON_MNEMONIC="word1 word2 ... word12" +export TRON_MNEMONIC='word1 word2 ... word12' unset AGENT_WALLET_PASSWORD unset TRON_PRIVATE_KEY ``` @@ -195,7 +169,7 @@ unset TRON_PRIVATE_KEY unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC # Set only one -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' # Restart server sun-mcp-server @@ -290,19 +264,14 @@ sun-mcp-server 1. **Check Wallet Support** ```bash # Agent Wallet must support signTypedData - echo $AGENT_WALLET_PASSWORD # Confirm set + [[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set" ``` 2. **Verify Signature Data** - Check Permit2 request structured data - Confirm chain ID, token address, deadline correct -3. **Reinitialize Wallet** - ```bash - rm -rf ~/.agent-wallet/ - export AGENT_WALLET_PASSWORD="your_password" - sun-mcp-server - ``` +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. 4. **Use Alternate Authorization Method** ``` @@ -427,7 +396,7 @@ Check transaction hash details on https://tronscan.org for error message **Yes.** For example, can run official mainnet server and local Nile instance simultaneously. -**Configuration Example (Claude Desktop):** +**Configuration Example (MCP client):** ```json { diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index e6876113..d93472e7 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Local Privatized Deployment ## What is Local Privatized Deployment? @@ -61,29 +58,18 @@ The wallet determines which identity the AI assistant uses to perform on-chain o #### 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. - -**Install and initialize Agent Wallet:** +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. -```bash -# Install -npm install -g @bankofai/agent-wallet +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). -# Create encrypted wallet -agent-wallet start -``` -Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. - -> For detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). - -**Set environment variables:** +**Set environment variables after initializing Agent Wallet:** ```bash # Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD="" +export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` @@ -177,121 +163,60 @@ sun-mcp-server --- -### Step 3: Client Configuration - -After configuration is complete, you need to add the connection definition of SUN MCP Server in your AI client. +### Step 3: Server Running Methods -#### Find Configuration File +After wallet configuration is complete, you can run the server using one of the following methods: -Depending on your AI client, the configuration file location is as follows: +### Option A: Run directly with npx (Recommended) -| Client | Configuration File Path | -|--------|-------------| -| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | -| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | -| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` or via environment variable | - -#### Add Server Definition - -Choose the tab corresponding to your deployment method: - - - - -**Claude Desktop Configuration:** +The simplest and quickest method, no installation or cloning needed. -Add to `~/.claude/resources/mcp/servers.json`: +**Command:** -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_NETWORK": "nile" - } - } - } -} +```bash +npx -y @bankofai/sun-mcp-server ``` -**Claude Code** +**Description:** +- `npx` automatically downloads the latest version of `@bankofai/sun-mcp-server` +- `-y` flag automatically confirms prompts +- First run may take a few seconds to download -```bash -# Basic -claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server +**Run with environment variables:** -# With environment variables -claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server +```bash +TRON_NETWORK=nile npx -y @bankofai/sun-mcp-server ``` -**Cursor Configuration:** - -Add to `~/.cursor/extensions/mcp/servers.json`: - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` +### Option B: Clone from Source - +Suitable for development and custom modifications. - +**Steps:** -For running from source code. +```bash +# 1. Clone repository +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server -**Claude Desktop Configuration:** +# 2. Install dependencies +npm install -Add to `~/.claude/resources/mcp/servers.json`: +# 3. Build project +npm run build -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_NETWORK": "nile" - } - } - } -} +# 4. Run server +npx tsx src/index.ts ``` -**Cursor Configuration:** - -Add to `~/.cursor/extensions/mcp/servers.json`: - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` +**Or install globally:** - +```bash +npm install -g @bankofai/sun-mcp-server +sun-mcp-server +``` - +### Option C: HTTP Mode Run SUN MCP Server in HTTP server mode, allowing remote connections. @@ -301,39 +226,12 @@ Run SUN MCP Server in HTTP server mode, allowing remote connections. sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -**Claude Desktop Configuration:** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - -**Cursor Configuration:** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - :::warning HTTP mode is suitable for local development and testing. For remote deployment, use HTTPS and appropriate authentication. ::: - - - :::tip About Environment Variables -- **npx Run**: Environment variables are set in the `"env"` field of the configuration file, or exported directly in the terminal before running. +- **npx Run**: Export environment variables directly in the terminal before running the command. - **HTTP Mode**: When starting the HTTP server, environment variables should be exported before the startup command: ```bash @@ -341,12 +239,21 @@ export TRON_NETWORK=nile sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -- **Restart Required**: After modifying configuration, you need to restart the AI client for changes to take effect. +- **Server Configuration**: Once the server is running, configure your MCP client to connect to it. ::: --- -### Step 4: Verify Connection +### Step 4: Client Configuration + +After the server is running, you need to configure your MCP client to connect to it. Refer to your MCP client's documentation for configuration instructions. The server will be accessible at one of the following: + +- **npx/Local Build**: Typically runs as a subprocess managed by your client +- **HTTP Mode**: `http://127.0.0.1:8080/mcp` (or the host/port you specified) + +--- + +### Step 5: Verify Connection After starting the AI client, you should be able to see the tool list of SUN MCP Server. Perform the following tests to confirm the configuration is correct: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 4aa271a2..d0fa20a0 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,25 +1,20 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Official Cloud Service Access ## What is the Official Cloud Service? The official cloud service is a SUN MCP Server instance hosted by **BANK OF AI**, providing AI clients with **read-only query capabilities for SunSwap on-chain data**. -If you want your AI assistant to query token prices, pool APYs, or protocol trading volume on SunSwap, or analyze a specific address's liquidity positions — these are all read-only operations that can be completed via the official cloud service, with no local installation required and no wallet credentials needed. +If you want your AI assistant to query token prices, pool APYs, or protocol trading volume on SunSwap, or analyze a specific address's liquidity positions — these are all read-only operations that can be completed via the official cloud service, with no wallet credentials needed. **The core purpose of the official cloud service is to handle all infrastructure for you.** You only need to add a single service URL to your AI client's configuration to start interacting with SunSwap. ### Key Advantages -**1. No local installation required** — No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready in under 2 minutes. - -**2. No private key exposure risk** — Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This eliminates key leakage risks and makes team sharing straightforward. +**1. No private key exposure risk** — Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This eliminates key leakage risks and makes team sharing straightforward. -**3. Official maintenance and continuous updates** — The service always runs the latest stable version, including SunSwap protocol updates and SUN.IO API synchronization. No manual rebuilds needed. +**2. Official maintenance and continuous updates** — The service always runs the latest stable version, including SunSwap protocol updates and SUN.IO API synchronization. No manual rebuilds needed. -**4. Covers a large number of practical use cases** — Querying token prices and swap quotes, analyzing pool data and APYs, getting protocol statistics and historical metrics, viewing user liquidity positions — all the most commonly used DeFi data queries are fully supported. Only when you need to actually execute swaps or manage liquidity do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). +**3. Covers a large number of practical use cases** — Querying token prices and swap quotes, analyzing pool data and APYs, getting protocol statistics and historical metrics, viewing user liquidity positions — all the most commonly used DeFi data queries are fully supported. Only when you need to actually execute swaps or manage liquidity do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). > In short: **The official cloud service acts as a "read-only data gateway" for SunSwap** — AI clients only need the service URL to query all public data on SunSwap. @@ -31,150 +26,96 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect -Add the following MCP service endpoint to your AI client configuration: +### Quick Auto-Install -**`https://sun-mcp-server.bankofai.io/mcp`** +Simply tell your AI Agent to execute the following command: -> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. +```bash +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y +``` ---- +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. -## Client Configuration - - - - -Configuration file path: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -**Basic Config**: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` +Once installation is complete, restart your AI Agent, and you can start interacting with SunSwap via SUN MCP Server. - - +### Interactive Installation -**Add via command line**: +If you want to choose which AI tools to install to, remove the `-y` flag: ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -**Or add `.mcp.json` to your project root**: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "type": "http", - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` +:::tip +This guide demonstrates the installation process using terminal commands as an example. +::: - - +#### Installation Walkthrough -Add `.cursor/mcp.json` to your project root: +The installer will guide you through a few steps — just follow along: -```json -{ - "mcpServers": { - "sun-mcp-server": { - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` +**1️⃣ Identify the service source** - - +The installer automatically detects the remote MCP service URL and generates a server name: + +``` +◇ Source: https://sun-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: sun-mcp-server +``` -If you want to integrate SUN MCP Server into your own application, you can call it via standard HTTP requests. +**2️⃣ Choose which AI tools to install to** -**Step 1: Initialize Connection** +The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor, Cline, etc.). Use Space to select the ones you want: -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code ``` -The response will include an `mcp-session-id` header — you will need it for subsequent requests. - -**Step 2: Call a Tool** +**3️⃣ Confirm installation details** -Use the `mcp-session-id` from Step 1: +The installer displays an installation summary. Review it and select `Yes` to proceed: -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "getPrice", - "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} - }, - "id": 2 - }' +``` +◇ Installation Summary ───╮ +│ │ +│ Server: sun-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├──────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes ``` -**Step 3: Discover Available Tools** +**4️⃣ Installation complete!** -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` +When you see output like this, SUN MCP Server has been successfully installed to your selected AI tools: -:::info Session Management -- Each `initialize` creates a new session -- Sessions automatically expire after 30 minutes of inactivity -- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session -::: +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` - - +Once installation is complete, restart your AI Agent, and you can start interacting with SunSwap via SUN MCP Server. --- ## Verify Connection -After configuration, **fully quit and restart** your AI client, then enter the following test query: +Once connected, you can test by asking your AI Agent the following question: ``` Check the current prices of USDT and TRX on SunSwap diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index ba07ff4e..3bdb6064 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Quick Start The goal of this page is simple: **get you integrated and make your first DeFi query in just 1 minute.** @@ -14,69 +11,25 @@ We'll use the [official cloud service](./OfficialServerAccess.md) for this quick Before you get started, make sure you have: 1. **Node.js** >= 20.0.0 ([download link](https://nodejs.org/)) -2. **MCP Client**: Any AI client that supports MCP. For example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). +2. **MCP Client**: Any AI client that supports MCP. --- -## Add Configuration - -Choose the configuration method that matches the tool you're using: - - - - -1. Open the Claude Desktop configuration file: - - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -2. Add the following configuration in the `mcpServers` section: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. Save the file and restart Claude Desktop. +## Install - - - - -Run the following command in the terminal to add SUN MCP Server: +Simply tell your AI Agent to execute the following command: ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y ``` - - - - -1. Open the Cursor configuration file: `.cursor/mcp.json` +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. -2. Add the following in the configuration: +After the command completes, restart your MCP client. -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. Save the file and restart Cursor. - - - +:::tip Want to choose which AI tools to install to? +Remove the `-y` flag to enter interactive installation mode. See [Official Cloud Service Access](./OfficialServerAccess.md) for details. +::: --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index d515d7b8..e628182e 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -8,7 +8,7 @@ When you encounter problems, check here first. Organized by the order you're mos Connection issues usually occur during the initial configuration phase. If your AI client can't recognize the TRON tools, this is likely where the problem is. -### "Failed to connect to MCP server" in Claude Desktop +### "Failed to connect to MCP server" in your MCP client This is the most common issue. Troubleshoot in the following order: @@ -20,15 +20,11 @@ This is the most common issue. Troubleshoot in the following order: 2. **Check that npx is available**. Run `npx --version` in your terminal. If the command is not found, your Node.js installation is incomplete — reinstall it. -3. **Verify config file format**. `claude_desktop_config.json` must be valid JSON. Common mistakes include trailing commas, missing quotes, or mismatched brackets. Quickly validate with: - ```bash - cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool - ``` - If formatted JSON is printed, the format is fine. If there's an error, fix it according to the message. +3. **Verify config file format**. Your MCP client configuration file must be valid JSON. Common mistakes include trailing commas, missing quotes, or mismatched brackets. Validate your configuration file using a JSON validator. -4. **Fully quit and restart**. Closing the window is not the same as quitting — you need to fully exit Claude Desktop from the menu bar/system tray, then reopen it. On macOS, right-click the Dock icon and choose "Quit". +4. **Fully quit and restart**. Closing the window is not the same as quitting — you need to fully exit your MCP client, then reopen it. -5. **Check logs**. If none of the above resolves the issue, check Claude Desktop's log files. On macOS they're in `~/Library/Logs/Claude/` — search for entries containing "mcp" or "tron". +5. **Check logs**. If none of the above resolves the issue, check your MCP client's log files for entries containing "mcp" or "tron". ### "Connection refused" in HTTP mode @@ -57,7 +53,7 @@ This is not an error — it's by design. Write tools (transfers, staking, etc.) To unlock write tools, configure one of the three wallet modes: -- Set `AGENT_WALLET_PASSWORD` (Agent Wallet mode, recommended) +- Set `AGENT_WALLET_PASSWORD` ([Agent Wallet](../../../Agent-Wallet/Intro) mode, recommended) - Set `TRON_PRIVATE_KEY` (Private Key mode) - Set `TRON_MNEMONIC` (Mnemonic mode) @@ -91,18 +87,9 @@ If the server reports an invalid private key at startup, it's usually a format i ### "Agent wallet password incorrect" error -`AGENT_WALLET_PASSWORD` must exactly match the master password set during `agent-wallet init`. If you're not sure: - -1. **Check that the wallet directory exists**: - ```bash - ls ~/.agent-wallet/ # Default location - ``` - If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. +`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. -2. **If the password is lost**, you'll need to re-initialize. Note: this creates a new wallet — funds in the old wallet must be recovered through other means. - ```bash - agent-wallet init - ``` +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. ### TronGrid API Key not working @@ -200,25 +187,7 @@ Always develop and test on Nile first, then execute on Mainnet after confirming ### Can I use multiple TRON MCP Servers simultaneously? -Yes. Define multiple MCP Server entries in your config — for example, one connecting to the mainnet cloud service (read-only) and another connecting to a local testnet deployment (with wallet). Just use different names: - -```json -{ - "mcpServers": { - "tron-mainnet": { - "command": "npx", - "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] - }, - "tron-local": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "your-password" - } - } - } -} -``` +Yes. Define multiple MCP Server entries in your MCP client configuration — for example, one connecting to the mainnet cloud service (read-only) and another connecting to a local testnet deployment (with wallet). Configure both servers with different names in your client's MCP configuration. ### How do I update to the latest version? diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md index 054efd9c..f79c1f28 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -8,7 +8,7 @@ For example: just tell Claude "Check how much USDT this address has", and the AI This means different things to different people: -- If you are an **AI application user**, it lets you operate blockchain directly in Claude Desktop, Cursor, and other tools — as easy as everyday chat. +- 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 a **data analyst**, it turns on-chain data queries into conversation — no more writing scripts to scrape and parse. @@ -82,7 +82,7 @@ Specify the target network via the `network` parameter when calling tools, e.g., :::warning Before getting started, keep these security principles in mind — especially for operations involving real assets: -- **Never hardcode private keys**: Do not write private keys or mnemonic phrases directly in configuration files (such as `claude_desktop_config.json`). Use system environment variables or an encrypted wallet instead. +- **Never hardcode private keys**: Do not write private keys or mnemonic phrases directly in configuration files. Use system environment variables or an encrypted wallet instead. - **Test on testnet first**: Always run through and verify on Nile or Shasta testnets before performing any operation on Mainnet. - **Minimum funds principle**: The wallet configured for AI agents should only hold the minimum funds required for the task. - **Pay attention to authorization risks**: Be especially cautious with token approval (`approve`) operations — avoid granting unlimited authorization. diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 989afc6f..215e0a51 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Local Private Deployment ## What is Local Private Deployment? @@ -46,7 +43,7 @@ node --version # Should output v20.x.x or higher Before configuring your wallet, make sure to understand the following security principles: :::danger Security Warning -**Never** save private keys or mnemonic phrases directly in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`). These files are often unencrypted and could be accidentally shared or committed to Git. Always use system environment variables or encrypted wallets. +**Never** save private keys or mnemonic phrases directly in MCP configuration files. These files are often unencrypted and could be accidentally shared or committed to Git. Always use system environment variables or encrypted wallets. ::: --- @@ -67,29 +64,18 @@ The wallet determines which identity the AI assistant uses to perform on-chain o #### 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. - -**Install and initialize Agent Wallet:** - -```bash -# Install -npm install -g @bankofai/agent-wallet - -# Create encrypted wallet -agent-wallet start -``` -Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. +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 detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). -**Set environment variables:** +**Set environment variables after initializing Agent Wallet:** ```bash # Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD="" +export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` @@ -169,149 +155,28 @@ npm install npm run build ``` ---- - -### Step 4: Client Configuration - -With environment variables set and installation done, now point your AI client to the local server. - -#### Find Your Configuration File - -| Application | Operating System | Configuration Path | -| :--- | :--- | :--- | -| **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Cursor** | All | Project root: `.cursor/mcp.json` | -| **Google Antigravity** | All | `~/.config/antigravity/mcp.json` | -| **Opencode** | All | `~/.config/opencode/mcp.json` | - -#### Add Server Definition - - - - -Run the latest version directly from npm. No need to clone any repository. - -**Claude Desktop** (`claude_desktop_config.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - -**Claude Code**: - -```bash -# Basic -claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron - -# With environment variables -claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron -``` - -**Cursor** (`.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - - - - -For developers running from a cloned repository. - -**Claude Desktop** (`claude_desktop_config.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - -Replace the path with your actual cloned repository path. - -**Cursor** (`.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - - - - -If you started the server in HTTP mode (`npm run start:http`), connect via HTTP URL: +#### Option C: Run in HTTP Mode -**Claude Code**: +Start the server in HTTP mode, then connect your MCP client via the HTTP endpoint: ```bash -claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp +npm run start:http ``` -**Cursor** (`.cursor/mcp.json`): +This will start a local HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "http://localhost:3001/mcp" - } - } -} -``` +#### Configuration Notes - - +If you're configuring an MCP client to point to your local server: -:::tip About the `env` Section in Configuration -If you have already set environment variables in your system (via `~/.zshrc` or `~/.bashrc`), you can omit the `env` section from the configuration entirely — the server will automatically read system environment variables. +- **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 your MCP client does not inherit system environment variables, you'll need to set them in the `env` section. In that case, **make sure the configuration file is never shared or committed to version control**. -::: +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**. --- -### Step 5: Verify Connection +### Step 4: Verify Connection After completing configuration, **fully exit and restart** your AI client, then try: diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index f560cab3..ae00d6d4 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Official Cloud Service Access ## What is the Official Cloud Service? @@ -20,15 +17,11 @@ This is far too much overhead for users who simply want to check a balance. ### Key Advantages -**1. No local installation required** - -No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready to use. The entire process usually takes no more than 2 minutes. - -**2. No private key exposure risk** +**1. No private key exposure risk** Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This fundamentally eliminates risks like key leakage and config files accidentally committed to Git. It's especially convenient for team collaboration — any member can connect directly without key distribution or management concerns. -**3. Official maintenance and continuous updates** +**2. Official maintenance and continuous updates** The cloud service is maintained by the official team and always runs the latest stable version of TRON MCP Server. This includes: @@ -38,7 +31,7 @@ The cloud service is maintained by the official team and always runs the latest You don't need to worry about version numbers or manually run `npm install` or rebuild. -**4. Covers the vast majority of real-world use cases** +**3. Covers the vast majority of real-world use cases** The most common daily operations — checking address balances, analyzing transaction details, reading contract state, viewing the Super Representative list, monitoring on-chain events — are all read-only queries, fully supported through the cloud service. Only when you need to actually move assets (transfers, staking, contract writes) do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). @@ -52,204 +45,96 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect -To connect to the official cloud service, simply add the official **MCP service URL** to your AI client configuration: [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) - -> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. +### Quick Auto-Install -The official cloud service supports **two usage modes**: - -| Mode | Rate Limit | Description | -| :--- | :--- | :--- | -| **Without TronGrid API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | -| **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | - -Both modes use the same connection method — the only difference is the request rate limit. - ---- +Simply tell your AI Agent to execute the following command: -### Without TronGrid API Key Mode (Default) +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y +``` -No API Key configuration needed to get started. Best for: +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. -- First-time experience with TRON MCP Server -- Occasional on-chain data queries -- Teaching, demos, and feature verification +Once installation is complete, restart your AI Agent, and you can start interacting with the TRON blockchain via TRON MCP Server. -In this mode, all tools are available, but mainnet queries under high-frequency usage may trigger TronGrid's public RPC rate limits. +### Interactive Installation ---- +If you want to choose which AI tools to install to, remove the `-y` flag: -### With TronGrid API Key Mode (Recommended) +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp +``` -For frequent mainnet queries, apply for a free TronGrid API Key to get a higher request rate limit. +:::tip +This guide demonstrates the installation process using terminal commands as an example. +::: -**How to apply:** +#### Installation Walkthrough -1. Visit [trongrid.io](https://www.trongrid.io/) -2. Register an account and create a project -3. Copy the generated API Key -4. Add the API Key header in your configuration (see client configuration examples below) +The installer will guide you through a few steps — just follow along: -After configuring the API Key, your requests will go through TronGrid's authenticated channel, with more stable performance and higher throughput. +**1️⃣ Identify the service source** ---- +The installer automatically detects the remote MCP service URL and generates a server name: -## Client Configuration - - - - -Configuration file path: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -**Basic Config (No API Key)**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} ``` - -**Config with TronGrid API Key**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} +◇ Source: https://tron-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: tron-mcp-server ``` -Replace `` with your actual TronGrid API Key. +**2️⃣ Choose which AI tools to install to** - - +The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor, Cline, etc.). Use Space to select the ones you want: -**Command line:** - -```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp ``` - -**Or add `.mcp.json` to your project root**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "type": "http", - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code ``` - - +**3️⃣ Confirm installation details** -Add the following to your project root `.cursor/mcp.json`: +The installer displays an installation summary. Review it and select `Yes` to proceed: -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} ``` - - - - -If you want to integrate TRON MCP Server into your own application, you can call it via standard HTTP requests. - -**Step 1: Initialize Connection** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' +◇ Installation Summary ────╮ +│ │ +│ Server: tron-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├───────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes ``` -The response will include a `mcp-session-id` header — you'll need it for subsequent requests. +**4️⃣ Installation complete!** -**Step 2: Call a Tool** +When you see output like this, TRON MCP Server has been successfully installed to your selected AI tools: -Use the `mcp-session-id` from Step 1: - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' ``` - -**Step 3: Discover Available Tools** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! ``` -:::info Session Management -- Each `initialize` creates a new session -- Sessions automatically expire after 30 minutes of inactivity -- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session -::: - - - +Once installation is complete, restart your AI Agent, and you can start interacting with the TRON blockchain via TRON MCP Server. --- ## Verify Connection -After completing configuration, **fully exit and restart** your AI client, then enter the following test prompt: +Once connected, you can test by asking your AI Agent the following question: ``` Query the current block height of TRON mainnet diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index 1aeda6bb..75702bfe 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Quick Start The goal of this page is simple: **get you connected in 1 minute and make your first blockchain query.** @@ -13,7 +10,7 @@ We'll use the [official cloud service](./OfficialServerAccess.md) for this quick Before you begin, make sure you have the following installed: -- Any AI client that supports MCP: for example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). +- Any AI client that supports MCP - **Node.js v20.0.0 or higher** (needed for `npx` command execution) ([Node.js Download](https://nodejs.org/)) Verify your Node.js version: @@ -24,59 +21,21 @@ node --version # should output v20.x.x or higher --- -## Add Configuration - -Choose your AI client and copy in the corresponding configuration: - - - +## Install -Open your configuration file: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -Add the following content: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - -Run the following command in your terminal: +Simply tell your AI Agent to execute the following command: ```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y ``` - - +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. -Add the following to your project root `.cursor/mcp.json`: +After the command completes, restart your MCP client. -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - +:::tip Want to choose which AI tools to install to? +Remove the `-y` flag to enter interactive installation mode. See [Official Cloud Service Access](./OfficialServerAccess.md) for details. +::: --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index d5f361cf..f71eddb4 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -29,8 +29,8 @@ During testing, it is recommended to explicitly set `nile` each time to avoid un | 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 mode). | - | Read | -| `select_wallet` | Switch the active wallet at runtime (Agent Wallet mode). | `walletId` | Write | +| `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 | | `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 af00d6c3..f23b9622 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,227 +1,192 @@ -# BANK OF AI Skills +# Skill Catalog -BANK OF AI Skills is a collection of ready-to-use skill packages designed for AI Agents, covering a wide range of scenarios within the TRON ecosystem—such as DEX trading, perpetual contracts, on-chain data queries, and payment protocols. Each skill encapsulates a complete business workflow, including how to call APIs, the order of execution steps, how to handle authorization, and how to safeguard user assets, all defined within `SKILL.md` and supporting scripts. +You don't need to write code or understand the technical details. Just copy the sample prompts below into your AI chat, hit enter, and the AI takes care of the rest. -You don't need to write code — just tell the AI in natural language what you want to do, and it will automatically find and execute the corresponding skill. +:::warning Three Golden Rules +BANK OF AI SKILLS can operate on **real on-chain assets**. Blockchain transactions are **irreversible** — there's no undo button, no customer service rollback. -:::warning Before Using Any Skill, Please Read -BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactions are **irreversible** once on-chain — there's no "undo" button, no customer service rollback, and funds sent to the wrong address cannot be recovered. Remember three essential rules before using: - -1. **Private keys must never appear in chat windows or config files.** Only pass them through environment variables (like `TRON_PRIVATE_KEY`). If a private key is compromised, move assets to a new wallet immediately. -2. **Test on testnet first, then mainnet.** Every new operation must be verified first on Nile or Shasta testnet before switching to mainnet execution. -3. **Write operations require manual confirmation.** Before executing any on-chain transaction, the AI should show you the complete operation details and wait for your explicit confirmation. +1. **Never paste your private key into a chat window.** Use [Agent Wallet](../../Agent-Wallet/Intro.md) instead (think of it as opening a dedicated "payment account" for your AI — you don't hand over your bank password directly). +2. **Practice with play money first.** Every new operation should be tested on the Nile testnet — it uses free test tokens, so there's nothing to lose. +3. **Read the confirmation prompt carefully.** Before any on-chain transaction, the AI will show you the full bill and wait for your explicit "yes." ::: --- -## Available Skills Overview +## Skill Summary -| Skill | Version | Functionality | Required Credentials | -| :--- | :--- | :--- | :--- | -| **sunswap** | v2.0.0 | SunSwap DEX trading — balance, quotes, swaps, V2/V3 liquidity | `TRON_PRIVATE_KEY` | -| **sunperp-skill** | v1.0.0 | SunPerp perpetual contracts — market data, orders, positions, withdrawals | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | -| **tronscan-skill** | v1.0.0 | TronScan on-chain data queries — accounts, transactions, tokens, blocks | `TRONSCAN_API_KEY` | -| **x402-payment** | v1.4.0 | x402 protocol payments — calling paid APIs and paid agents | `TRON_PRIVATE_KEY` or `EVM_PRIVATE_KEY` | -| **recharge-skill** | v1.1.1 | BANK OF AI balance queries, order history, TRC20 recharge via MCP | `BANKOFAI_API_KEY` | +| Skill | What It Does | What Key/Credential Do I Need? | +| :--- | :--- | :--- | +| **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) | +| **x402-payment** | On-chain "pay-first" auto-settlement | Wallet credentials | +| **recharge-skill** | Balance, order history, account top-up | BANK OF AI API key | ---- +### 🔑 Where Do I Get These Keys? How Do I Set Them Up? + +If you just want the AI to look up public data (like token prices or block height), you don't need to configure anything — just start using it. -## Installation +But if you want to unlock advanced features or trading, grab the keys you need below: -The simplest installation method is using **OpenClaw Extension** — install all components with one command, automatically configure the skills directory, and the AI is ready out of the box: +**1. Wallet Credentials (for spending money and trading)** -```bash -# Method 1: Direct run (for trusted sources) -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +- **Where to get it:** You don't need to apply anywhere — this is simply your TRON wallet private key. +- **How to set it up:** We've prepared two options in [Quick Start](./QuickStart.md#-want-the-ai-to-trade-for-you) — pick whichever suits you: + - **Option 1 (Recommended):** Use [Agent Wallet](../../Agent-Wallet/QuickStart.md) — visual interface, 2 minutes, private key encrypted and never exposed. + - **Option 2:** Paste your private key directly into your system config file (the "notepad method") — great for power users or quick testing. -# Method 2: Check script before running (recommended) -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +**2. TronScan API Key (your VIP pass for data queries)** -After installation, skills will be placed in the `~/.openclaw/skills/` directory, and OpenClaw will automatically discover and load them. +You can query data without this, but if you query too fast, the system may rate-limit you. With a key, you get the VIP fast lane. -Verify that skills are ready after installation: +- **Where to get it (completely free):** Go to [TronScan](https://tronscan.org/), register an account, and click to generate a key. +- **How to set it up:** Follow the same "notepad method" in [Quick Start — "Want the AI to Trade for You?"](./QuickStart.md#-want-the-ai-to-trade-for-you) and paste `TRONSCAN_API_KEY` in the same way. -```bash -ls ~/.openclaw/skills -``` +**3. SunPerp API Keys (for perpetual contract trading)** -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. +- **Where to get them:** Go to [SunPerp](https://sunperp.com/), connect your wallet, then generate an API Key and Secret in your account settings. +- **How to set them up:** Use the same "notepad method" to paste `SUNPERP_ACCESS_KEY` and `SUNPERP_SECRET_KEY` into your config file. -### Installation on Other Platforms +**4. BANK OF AI API Key (for balance checks and account top-ups)** -If you use Claude Code, Cursor, or other AI tools that support Skills, you can also install manually: +- **Where to get it:** Go to [chat.bankofai.io/key](https://chat.bankofai.io/key) and log in to get your key. +- **How to set it up:** Use the notepad method to paste `BANKOFAI_API_KEY`. -**Claude Code:** +--- -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ -``` +## Haven't Installed Yet? -Claude Code will automatically load these skills when it starts. +Head over to **[Quick Start](./QuickStart.md)** — it takes about 1 minute. Come back here to pick your skills once you're set up. -**Cursor:** +--- -```bash -# Clone to project root -git clone https://github.com/BofAI/skills.git .cursor/skills -``` +## sunswap — Swap Tokens, Check Prices, Manage Pools {#sunswap} -In Cursor Chat, use the `@` symbol to reference specific `SKILL.md` files for context, or add the skills path to `.cursorrules`. +Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. -**Universal Method (any AI tool):** +**Completely safe — looking only, no spending:** -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` +> What's the current price of TRX? -Then explicitly tell the AI to read a skill file in your conversation: +> How much TRX can I get for 100 USDT on SunSwap? -``` -Please read ~/bofai-skills/sunswap/SKILL.md and help me check the current price of TRX. -``` +> Show me the top 10 highest-APY pools on SunSwap. ---- +> Show me all my current SunSwap V3 liquidity positions. -## Verify Installation +**Requires your confirmation (AI shows the bill first):** -After installation, starting with read-only operations is the best entry point — no private keys needed, zero risk, perfect for getting familiar with how skills work. +> Swap 100 TRX for USDT on the SunSwap Nile testnet. -In your client, enter: +> Add 100 TRX and 15 USDT liquidity to the TRX/USDT pool on SunSwap V2. -``` -How much TRX can I get for 100 USDT on SunSwap? -``` +> Collect fee rewards from V3 position #12345. -``` -Help me check the current market data for BTC-USDT perpetual contract. -``` +**Real-world scenarios:** + +> Looking for arbitrage? Try: "Is it worth swapping 100 USDT to TRX on SunSwap right now?" + +> Interested in yield farming? Try: "Which V3 pool on SunSwap has the highest APY? Give me an analysis." + +> Looking to buy the dip? Try: "What's TRX's price trend over the last 7 days?" --- -## Usage Examples for Each Skill +## sunperp-skill — Perpetual Contract Trading {#sunperp-skill} -Each example is marked with an operation type: -- 🟢 **Read-only** — produces no on-chain transactions, no private key needed -- ⚠️ **Write operation** — initiates on-chain transactions, requires user confirmation before execution +Want to trade contracts? This skill handles market data, opening/closing positions, stop-loss, and withdrawals. Built-in safety: max 20x leverage, mandatory stop-loss — if losses exceed 5%, the AI automatically closes your position to prevent liquidation. -### sunswap +**Completely safe — looking only, no spending:** -``` -# 🟢 Query balance -Help me check my TRX and USDT balances. +> What's the current price, 24h change, and funding rate for BTC-USDT perpetual? -# 🟢 Query price -What's the current price of TRX? +> What's my SunPerp account balance and available margin? -# 🟢 Get swap quote -How much TRX can I get for 100 USDT on SunSwap? +> What open positions do I have? Show entry price, unrealized P&L, and liquidation price. -# ⚠️ Execute swap -Swap 100 TRX for USDT on SunSwap Nile testnet. +**Requires your confirmation:** -# ⚠️ Add liquidity -Add 100 TRX and 15 USDT liquidity to the TRX/USDT pool on SunSwap V2. +> Open 1 BTC-USDT long at market price on SunPerp with 10x leverage, 5% stop loss. -# 🟢 View V3 positions -Help me check all my current SunSwap V3 liquidity positions. +> Close all my BTC-USDT positions. -# ⚠️ Collect fees -Help me collect fee rewards from V3 position #12345. -``` +> Withdraw 10 USDT from SunPerp to my on-chain address. -### sunperp-skill +**Real-world scenarios:** -``` -# 🟢 View market data -What are the current price, 24h change, and funding rate for BTC-USDT perpetual contract? +> Stuck in a bad position? Try: "What's BTC's funding rate right now — should I go long or short?" -# 🟢 View account -What's my SunPerp account balance and available margin? +> Want to manage risk? Try: "Lower my BTC-USDT leverage to 5x and set stop-loss to 3%." -# 🟢 View open positions -What open positions do I have? Show entry price, unrealized P&L and liquidation price. +> Want the big picture? Try: "List all available perpetual contracts, sorted by 24h volume." -# ⚠️ Open position -Open 1 BTC-USDT long position at market price on SunPerp with 10x leverage, set 5% stop loss. +--- + +## tronscan-skill — On-Chain Data Detective {#tronscan-skill} -# ⚠️ Close position -Close all my BTC-USDT positions. +Want to know what's happening on-chain? This skill looks up accounts, transactions, tokens, blocks, and network stats. **Pure read-only, completely safe, costs nothing, needs no credentials.** The perfect first skill to get started. -# ⚠️ Withdraw -Withdraw 10 USDT from SunPerp to my on-chain address. -``` +> Look up the full account info and holdings for address TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf. -### tronscan-skill +> Show me the details of this transaction: abc123... -``` -# 🟢 Account query -Help me query the complete account info and holdings for address TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf. +> Show the top 10 TRC20 tokens by market cap. -# 🟢 Transaction query -Query the details of this transaction hash: abc123... +> Give me a TRON network overview: current TPS, Super Representatives, total accounts. -# 🟢 Token info -Show the top 10 TRC20 tokens by market cap. +> Show the last 20 USDT transfers from address TXX... -# 🟢 Network overview -Give me a TRON network overview: current TPS, number of Super Representatives, total accounts. +**Real-world scenarios:** -# 🟢 Transfer history -Query the last 20 USDT transfers from address TXX... -``` +> Found a new token and want to check if it's legit? "Check the holder distribution and contract verification for token TXX..." -### x402-payment +> Tracking a whale? "Show all transactions above 100,000 USDT from address TXX... in the last 24 hours." -``` -# ⚠️ Call paid endpoint -Use x402 protocol to call this paid agent endpoint: https://api.example.com -``` +> Verifying a transfer? "Did this transaction actually succeed: abc123...?" -### recharge-skill +--- -``` -# 🟢 Query balance -How much balance does my BANK OF AI account have? +## x402-payment — On-Chain "Pay-First" Auto-Settlement {#x402-payment} -# 🟢 Query orders -Show my recent BANK OF AI order history. +Some APIs and AI agents require on-chain payment before use. This skill uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — the AI detects the charge, completes the on-chain payment, gets the result, and reports back. It always asks for your confirmation before paying. -# ⚠️ Recharge -Recharge 1 USDT to my BANK OF AI account. +**Requires your confirmation:** -# ⚠️ Recharge (Chinese) -给 BANK OF AI 充值 1 USDT -``` +> Use x402 protocol to call this paid agent endpoint: https://api.example.com （replace with the actual paid endpoint URL you want to call） --- -## Recommended Learning Path +## recharge-skill — BANK OF AI Account Management {#recharge-skill} + +Check your balance, view order history, or top up your account. + +**Completely safe — looking only, no spending:** + +> How much balance does my BANK OF AI account have? + +> Show my recent BANK OF AI order history. + +**Requires your confirmation:** -If you're just starting with BANK OF AI Skills, following this order makes it smoother: +> Recharge 1 USDT to my BANK OF AI account. + + +--- + +## Recommended Learning Path -Step 1: Read-only queries - → Start with tronscan-skill to query accounts and check transactions, get familiar with skill interaction - → Use sunswap to check prices and quotes, no real trades +**Start here — zero risk, zero config:** Use tronscan-skill to look up accounts and check transactions. Use sunswap to check prices and get quotes. Read-only, no credentials needed. -Step 2: Testnet write operations - → Execute swaps, add liquidity, open contracts on Nile testnet - → Confirm AI behavior matches expectations, parameters pass correctly +**Next — practice with play money:** Set up your wallet (see [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md)), then test swaps and liquidity operations on the Nile testnet. Confirm the AI behaves exactly as expected. -Step 3: Mainnet small transactions - → Verify the complete workflow with small amounts of capital +**Then — mainnet with small amounts:** Run the full flow with a small amount of real funds to make sure everything works. -Step 4: Mainnet production use - → Daily operations, adjust parameters and skill combinations as needed +**Finally — daily use:** Run your regular operations, adjust parameters, and combine skills as needed. --- ## Next Steps -- Want to understand how Skills work? → [What Are Skills?](./Intro.md) -- Encountering issues? → [FAQ](./Faq.md) +- Want to understand how skills work under the hood? → [What Are Skills?](./Intro.md) +- Running into issues? → [FAQ](./Faq.md) - Using OpenClaw Extension? → [OpenClaw Extension Documentation](../../Openclaw-extension/Intro.md) diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index d21c64d0..d6e933c3 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -1,204 +1,188 @@ # FAQ -The following questions are arranged in the order you're most likely to encounter them. +Questions are ordered by urgency — the ones you're most likely to hit first are at the top, concepts at the bottom. --- -## Foundational Concepts +## Something Went Wrong -### What's the difference between Skill and MCP Server? +### The AI says "skill not found" or gives a completely wrong answer -This is the most common question. In one sentence: **MCP Server is a toolbox, Skill is an instruction manual.** +Tell the AI exactly where to find the skill file: -MCP Server provides atomic-level tools — like "check balance", "initiate transfer", or "call contract". Skills tell the AI how to combine these tools to complete a full task — for example, "swap tokens on a DEX" requires executing balance check, get quote, verify approval, and execute swap in sequence. Skills define this workflow. +``` +Please read ~/.openclaw/skills/sunswap/SKILL.md and check the current price of TRX. +``` -### Do Skills require separate installation? +If that works, the issue was just the AI's auto-matching. Add clearer keywords next time, like "use the sunswap skill." -No additional application needed. A Skill is just a folder — you only need to place it in a directory that your AI tool can read, and the AI will automatically discover and use it. +If that doesn't work either, check these in order: -However, if a skill contains a `scripts/` directory (as sunswap, sunperp-skill, and tronscan-skill do), you need to run `npm install` once in that directory to install script dependencies. This step is automatic when using OpenClaw Extension. +1. Does the skill directory exist? Run `ls ~/.openclaw/skills` in your terminal. +2. Are dependencies installed? Go to the skill folder and run `npm install` (e.g., `cd ~/.openclaw/skills/tronscan-skill && npm install`). +3. Are credentials configured? See [How do I configure credentials?](#how-do-i-configure-credentials) below. -### Which AI tools support Skills? +### Installation failed -Currently supported: **OpenClaw** (most complete integration), **Claude Code**, **Cursor**, and any AI assistant that can read local files (using explicit invocation method). +Skills require a program called "Node.js" on your computer (similar to how some apps need Java). If installation fails, it's most likely missing or outdated. ---- +**Simplest fix:** Go to [nodejs.org](https://nodejs.org/), download the latest LTS version (install it like any normal app — just click "Next" through the wizard), then try again. + +:::tip Already have Node.js but still getting errors? +Run `node --version` in your terminal. Skills require **v20 or higher**. If your version is too old, download the latest from the official site and install over the old one. +::: -## Installation and Configuration +### How do I know the skills installed successfully? -### How do I know the skill installed successfully? +Run this in your terminal: ```bash ls ~/.openclaw/skills ``` -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. +You should see directory names like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`. -Then verify in OpenClaw: +Then verify in your AI chat: ``` -Read the sunswap skill and tell me what this skill can do. +Read the sunswap skill and tell me what it can do. ``` -If the AI accurately describes the skill content, installation was successful. - -### What if npm install fails? +If the AI accurately describes the skill's capabilities, you're good to go. -First confirm your Node.js version: +--- -```bash -node --version # needs >= 18 -``` +## Is My Money Safe? -If the version is too old, use nvm to upgrade: +### Will the AI secretly transfer my funds? -```bash -nvm install 18 -nvm use 18 -``` +**No.** Every operation that involves spending money will pause first and show you the full "bill" — what it's doing, how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** -Then run `npm install` again in the skill directory. +That said, we recommend using a dedicated wallet with only the funds you intend to trade. Don't load your life savings — just like you wouldn't carry all your cash to the grocery store. -### How do I configure credentials (private keys/API keys)? +### What if my private key is compromised? -Configure through environment variables. Depending on which skills you use, add the corresponding variables in `~/.zshrc` or `~/.bashrc`: +**First — don't panic. Check which network you were using.** -```bash -# TRON wallet (needed for sunswap, sun-mcp-server, x402-payment) -export TRON_PRIVATE_KEY="your_private_key" -export TRONGRID_API_KEY="your_TronGrid_API_Key" +If you've been using the **Nile testnet** (which we strongly recommend for beginners), then congratulations — testnet tokens are free play money. Losing them means nothing. Just create a new wallet and move on. -# SunPerp contract trading (needed for sunperp-skill) -export SUNPERP_ACCESS_KEY="your_SunPerp_Access_Key" -export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" +If it's a **mainnet** private key, act immediately: -# TronScan data queries (needed for tronscan-skill) -export TRONSCAN_API_KEY="your_TronScan_API_Key" +1. Stop using your current AI tool. +2. Create a new wallet. +3. Transfer all assets from the old wallet to the new one. +4. Update all your configurations to point to the new key. +5. Revoke token approvals on all protocols (SunSwap, SunPerp, etc.) connected to the old wallet. -# BANK OF AI (needed for recharge-skill) -export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" -``` +:::tip Prevention is better than cure +Use [Agent Wallet](../../Agent-Wallet/Intro.md) from the start instead of plaintext private keys. Agent Wallet locks your key in an encrypted local vault — even if someone sees your environment variables, they can't open the vault without the encryption password. Two locks broken at once? Extremely unlikely. +::: -After adding them, run `source ~/.zshrc` to apply, then restart your AI tool. +### Why does the AI ask for confirmation before every transaction? ---- +By design. Every time the AI wants to spend your money, it shows you the full details first: what operation, which tokens and amounts, which chain, estimated fees. -## Usage Issues +**This is your last safety checkpoint before real money moves. Don't skip it.** -### The AI says "skill not found" or behaves unexpectedly. What should I do? +### How do I switch between testnet and mainnet? -First switch to **explicit invocation** — directly tell the AI where the skill file is: +Just tell the AI: ``` -Please read ~/.openclaw/skills/sunswap/SKILL.md and help me check the current price of TRX. +Swap 100 TRX for USDT on the Nile testnet. ``` -If explicit invocation works normally, the issue is with implicit triggering matching. Try adding clearer keywords in your task description, like "use sunswap skill", "use tronscan-skill". +The AI switches to testnet automatically. **We strongly recommend testing every new operation on testnet first** — testnet tokens are free, so there's nothing to lose. -If explicit invocation also doesn't work, check if the skill directory exists, npm install is complete, and environment variables are set correctly. +### Why is there a difference between the quoted and actual price? -### How do I switch between testnet and mainnet? +Because the blockchain doesn't pause while you're reading the quote. Between seeing the quote and confirming the transaction, a few seconds to a few minutes may pass, and the price can shift. -Use the `--network` parameter to specify. **Strongly recommend testing every new operation on testnet first**: +The AI handles this with a two-step approach: it shows you a quote first, then right before submitting, it fetches the latest price and uses slippage protection to ensure you don't get a drastically worse deal. -```bash -# Testnet (default, try this first) -node scripts/swap.js TRX USDT 100 --network nile +If extreme volatility causes a transaction to fail, try increasing the tolerance: "Swap 100 TRX for USDT with 1% slippage." -# Mainnet (only after confirming everything works) -node scripts/swap.js TRX USDT 100 --network mainnet --execute -``` +--- -You can also tell the AI directly in conversation: +## Configuration -``` -Help me swap 100 TRX for USDT on the Nile testnet. -``` +### How do I configure credentials? -### Why does the AI require confirmation before executing? +**The simplest and safest method (strongly recommended): use [Agent Wallet](../../Agent-Wallet/QuickStart.md).** Think of it as a password-protected vault with a simple visual interface — just follow the prompts to enter your keys. Set it up once, and you'll never have to wrestle with config files again. -This is a safety mechanism by design — all write operations (operations involving on-chain transactions) must be explicitly confirmed by the user before execution. +
+Backup method for power users: environment variables -The AI will show in the confirmation prompt: operation type, tokens and amounts involved, target network, estimated Gas, and slippage. This gives you a chance to verify the operation matches expectations before your funds are actually used. **Don't skip this step, and never enable automatic execution of write operations.** +If you're comfortable with the command line, you can store credentials in your shell config file. -### What does dry-run (simulation) mean? +**Mac:** -Scripts in sunswap and other Skills support running without the `--execute` flag — this is dry-run mode. It simulates the execution flow, checks balance and approval status, and gets quotes, but doesn't broadcast any on-chain transactions. +1. Open Terminal (press `Command + Space`, search for `Terminal`) +2. Type `nano ~/.zshrc` and press Enter — you'll see a basic text editor +3. Use arrow keys to scroll to the bottom, paste the lines you need from below (important: do NOT delete the double quotes `"` around each value, and make sure they're straight quotes, not curly quotes) +4. Press `Ctrl + X`, then `Y`, then Enter to save +5. Close the terminal, reopen it, and restart your AI tool + +Add the variables for the skills you need: ```bash -# Dry-run: simulate check, no execution -node scripts/swap.js TRX USDT 100 +# SunSwap trading (needed for swap operations) +export TRON_PRIVATE_KEY="your_private_key" +export TRONGRID_API_KEY="your_TronGrid_API_key" -# Real execution -node scripts/swap.js TRX USDT 100 --execute -``` +# SunPerp perpetual contracts +export SUNPERP_ACCESS_KEY="your_SunPerp_Access_Key" +export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" -Running dry-run first is a good habit when unsure. +# TronScan data queries +export TRONSCAN_API_KEY="your_TronScan_API_Key" -### Why is there a difference between the quoted price and the actual execution price? +# BANK OF AI account +export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" +``` -Because there's a time difference between getting the quote and actual execution, during which the price may change. The sunswap script uses a two-step quoting strategy to handle this: the first quote is shown to you for confirmation; after you confirm, it fetches the latest quote right before submitting the actual transaction, then uses the latest quote to calculate the `amountOutMin` as slippage protection. +
-If extreme market volatility causes transaction failure, increasing the slippage tolerance (`--slippage 1.0`) usually fixes it. +### Which AI tools support Skills? ---- +Currently: **OpenClaw** (most seamless), and any AI assistant that can read local skill files. -## Security and Advanced +--- -### Can I modify a skill? +## Customization -Yes. Edit `SKILL.md` or scripts in `scripts/` directly, and the AI will read the latest version on the next call. You can change operation steps, add custom rules, adjust safety parameters, or add new examples. +### Can I modify a skill's rules? -Modifying `sunperp-skill/resources/sunperp_config.json` lets you adjust leverage limits and stop-loss defaults: +Absolutely. Skills are just regular folders on your computer. Edit anything you want. -```json -{ - "safety": { - "max_leverage": 20, - "stop_loss": { - "required": true, - "default_percent": 5, - "max_percent": 25 - } - } -} -``` +For example, if you think 20x leverage is still too risky for perpetual trading, open `~/.openclaw/skills/sunperp-skill/resources/sunperp_config.json` and lower the number. Your AI, your rules. -### How is skill versioning managed? +### How do I uninstall or update? -Skill versions are marked by the `version` field in the YAML frontmatter of `SKILL.md`. When using OpenClaw Extension, you can specify a specific version via the `GITHUB_BRANCH` environment variable: +**Uninstall:** Delete the folder. ```bash -GITHUB_BRANCH=v1.4.10 ./install.sh # Install specific version -GITHUB_BRANCH=main ./install.sh # Use latest main branch +rm -rf ~/.openclaw/skills/sunswap ``` -The default uses the `v1.4.12` tag version. +**Update:** Re-run the install command. It will update all skills to the latest version. -### What if my private key is compromised? +```bash +npx skills add https://github.com/BofAI/skills +``` -**Act immediately, don't hesitate:** +--- -1. Stop using the current AI tool -2. Create a new TRON/EVM wallet address -3. Transfer all assets to the new address (check for pending transactions in the current account first) -4. Update all environment variables to point to the new private key -5. Revoke token approvals on all protocols using the old wallet -6. Review the transaction history of the old wallet to confirm whether any unauthorized operations have occurred +## Concepts (for the Curious) -Agent Wallet (encrypted storage) is safer than plaintext private keys — even if environment variables are compromised, attackers still need additional encryption keys to access funds. If you manage significant capital, consider switching to Agent Wallet mode. +### What's the relationship between "skills" and the "toolbox"? -### How do I uninstall or update a skill? +In one sentence: **The toolbox gives the AI abilities. Skills teach it how to use them.** -**Uninstall:** +The toolbox (MCP Server) provides individual capabilities — "check balance," "send transfer." A skill teaches the AI how to string these capabilities together into a complete workflow — "swap tokens" requires checking balance, getting a quote, confirming price, then executing. The skill defines that sequence. -```bash -rm -rf ~/.openclaw/skills/sunswap # Delete specific skill -``` +Analogy: Toolbox = knives, pots, and a stove. Skill = the recipe. -**Update (reinstall the latest version):** +### Will installing lots of skills slow things down? -```bash -cd openclaw-extension -./install.sh # If a skill with the same name exists, the installer will ask if you want to overwrite -``` +No. The AI only loads a "table of contents" at startup (like glancing at shelf labels). It reads the full skill content only when you actually use it. Hundreds of skills? Still lightning fast. diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index c9e0c2dc..eef6b17f 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -1,143 +1,120 @@ -# What Are Skills? +# Introduction -You may have already used MCP Server to let an AI assistant check balances, send transfers, and invoke contracts. But you'll notice that some tasks aren't "call a tool once and done" — for example, swapping tokens on a DEX requires checking your balance first, getting a quote, approving the transaction, then executing the swap. Each step involves decision-making and parameter handling. +Welcome to BANK OF AI SKILLS! -**Skills exist precisely for this kind of multi-step task.** +In the past, exploring Web3 was a grind full of barriers: watching charts, calculating slippage, switching wallets, checking contracts... one wrong step and you'd hit an error. We decided to put an end to that hassle. -A Skill is a "task handbook" — it's not a tool itself, but rather instructions that tell the AI how to combine a series of tools in the correct order with the correct parameters to complete a full business workflow. +In a nutshell, BANK OF AI SKILLS is a set of **"AI skill packs"** purpose-built for the TRON ecosystem. Ordinary AI tends to fumble complex Web3 trades — blindly copying steps and riddled with errors. Our Skills provide the AI Agent with a set of **"standardized workflows"** — like having a personal trader who already comes with hands-on experience in DEX trading, contract lookup, and perpetual swaps. Just chat naturally, and from pre-flight checks and parameter calculations to transaction bundling — all the error-prone grunt work — Skills automatically orchestrate everything flawlessly behind the scenes. --- -## The Difference Between Skills and MCP Server +## 🌟 Why You Need Professional Skills -Many people ask this question when first encountering Skills: what's the difference from MCP Server? +Today's AI chatbots are smart — if you push them to write a transfer script or hook them up to an API to try their luck on-chain, they can pull it off. But if you actually let them loose on your real money without guardrails, it often turns into a disaster. -| | MCP Server | Skill | -| :--- | :--- | :--- | -| **Essence** | Tool service | Task handbook + script collection | -| **Purpose** | Provide AI with **atomic capabilities to get things done** | Teach AI **how to combine capabilities to complete a task** | -| **Example** | `mcp-server-tron` provides the `send_trx` tool | `sunswap` tells AI how to use multiple tools to execute a DEX swap | -| **Analogy** | Kitchen knives, pots, and stoves | A recipe | - -Simply put: **MCP Server is a toolbox, Skill is an instruction manual.** A Skill tells the AI which drawer to open, which tool to grab, and what steps to follow to complete the task. +In the high-stakes reality of Web3 trading, an AI needs more than "smart and capable" — it must "know the business" and be "absolutely reliable." The core edge of BANK OF AI SKILLS is that we took a regular copy-paste AI and upgraded it into a **Web3 personal assistant** with built-in error prevention, deep business workflow expertise, and strict risk control guardrails. ---- +With Skills, your AI gains decisive advantages: -## What Does a Skill Look Like? +| Real Trading Pain Point | ❌ Regular AI Chatbot | 🦸‍♂️ With BANK OF AI SKILLS (personal assistant) | +| :--- | :--- | :--- | +| **Complex trade execution** (error prevention & SOP) | Guesses its way through, easily gets stuck. It can handle single-step commands, but for complex swaps, it often doesn't know you need to Approve first — leading to blind operations and error crashes. | Built-in "veteran driver navigation." Enforces the perfect sequence: check balance → verify approval → get quote → confirm → execute. Never misses a step. | +| **Fund safety & risk control** (blow-up prevention) | Blindly obedient, no guardrails. It doesn't understand financial common sense — if you casually say "open 100x leverage," it will generate that dangerous command without hesitation. | Built-in "business-level safety locks." Hard-coded risk limits (e.g., max 20x leverage, mandatory stop-loss) — dangerous operations get blocked on the spot. | -A Skill is a folder with a very simple structure: +**In one sentence:** A regular AI is a straight-A "top student" on paper, but full of holes the moment it hits real operations. An AI with BANK OF AI SKILLS is like a seasoned pro who already comes with DEX trading, contract lookup, and perpetual swap skills — never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. -| File/Directory | Purpose | Required? | -| :--- | :--- | :--- | -| `SKILL.md` | Core instruction document — where AI learns how to execute the task | **Yes** | -| `scripts/` | Executable scripts — AI calls these to perform specific operations | Optional | -| `resources/` | Reference data — contract addresses, token lists, config files, etc. | Optional | -| `package.json` | npm dependency declaration (required if the Skill has scripts) | Optional | +### 🎬 Real Scenario: You Want to "Buy Some TRX with 50 USDT" -The top of `SKILL.md` contains YAML Frontmatter that declares basic information about the Skill: +Let's say you give the AI the simplest possible command: "Buy some TRX with 50 USDT." -```yaml ---- -name: SunSwap DEX Trading -description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. -version: 2.0.0 -dependencies: - - node >= 18.0.0 - - tronweb -tags: - - defi - - dex - - swap - - tron ---- +**❌ With a regular AI:** -# SunSwap DEX Trading Skill +It hears the command and might generate a chunk of buggy code, or blindly try its luck on-chain. The result is usually **BOOM — transaction failed.** Then it throws a wall of incomprehensible error messages at you (something like `transfer amount exceeds allowance`). -## 🚀 Quick Start -...(specific operation instructions) -``` +Why? Because in the Web3 world, you must **"Approve"** a token before spending it. A regular AI has plenty of IQ but zero "industry common sense" — it skips the prerequisite step, crashes, and leaves you staring at gibberish. -The `name` and `description` fields are key for AI to identify and match skills — the more accurate they are, the more easily the AI can find them at the right moment. The main content is the specific operation instructions with no format restrictions — it can be text explanations, code examples, parameter tables, or anything that helps the AI understand. +**✅ With BANK OF AI SKILLS installed:** ---- +After receiving your command, it doesn't just execute — it automatically runs through a standard operating procedure behind the scenes. Here's what your experience looks like: -## Why Not Just Give All Instructions Directly to the AI? +1. **Auto balance check:** "Boss, I checked — you have 100 USDT in your wallet. Plenty of funds." +2. **Preemptive troubleshooting:** "I noticed you haven't approved USDT for SunSwap yet. I've prepared the Approve request — please confirm." +3. **Precise quote:** "Approval successful! At the latest price, 50 USDT gets you roughly 350 TRX. I've automatically set 1% slippage protection. Ready to buy?" -The key question for understanding Skills design: if we just tell the AI how to operate, why not just say it in the conversation? +In this scenario, you said one sentence, and the Skill quietly handled 5 high-barrier steps behind the scenes: check balance → detect missing approval → submit approval → calculate slippage → fetch quote. That's the difference between a **"regular chatbot AI"** and a **"professional Web3 butler."** -This approach has two fundamental problems: +--- -**Context window is limited and expensive.** If we stuff the complete content of all Skills into every conversation, the instructions alone would consume huge amounts of tokens, making the AI slower and dramatically increasing costs per conversation. +## 🛡️ Your Assets Are Absolutely Safe with Skills -**Scattered attention.** When the AI faces detailed explanations for dozens of Skills, it struggles to focus on the current task and easily confuses rules and parameters across different skills, leading to errors. +**"Can Skills spend my money without permission?"** +No. Every operation that involves spending money has a built-in **intercept-confirm mechanism** — the AI pauses first and shows you the full "bill": how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** Think of it as a diligent assistant who needs your signature on every expense report. -Skills solve this with **three-tier progressive loading** — only loading what's needed when it's needed. +**"Will installing lots of Skills slow things down?"** +No. Skills use an **on-demand, lightweight architecture** — the AI only loads a "table of contents" at startup (like glancing at labels on a bookshelf). It reads the full skill content only when you actually use it. Hundreds of Skills? Still lightning fast. --- -## Three-Tier Progressive Loading - -Think of Skills as a library's retrieval system: +## What Can Skills Do for You? -**Tier 1: Shelf Index (ultra-lightweight)** +Five 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. -When starting up, the system only exposes to the AI the `name` and `description` of all Skills — like labels on shelves. These "index cards" are tiny, so loading even hundreds of Skills at once creates no burden. Through this tier, the AI decides "which skill do I need for this task?" +### 💱 Execute DEX Trades -**Tier 2: Operation Manual (loaded on demand)** +Check prices, compare rates, even swap tokens in one go. -Only when the AI confirms it needs a particular Skill does it read the complete `SKILL.md` content. This step triggers only when a skill is matched, providing the AI with specific execution steps, parameter requirements, edge conditions, and common error handling. +> 🗣️ "How much TRX can I get for 100 USDT on SunSwap right now?" -**Tier 3: Tool Execution (real-time invocation)** +💡 For more advanced features, see: [**sunswap** (DEX Trading Guide)](./BANKOFAISkill.md#sunswap) -Only when the task execution reaches a point requiring actual operations (like querying on-chain balance, executing a swap), the AI calls the corresponding script or MCP tool to do the substantive work, then returns the result to the conversation. +### 📈 Trade Perpetual Contracts -This design lets the system manage large numbers of Skills while maintaining low latency and high accuracy. +View market data, open and close positions on SunPerp. Built-in safety lock: max 20x leverage, mandatory stop-loss on every position — keeps you from blowing up your account. ---- +> 🗣️ "What's BTC's funding rate right now? Open a 5x long position with a 5% stop-loss." -## How Does the AI Find and Use a Skill? +💡 For more parameter settings, see: [**sunperp-skill** (Perpetual Contract Safety Officer)](./BANKOFAISkill.md#sunperp-skill) -The AI selects and executes a Skill in four steps: +### 🕵️ Query On-Chain Data -**Step 1: Intent Recognition** +Look up accounts, transactions, and check if a new token is legit. Pure read-only, completely safe, costs nothing. -You send a request (e.g., "Help me swap 100 USDT for TRX on SunSwap"), the AI parses the intent, scans the descriptions of all mounted Skills, and finds the best match. +> 🗣️ "Check the holder distribution for that new token — is it controlled by a whale?" -**Step 2: Rule Internalization** +💡 For more query dimensions, see: [**tronscan-skill** (On-Chain Data Detective)](./BANKOFAISkill.md#tronscan-skill) -The AI reads the Skill's `SKILL.md`, understanding the execution steps, parameter formats, network selection, and security constraints. +### ☕ Auto-Settle On-Chain Paid Services -**Step 3: Tool Execution** +When the AI needs to call a paid on-chain service or data API, it uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — no manual QR scanning or wallet switching needed. -Following the manual's guidance, the AI proceeds step by step — calling scripts to check balance, get quotes, verify approvals, execute the swap — waiting for your confirmation at critical points. +> 🗣️ "Use the x402 protocol to call this paid agent endpoint: https://api.example.com" (replace with the actual paid endpoint URL you want to call) -**Step 4: Result Feedback** +💡 For payment and authorization details, see: [**x402-payment** (On-Chain Auto-Settlement)](./BANKOFAISkill.md#x402-payment) -After completion, the AI presents results in an easy-to-read format. When information is missing or execution fails, it asks proactively. +### 🏦 Manage BANK OF AI Account ---- +Check your BANK OF AI balance and top up with a single sentence. -## Two Ways to Invoke Skills +> 🗣️ "How much balance do I have? Go ahead and recharge 5 USDT." -You can trigger a Skill in two ways: +💡 For top-up and withdrawal rules, see: [**recharge-skill** (Account Manager)](./BANKOFAISkill.md#recharge-skill) -**Explicit Invocation** — directly tell the AI which Skill to read, suitable for scenarios requiring deterministic behavior: +--- -``` -Read the sunswap skill and help me check how much TRX I can get for 100 USDT on SunSwap. -``` +## 🎯 Are These Skills Right for Me? -**Implicit Triggering** — describe the task and let the AI auto-match, suitable for everyday conversation: +- **👶 I'm a total beginner:** Perfect! No more wrestling with candlestick charts, slippage settings, or gas fee calculations. Just tell the AI what you want in plain language — it does the hard work and feeds you the results. +- **🕴️ I'm an experienced trader:** Tired of staring at screens all day? Let the AI batch-monitor data and calculate yields, freeing up your time and energy. You focus on strategy — let the AI handle the tedious execution. +- **🍉 I just want to explore:** Absolutely fine! Read-only skills like "On-Chain Data Detective" are 100% free — no wallet needed, zero risk, full access to the Web3 magic. -``` -Check how much TRX I can get for 100 USDT on SunSwap right now. -``` +--- -The difference lies in control: explicit invocation ensures the AI uses the Skill you specified; implicit triggering is more natural but if the description isn't clear enough, the AI might match the wrong Skill. When execution doesn't meet expectations, switching to explicit invocation usually solves the problem. +
---- +**Ready? Just 2 steps, less than 1 minute.** -## Next Steps + +Go to Quick Start + -- Want to know what Skills BANK OF AI provides? → [BANK OF AI Skills](./BANKOFAISkill.md) -- Have questions? → [FAQ](./Faq.md) +
diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md new file mode 100644 index 00000000..9163ca32 --- /dev/null +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -0,0 +1,213 @@ +# Quick Start + +Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than **1 minute**. No private keys, no configuration — just install and start talking. + +--- + +## Step 1: Install the Skills + +### Quick Auto-Install + +Simply tell your AI Agent to execute the following command: + +```bash +npx skills add https://github.com/BofAI/skills -y -g +``` + +The `-y` flag skips all interactive prompts and installs all available Skills by default. The `-g` flag enables global installation (available across all projects). Once complete, it will show ✅ Global installation complete! along with the full list of installed Skills. + +### Interactive Installation + +If you want to choose which Skills to install and the installation scope, remove the `-y -g` flags: + +```bash +npx skills add https://github.com/BofAI/skills +``` + +:::tip +This guide demonstrates the installation process using terminal commands as an example. +::: + +#### Installation Walkthrough + +The installer will guide you through a few steps — just follow along: + +**1️⃣ Confirm tool installation** + +Terminal will ask you to install the `skills` package. Type `y` and press Enter: + +``` +Need to install the following packages: + skills@1.4.6 +Ok to proceed? (y) y +``` + +**2️⃣ Select which Skills to install** + +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 6 skills +│ +◇ Select skills to install (space to toggle) +│ Multi-Sig & Account Permissions, recharge-skill, +│ SunPerp Perpetual Futures Trading, SunSwap DEX Trading, +│ TronScan Data Lookup, x402-payment +``` + +:::tip Select all +Unless you're sure you only need specific skills, install them all. Skills use an on-demand architecture — unused skills consume zero resources. +::: + +**3️⃣ Choose which AI tools to install to** + +The installer auto-detects AI tools on your computer (e.g., Cursor, Claude Code, Cline, etc.). Use Space to select the ones you want: + +``` +◇ 43 agents +◇ Which agents do you want to install to? +│ Amp, Antigravity, Cline, Codex, Cursor, Deep Agents, +│ Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp +``` + +**4️⃣ Choose installation scope** + +Select `Project` (current project only) or `User` (globally available across all projects): + +``` +◇ Installation scope +│ Project +``` + +**5️⃣ Review security assessment & confirm** + +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 -- -- -- │ +│ TronScan Data Lookup -- -- -- │ +│ x402-payment Med 1 alert Med │ +│ │ +├──────────────────────────────────────────────────────────╯ + +◇ Proceed with installation? +│ Yes +``` + +**6️⃣ Installation complete!** + +When you see output like this, all Skills have been successfully installed to your selected AI tools: + +``` +◇ Installed 6 skills ────────────────────────╮ +│ │ +│ ✓ Multi-Sig & Account Permissions (copied) │ +│ ✓ recharge-skill (copied) │ +│ ✓ SunPerp Perpetual Futures Trading (copied)│ +│ ✓ SunSwap DEX Trading (copied) │ +│ ✓ TronScan Data Lookup (copied) │ +│ ✓ x402-payment (copied) │ +│ │ +├─────────────────────────────────────────────╯ + +└ Done! +``` + +:::tip Optional: Install find-skills +After installation, you may be prompted to install `find-skills` — a helper that lets your AI automatically discover and suggest new skills. We recommend selecting `Yes`. +::: + +### Verify Installation + +Open your AI chat and type: + +``` +Read the sunswap skill and tell me what it can do. +``` + +If the AI accurately describes the skill's capabilities — congratulations, installation is complete! + +--- + +## Step 2: Talk to Your AI + +Open your AI chat and copy-paste any of these: + +> Give me a TRON network overview: current TPS, number of Super Representatives, total accounts. + +In seconds, the AI calls the tronscan-skill and returns a complete on-chain data report. + +**This is completely safe — it's only "looking" at data. It doesn't touch your wallet or spend a single coin.** + +Try a few more: + +> How much TRX can I get for 100 USDT on SunSwap? + +> Show me the top 10 TRC20 tokens by market cap. + +> What's the current price, 24h change, and funding rate for BTC-USDT perpetual contract? + +If the AI responds with real data — congratulations, your AI is up and running! + +--- + +## 💰 Want the AI to Trade for You? + +Everything above is "look but don't touch" — the AI can look up data and compare prices, but it doesn't have permission to spend a single coin of yours. That's by design: you stay in full control. + +When you're ready to let the AI execute swaps, open positions, or manage liquidity, you need to give it a "wallet key." + +We've prepared two ways to hand over the key — pick whichever suits you: + +### Option 1: Open a Dedicated "Payment Account" for the AI (Strongly Recommended, Safest) + +We recommend using **Agent Wallet**. Think of it as opening a dedicated payment account for your AI. You don't expose your bank password (plaintext private key) in a file on your computer — instead, you set an encryption password. Every time it wants to spend money, it shows you the full bill first and only proceeds after you say "yes." + +👉 Head over to [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md) to set it up (visual interface, about 2 minutes). + +### Option 2: Paste Your Private Key Directly (For Power Users or Quick Testing) + +If you don't want to install another tool and just want to start trading right away, you can paste your private key into a simple config file on your computer — like editing a notepad: + +1. In Terminal (the black window), type `open -e ~/.zshrc` and press Enter. +2. A text editor window will pop up. Scroll to the very bottom, start a new line, and paste your TRON private key: + ```bash + export TRON_PRIVATE_KEY='your_real_or_testnet_private_key' + ``` + ⚠️ Important: Don't forget the double quotes on both sides! +3. Press `Command + S` to save, then close the editor. + +:::danger Critical Step +No matter which option you chose, you must **completely close and reopen your AI tool** for it to pick up the new key! +::: + +--- + +## 🎮 Key Is Set — How Do I Start Trading? + +Once you've configured your key and restarted your AI, you can start giving it trading commands right away! + +:::caution Golden Rule for Beginners: Practice with Play Money First +Before running any real transaction, **always test on the Nile testnet first**. Testnet tokens have zero real-world value — you can experiment freely without risking anything. +::: + +Open your AI chat and say your first trading command: + +> Swap 100 TRX for USDT on the Nile testnet. + +The AI will quickly calculate the price, estimate fees, then pause and ask: "Ready to execute?" Just reply "yes," and the on-chain transaction completes automatically! + +Once you've practiced on testnet and confirmed the AI behaves exactly as expected, simply drop the words "Nile testnet" from your commands — and it will trade with real funds on mainnet. + +--- + +## Next Steps + +- See what each skill can do → [Skill Catalog](./BANKOFAISkill.md) +- Something not working? → [FAQ](./Faq.md) diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md index 9666845f..b1a5ea6e 100644 --- a/docs/Openclaw-extension/FAQ.md +++ b/docs/Openclaw-extension/FAQ.md @@ -1,219 +1,93 @@ -# FAQ & Troubleshooting +# FAQ -When you encounter problems, check here first. Organized by the most likely issues you'll encounter: installation problems, connection issues, credential problems, runtime problems, and finally some general questions. +Don't panic when you see an error — it's usually just a small setting that's not configured properly. We've listed the most common issues in order of frequency: --- -## Installation Problems +## Errors During Installation -### Installer reports error "command not found: node" +### Error Says "command not found: node" or "npm install Failed" -The installer requires Node.js v18.0.0 or higher. Check if it's installed: +**Plain English**: Your computer doesn't have Node.js installed, or the version is too old. -```bash -node --version -``` +**How to fix**: Go to the [Node.js official website](https://nodejs.org/) and download the latest stable version (LTS, v20 or higher recommended). Install it like any regular software by clicking "Next" all the way through. Then close the terminal window and run the installation command again. -If not installed or version is too old, download and install the latest LTS version from [nodejs.org](https://nodejs.org/). After installing Node.js, the `npx` command will also be available. +### Error Says "command not found: python3" -### Installer reports error "command not found: python3" +**Plain English**: Your computer is missing a basic runtime environment called Python. -The installer uses Python to process JSON configuration files. macOS typically comes with Python 3; on Linux, install via package manager: +**How to fix**: Go to the [Python official website](https://www.python.org/downloads/) and download and install it. -```bash -# Ubuntu/Debian -sudo apt install python3 +### AgentWallet (AI Vault) Installation Failed -# macOS (via Homebrew) -brew install python3 -``` +**How to fix**: -### Installer warning "OpenClaw not found" - -The installer detected that `~/.openclaw` directory doesn't exist. This means OpenClaw might not be installed or was installed in a non-standard location. - -The installer will ask if you want to continue — you can choose to proceed (MCP Servers and Skills will still be configured), but OpenClaw may not auto-load them on startup. Recommend first completing installation from the [OpenClaw official repository](https://github.com/openclaw). - -### Skills clone failed - -If `git clone` fails, common causes include: - -- **Network issues**: Check if you can access GitHub. Try `git clone https://github.com/BofAI/skills.git` to test manually. -- **Git not installed**: Run `git --version` to confirm. -- **Specified branch/tag doesn't exist**: If you set the `GITHUB_BRANCH` environment variable, confirm the branch or tag actually exists. - -Skills clone failure won't interrupt the entire installation — MCP Server configuration remains intact. You can install Skills manually later. - -### npm install failed - -When installing Skills, some Skills (like sunswap, x402-payment) need to run `npm install` to install dependencies. If it fails: - -- Check network connectivity (npm needs to access registry.npmjs.org) -- Confirm Node.js version >= 18 -- Try running manually: - ```bash - cd ~/.openclaw/skills/sunswap # or other Skill directory - npm install - ``` - -npm install failure won't interrupt the installer — it will issue a warning but continue. That Skill's functionality may be limited until dependencies are successfully installed. - ---- - -## Connection Issues - -### Can't see blockchain tools in OpenClaw after startup - -**Most common cause**: OpenClaw wasn't restarted. After modifying mcporter.json, you must completely exit and restart OpenClaw. - -If you still can't see them after restarting: - -1. **Check mcporter.json format**: - ```bash - python3 -m json.tool ~/.mcporter/mcporter.json - ``` - If there's a JSON syntax error, fix the format issues and restart. - -2. **Check mcporter.json contents**: Confirm there are Server entries under `mcpServers` for what you installed. - -3. **Manually test MCP Server**: - ```bash - npx -y @bankofai/mcp-server-tron - ``` - If this command starts normally (shows logging output), the MCP Server itself is fine; the issue is in OpenClaw's configuration reading. - -### Only query tools available, no write tools like transfers - -This is by design. Write tools only appear after wallet credentials are configured. Check if any of these are set: - -- Environment variable `TRON_PRIVATE_KEY` (mcp-server-tron) -- Environment variable `PRIVATE_KEY` (bnbchain-mcp) -- `env.TRON_PRIVATE_KEY` or `env.PRIVATE_KEY` for corresponding Server in mcporter.json - - -### MCP Server startup timeout - -If OpenClaw times out starting an MCP Server, it may be that npx is downloading packages too slowly. The first run downloads packages from npm, which can take tens of seconds. - -Speed this up by pre-downloading: - -```bash -npx -y @bankofai/mcp-server-tron --help -npx -y @bnb-chain/mcp@latest --help -``` - -After downloading completes, subsequent startups will use cache and be much faster. +1. Double-check that your Node.js version is new enough. +2. Sometimes it's simply a network timeout — wait a couple of minutes and run the installation command again. +3. If it keeps getting stuck, try manually deleting the `~/.agent-wallet` folder and starting over from scratch. --- -## Credential Issues - -### "Invalid private key" error - -**TRON private key** should be a 64-character hexadecimal string, with or without `0x` prefix. +## Installation Finished, But AI Acts Clueless -**EVM private key** should have `0x` prefix. The installer automatically adds `0x` to private keys without it, but if you manually edit config files, ensure the format is correct. +### AI Says "I Don't Have Blockchain Tools" or "I Don't Know What SunSwap Is" -Common mistakes: -- Extra spaces, newlines, or quote nesting -- Invisible characters when copying from elsewhere +**Most likely cause**: You were too eager after installation and **didn't restart the OpenClaw software**. -Validation: Import the private key into the appropriate wallet (TronLink or MetaMask) to confirm validity. +**How to fix**: Completely quit OpenClaw (on Mac press `Command+Q`), then reopen it so the AI can reload its new brain. -### TronGrid API Key not working +### AI Can Fetch Data, But Answers Are Messy and Often Wrong? -1. **Is variable name correct?**: Must be `TRONGRID_API_KEY` (not `TRON_API_KEY`) -2. **Is Key still valid?**: Log in to [trongrid.io](https://www.trongrid.io/) to check status -3. **Is it properly loaded?**: If set in environment variables, confirm you ran `source ~/.zshrc` +**Most likely cause**: The underlying AI model version you're using is too weak. It's like asking a grade-schooler to do high school math — it's not that they're not trying, they just don't have the capacity. +**How to fix**: Open OpenClaw settings and upgrade to a more powerful model version. The stronger the model, the more accurately AI understands your commands and the fewer mistakes it makes when calling tools. -### BANK OF AI API Key invalid +### Why Can Others Send Transfers While My AI Can Only Read Data? -Check contents of `~/.mcporter/bankofai-config.json` (or `~/.bankofai/config.json`): +**Reason**: Your AI is currently in ultra-safe "read-only mode." This is because you skipped the AgentWallet configuration during installation and didn't provide it with wallet keys. -```bash -cat ~/.mcporter/bankofai-config.json -``` - -Confirm the `api_key` field contains a valid Key. Note that recharge-skill has a credential priority order (CLI arguments > environment variables > `bankofai-config.json` in working directory > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`); if you set different values in multiple places, you might read the unexpected one. +**How to fix**: Run the installation script again. At the AgentWallet setup level, follow the prompts carefully to properly configure your wallet. After configuring and restarting, transfer and trading functions will be activated. --- -## Runtime Problems - -### Rate limiting (429 errors) - -Mainnet's public RPC has strict rate limits. Solutions: - -- **Configure TronGrid API Key**: After free registration, set `TRONGRID_API_KEY`, significantly increasing quota -- **Use testnet**: Nile and Shasta testnets have fewer restrictions -- **Reduce concurrent queries**: In prompts, avoid having the AI execute large numbers of queries simultaneously - -### Skill execution failed +## Passwords and Security Concerns -If a Skill errors, troubleshoot in this order: +### Private Key Was Entered Wrong or Error Says "Invalid Private Key" -1. **Check if dependencies are installed**: - ```bash - cd ~/.openclaw/skills/ - npm install # if there's package.json - ``` +**Reason**: The current installer uses AgentWallet to manage wallets, so you generally don't need to manually enter private keys anymore. However, if you're using the BNB Chain toolbox (bnbchain-mcp) and manually configuring a private key, you might have accidentally copied an extra space or line break. -2. **Check Node.js version**: Some Skills require >= 18.0.0. +**How to fix**: Carefully copy it again. EVM (BNB/Ethereum) private keys should start with `0x` — if you're manually editing the file, make sure you don't miss that prefix. -### Transaction failed +### AI Reports "Rate Limited" or "429 Error" -Common reasons for on-chain transaction failures: +**Plain English**: You're making AI query data too fast, and the free network channel thinks you're a bot and temporarily blocked you. -- **Insufficient balance**: TRX balance doesn't cover gas fees (bandwidth/energy) -- **Insufficient energy**: Smart contract calls (including TRC20 transfers) consume energy -- **Account not activated**: New TRON addresses need to receive one TRX first to activate -- **Insufficient approval**: TRC20 token transfers may require prior approval +**How to fix**: -Use mcp-server-tron's `get_transaction_info` tool to see the specific reason for transaction failure. +1. **Quick fix**: Wait a few minutes before asking again. +2. **Permanent fix**: Go to [TronGrid](https://www.trongrid.io/) and apply for a free dedicated API Key. Enter this key during installation, and AI will be able to use the VIP express lane. --- -## General Questions - -### Can I install only some components? - -Yes. The installer lets you selectively install at each stage. For example, you can install only mcp-server-tron without other MCP Servers, or only sunswap Skill while skipping others. - -### Can I run the installer multiple times? - -Yes. The installer uses deep merge strategy for mcporter.json and won't overwrite existing configurations. For Skills, if a Skill with the same name already exists at the target location, it will ask if you want to overwrite. - -### How do I completely uninstall? +## Tinkering Freely (Uninstall & Reinstall) -OpenClaw Extension has no automatic uninstaller. Manual uninstall steps: +### Can I Install Just One Skill Without the Others? -1. **Remove MCP Server configuration**: Edit `~/.mcporter/mcporter.json`, remove corresponding Server entries -2. **Delete Skills**: Delete Skill folders in installation directory (default `~/.openclaw/skills/`) -3. **Delete credential files**: - ```bash - rm -f ~/.x402-config.json - rm -f ~/.mcporter/bankofai-config.json - rm -f ~/.bankofai/config.json - rm -f ~/.clawdbot/wallets/.deployer_pk - ``` -4. **Clean environment variables**: Remove related export statements from `~/.zshrc` or `~/.bashrc` +Absolutely! When the installation wizard reaches Level 4, it will list all skills. Just use the Space key to check only the ones you want, leave the rest unchecked, and press Enter to confirm. -### Which operating systems are supported? +### I'm Done With It — How Do I Uninstall? -The installer is a Bash script supporting: -- **macOS** (Intel and Apple Silicon) -- **Linux** (Ubuntu, Debian, CentOS, etc.) -- **Windows**: Requires WSL (Windows Subsystem for Linux) to run +The simplest brute-force method: Open your file manager, find the `~/.openclaw/skills/` directory, delete the skill folder(s) you no longer want, then restart the AI software — they'll be completely gone. -### What's the difference from TRON MCP Server's official cloud service? +### I Messed Everything Up — Can I Reinstall? -The [official cloud service](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md) is a remote-hosted read-only MCP Server, requiring no local installation. OpenClaw Extension runs the MCP Server locally, and with private keys configured, unlocks full read-write capabilities. +Reinstall anytime! Don't worry about breaking your computer. -If you only need to query on-chain data, cloud service is simpler. If you need transfers, contract writes, or want to use Skills (like SunSwap trading), you need OpenClaw Extension. +- **Option 1 (Normal installation)**: Run the script again and it will automatically patch whatever's missing. +- **Option 2 (Clean install)**: If you want to start completely from scratch, choose this one. It will wipe all your old toolboxes, skills, and configurations clean, giving you a fresh new environment. To prevent accidental triggers, it will ask you to manually type `CLEAN` to confirm. --- -## Next Steps +## Still Can't Figure It Out? -- Start fresh → [Quick Start](./QuickStart.md) +👉 Go back to **[Quick Start](./QuickStart.md)** and follow along from step one again — that usually solves 99% of the problems. diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index d4814867..b0756b3e 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -1,62 +1,60 @@ # Introduction -## What is OpenClaw Extension? +Make your AI understand blockchain with one click. -OpenClaw Extension is a toolkit developed by **BANK OF AI** that equips [OpenClaw](https://github.com/openclaw) (an open-source AI assistant) with **blockchain interaction capabilities**. Once installed, your AI assistant can directly manage on-chain assets — check balances, initiate transfers, invoke smart contracts, and swap tokens on DEXs — all through natural language conversation. +Have you ever wished that checking on-chain data, swapping tokens, or viewing balances didn't require opening dozens of web pages or staring at complex apps? -Traditionally, enabling an AI to interact with blockchain requires you to manually set up MCP Servers, manage configuration files, and install various tools individually. OpenClaw Extension packages all of this into an interactive installer — run one command, follow the prompts to select the components you need, and within minutes your AI assistant will have multi-chain operation capabilities. +All you need to do is send a simple message — just like chatting with a friend — and let your AI assistant handle all the heavy lifting. + +**OpenClaw Extension is the "one-click installer" that makes this magic happen.** --- -## Core Vision +## How Does the Magic Work? -OpenClaw Extension aims to build a financial infrastructure for the AI agent economy — enabling every AI agent with independent financial capabilities: +Previously, AI was just a "know-it-all" that could only talk the talk. To make it actually do things for you, our installer equips it with two core weapons: -- **Earn Revenue**: Receive payments for tasks and services through standard interfaces like the x402 protocol -- **Autonomous Spending**: Independently pay for compute, data, and storage resources -- **Agent Interconnection**: Facilitate direct financial transactions and settlements between agents (A2A) -- **DeFi Interaction**: Seamlessly interact with decentralized finance protocols and smart contracts +### 🛠️ 1. Toolbox (MCP Server) — Giving AI "Hands" ---- +This is the cable that connects AI to the blockchain. Once installed, AI gains the ability to directly read from and write to the blockchain. -## What Does It Include? +Currently supported: -OpenClaw Extension consists of two main categories of components: **MCP Servers** and **Skills**. You can choose which components to enable at installation time. +- **TRON Toolbox**: Check balances, send transfers, and interact with the TRON ecosystem. +- **BNB Chain Toolbox**: Supports multi-chain operations on BSC, Ethereum, and more. +- **Top-up Assistant**: Helps you remotely top up your BANK OF AI account. -### MCP Server — On-Chain Operation Capabilities +### 🧠 2. Skill Packs (Skills) — Giving AI a "Brain" -MCP Servers are bridges between your AI assistant and the blockchain, providing on-chain operation capabilities through the [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) standard interface. Currently supports MCP Servers for two blockchain chains plus one remote recharge service: +Having hands isn't enough — AI needs to know how to handle tasks step by step. Skill packs are the pre-written "recipes" we've prepared. -| MCP Server | Target | Core Capabilities | -| :--- | :--- | :--- | -| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | -| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | -| **bankofai-recharge** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | +For example, the **"sunswap" skill** teaches AI: "When the user wants to swap tokens, first check the price, then calculate the fees, and finally send the bill to the user for confirmation — never spend money recklessly." -### Skills — Pre-built Workflows +--- -Skills are encapsulated business process templates. Unlike individual tools provided by MCP Servers, a single Skill can chain multiple operations together to complete complex tasks — for example, "swap tokens on SunSwap" involves checking prices, verifying balances, executing the swap, and confirming results, all handled by one Skill. +## 🌟 How Great Is the Experience After Installation? -| Skill | Functionality | -| :--- | :--- | -| **sunswap** | SunSwap DEX trading including balance queries, quotes, swaps, and liquidity management | -| **sunperp-skill** | SunPerp perpetual futures trading — market data, orders, positions, leverage, withdrawals | -| **tronscan-skill** | Query on-chain data via TronScan API (accounts, transactions, tokens, blocks, network statistics) | -| **x402-payment** | x402 payment skill for calling paid agents and APIs | -| **recharge-skill** | BANK OF AI balance and order queries, plus TRC20 recharge via MCP | +Once installed, your AI instantly transforms into an incredibly professional personal Web3 assistant. Try giving it commands like these: +> **"Check if TRON energy fees are expensive right now."** +> +> **"How much TRX can I get for 100 USDT on SunSwap? Is it worth it after fees?"** +> +> **"How much balance is left in my wallet? Also check my holdings of that meme coin from yesterday."** + +It will chew through all the boring code and data and serve it up to you in plain language. --- -## Who Should Use This? +## Is This for Me? -- **OpenClaw Users**: Want your AI assistant to interact directly with blockchain without manually setting up MCP Servers -- **Web3 Developers**: Need a quick on-chain development environment to debug contracts and query data using natural language -- **AI Agent Builders**: Need to equip automation agents with multi-chain operation capabilities -- **DeFi Users**: Want to use your AI assistant to trade on SunSwap or manage liquidity +- **I'm a beginner**: Perfect! If you don't want to deal with code and just want to use plain language to have AI help you check data and make trades, this was tailor-made for you. +- **I'm a Web3 veteran**: Tired of opening web pages and connecting wallets every day? Want a personal trading assistant on call 24/7? It can save you tons of time watching charts. --- -## Next Steps +## Can't Wait? + +Don't hesitate — the entire installation process is as simple as microwaving a meal, taking just a few minutes. -- Want to get started immediately? → [Quick Start](./QuickStart.md) +👉 **[Go to Quick Start and upgrade your AI!](./QuickStart.md)** diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md index 291c504b..4f2d2a6a 100644 --- a/docs/Openclaw-extension/QuickStart.md +++ b/docs/Openclaw-extension/QuickStart.md @@ -1,146 +1,133 @@ # Quick Start -The goal of this page is: **Get you up and running with a complete installation and your first blockchain query in just a few minutes.** - -The installer is interactive, guiding you to select which MCP Servers and Skills to install, then automatically completing all configuration. You just need to follow the prompts. +Our goal: **Spend a few minutes following the wizard, clicking a few buttons, and get your AI to successfully fetch its first piece of on-chain data.** --- -## Prerequisites +## 🕹️ Prerequisites -Before running the installer, ensure the following tools are ready: +Before you begin, make sure the following basic software is installed on your computer (if not, download and install them from their official websites just like any regular software): -| Requirement | Description | Verification Command | Download | -| :--- | :--- | :--- | :--- | -| **OpenClaw** | Your open-source AI assistant | Check if `~/.openclaw` directory exists | [OpenClaw official repository](https://github.com/openclaw) | -| **Node.js v18+** | Required to run MCP Servers | `node --version` | [Node.js official site](https://nodejs.org/) | -| **Python 3** | Used by installer to handle JSON configuration | `python3 --version` | [Python official site](https://www.python.org/downloads/) | -| **Git** | Clone Skills repository | `git --version` | [Git official site](https://git-scm.com/) | +1. **OpenClaw**: Your AI assistant software. +2. **Node.js** (must be v20 or above): The runtime environment for skill packs. *(Extremely important — older versions will definitely cause errors!)* +3. **Git**: A small tool used to download skill packs. +4. **Python 3**: A helper used by the installation wizard to process configuration files. --- -## Running the Installer +## 🚀 Step 1: One-Click Installation + +Open the "Terminal" on your computer (that black window). -### Method 1: One-Click Install (Recommended) +- **Mac:** Press `Command + Space`, type `Terminal` in the search box, and hit Enter. + +**Copy the entire line below**, paste it into the terminal, and press Enter: ```bash curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash ``` -### Method 2: Install from Source +🚑 **First Aid: Got an error right after pressing Enter?** If the screen says `command not found: node` or `python3`, it means your computer is missing the prerequisites mentioned above. 👉 [Click here to see how to fix it](./FAQ.md#error-says-command-not-found-node-or-npm-install-failed) -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +If there are no errors, an English wizard will appear on screen. Think of it as a text-based mini-game with 4 levels: -Once started, the installer automatically checks environment dependencies (Node.js, npx, Git, Python). If any are missing, it will alert you immediately. +### 🟢 Level 1: Choose Installation Mode ---- +The screen will ask you which mode to use. Type `1` (normal installation) on your keyboard, then press Enter. This is the most hassle-free option and preserves your previous settings. -## Installation Process Details +### 🟢 Level 2: Configure "AI's Personal Vault" (AgentWallet) -The installer consists of two main phases, each with interactive selection at every step. +The wizard will automatically install a tool called AgentWallet, which securely stores your AI's wallet keys. -### Phase 1: Select and Configure MCP Servers +If you're a beginner, just close your eyes and press Enter all the way through — the default values are perfectly fine. -The installer displays all available MCP Servers and asks which ones you want to install: +(🚑 Got stuck with an error? 👉 [Click here to see how to fix AgentWallet installation failures](./FAQ.md#agentwallet-ai-vault-installation-failed)) -``` -📦 Available MCP Servers: - 1) mcp-server-tron - TRON blockchain interaction - 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) bankofai-recharge - Remote BANK OF AI recharge MCP +### 🟢 Level 3: Pick Your Toolbox (Give AI "Hands") -Select servers to install (e.g., 1,2,3 or 'all'): -``` +The screen will list options like TRON (mcp-server-tron). Use the `↑` `↓` arrow keys to move, press **Space** to check, and press **Enter** to confirm. -> **Note on bankofai-recharge**: This is a remote MCP that connects directly to `https://recharge.bankofai.io/mcp`. No local credentials are needed — the installer configures the endpoint automatically. +⚠️ **Heads up**: The wizard might suddenly ask you for an API Key! -For each selected server, the installer continues by asking how you want to store credentials: +- **What's that?** It's a VIP pass — having one means data queries won't be throttled. +- **I don't have one right now?** Just press Enter to skip! Leaving it blank is totally fine and won't affect your installation at all. -- **Option 1: Save to Configuration File** — Keys stored in plaintext in `~/.mcporter/mcporter.json`. Convenient but lower security. -- **Option 2: Use Environment Variables (Recommended)** — Keys read from system environment variables, not written to any files. +### 🟢 Level 4: Pick Your Skill Packs (Give AI a "Brain") -If you choose to save to a configuration file, the installer will ask for specific key values (private keys, API Keys, etc.). If you choose environment variables, the installer will tell you which variables need to be set. +The screen will list skills like sunswap (token swapping), tronscan (data lookup), etc. Use **Space** to check and **Enter** to confirm. -> **Tip**: If you just want to quickly experience the features, you can skip key configuration for now (just press Enter to leave it empty). Without a private key, the MCP Server will run in read-only mode, and you can still query on-chain data. +If you see any prompts asking for keys that you don't understand, just press Enter to skip them all. -### Phase 2: Select and Install Skills +When `Installation Complete!` lights up at the bottom of the screen — congratulations, you've passed all levels! -The installer clones the [Skills repository](https://github.com/BofAI/skills) from GitHub, automatically discovers all available Skills, and asks you to select: +--- + +## 🎉 Step 2: Restart and Witness the Magic + +After installation, there's one step you absolutely cannot skip: **Completely close your OpenClaw software, then reopen it.** + +🚑 **First Aid: AI acting clueless?** If it says "I don't know what SunSwap is," 99% of the time it's because you didn't restart. 👉 [Click here to see how to properly restart](./FAQ.md#ai-says-i-dont-have-blockchain-tools-or-i-dont-know-what-sunswap-is) + +Open the chat window and send your AI its first command: ``` -🔧 Available Skills: - 1) recharge-skill - BANK OF AI account query and recharge - 2) sunperp-skill - SunPerp perpetual futures trading (TRON) - 3) sunswap - SunSwap DEX trading skill - 4) tronscan-skill - TRON blockchain data lookup - 5) x402-payment - Agent payment protocol (x402) - -Select skills to install (e.g., 1,2,3 or 'all'): +Check the current block height on the TRON mainnet. ``` -Then choose the installation location: - -| Option | Path | Use Case | -| :--- | :--- | :--- | -| **User-level (Recommended)** | `~/.openclaw/skills/` | Shared across all projects | -| **Workspace-level** | `.openclaw/skills/` | Used only by current project | -| **Custom Path** | Directory you specify | Special requirements | +If it thinks for a few seconds and then reports back a number — awesome! Your AI has successfully connected to the blockchain! -Some Skills have additional credential requirements, which the installer will prompt you for during installation: +Try another one: -- **recharge-skill** — Requires BANK OF AI API Key (`BANKOFAI_API_KEY`) -- **sunperp-skill** — Requires SunPerp API keys (`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`) -- **tronscan-skill** — Prompts you to set `TRONSCAN_API_KEY` environment variable in your shell -- **sunswap** — Prompts to configure TRON private key (if not configured earlier) +``` +How much TRX can I get for 100 USDT on SunSwap right now? +``` --- -## Verifying the Installation +*(That covers the beginner essentials. If you've got the hang of it, keep reading below 👇)* -After installation completes, **restart OpenClaw**, then in your conversation, enter: +--- -``` -Check the current block height on TRON mainnet -``` +## 🛠️ How to Add API Keys (VIP Pass) After Installation? -If you receive a normal response showing the current block height, it means mcp-server-tron has been successfully connected. +Totally get it! You were just browsing during installation and pressed Enter to skip everything. Now that you're comfortable, here's how to fill in your API Keys for the "VIP express lane": -You can also try: +### Step 1: Figure Out Which "Key" You Need -``` -Check the TRX balance of TRON address TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -``` +| Key Name | What's It For? | Where to Get It for Free? | +| :--- | :--- | :--- | +| `TRONGRID_API_KEY` | Express lane for the TRON toolbox — without it you'll be throttled | Register for free at [trongrid.io](https://www.trongrid.io/) | +| `TRONSCAN_API_KEY` | Required for the TronScan data lookup skill | Apply for free at [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) | +| `BANKOFAI_API_KEY` | Used for topping up or checking balance on BANK OF AI | Get it after logging in at [chat.bankofai.io/key](https://chat.bankofai.io/key) | -``` -What are the current energy and bandwidth prices on TRON mainnet? -``` +### Step 2: Enter Your Keys into the System -If all these queries return results normally, you're all set. +Once you have the corresponding key, choose the simple method below based on its type. **Don't forget to restart OpenClaw after filling it in!** -:::info About Read-Only Mode -If you didn't configure a private key during installation, the MCP Server will run in read-only mode — all query operations (check balance, check transactions, check contract state, etc.) work normally, but transfer and contract write operations are unavailable. To unlock write capabilities, see [Configuration Reference](./Configuration.md). -::: +#### 🔧 Type A Keys: Add to "Hidden Notepad" (For TRONGRID and TRONSCAN) ---- +1. Type `open -e ~/.zshrc` in the terminal and press Enter. +2. At the bottom of the text editor that opens, paste these lines (keep the double quotes `""`): + ``` + export TRONGRID_API_KEY="paste_your_TronGrid_Key_here" + export TRONSCAN_API_KEY="paste_your_TronScan_Key_here" + ``` +3. Press `Command + S` to save and close, then reopen the terminal or restart OpenClaw for changes to take effect. -## Having Problems? +#### 🔧 Type B Keys: One-Click Config File (For BANK OF AI) -If your AI assistant can't recognize blockchain tools after installation, common causes include: +If you have this key, simply copy and run the following command in the terminal (remember to replace the placeholder with your actual key): -- **OpenClaw not restarted** — Configuration changes require a full restart -- **Node.js version too old** — Ensure v18.0.0 or higher -- **mcporter.json format error** — You can check with `python3 -m json.tool ~/.mcporter/mcporter.json` +**Configure BANK OF AI:** -For more troubleshooting, see [FAQ & Troubleshooting](./FAQ.md). +```bash +mkdir -p ~/.mcporter && echo '{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://api.bankofai.io/v1/"}' > ~/.mcporter/bankofai-config.json +``` --- -## Next Steps +## Still Stuck Somewhere? + +That's totally normal! Everyone's computer environment is different. -- Want to understand the detailed features of each MCP Server and Skill? → [Component Details](./Components.md) -- Want to configure private keys, API Keys, or security options? → [Configuration Reference](./Configuration.md) -- Having issues? → [FAQ & Troubleshooting](./FAQ.md) +Check out 👉 **[FAQ (Troubleshooting Guide)](./FAQ.md)** — we've already encountered and documented solutions for 99% of the weird issues out there. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index 4de059a6..d8a44366 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -67,5 +67,9 @@ "sidebar.docsSidebar.category.API": { "message": "API 参考", "description": "The label for category API in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Explore Further": { + "message": "进一步探索", + "description": "The label for category Explore Further in sidebar docsSidebar" } } diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md new file mode 100644 index 00000000..291f80ce --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -0,0 +1,276 @@ +# CLI 命令行手册 + +包含了 Agent-wallet 所有命令的完整参考。无论你是想复习基础操作，还是想配置自动化脚本，这里都有答案。 + +:::tip 刚刚入门？ +如果你还没创建过钱包，先去 [快速开始](../QuickStart.md) 走一遍——三步搞定，不到一分钟。 +::: + +--- + +## 基础命令 + +高频使用的核心操作——创建钱包和签名。 + +### `agent-wallet start`（初始化 / 创建钱包） + +**交互式创建（推荐）：** +```bash +agent-wallet start +``` +系统会一步步引导你选择钱包类型、生成密钥、设置主密码。跟着提示走就行。 + +:::danger 切勿对真实资金使用 `raw_secret` 钱包类型 +交互式向导可能会提供 `raw_secret` 选项。该类型将私钥**以明文形式**存储在磁盘上——任何有文件系统访问权限的程序都能直接读取。`raw_secret` 仅适用于完全隔离的测试环境。持有真实资金的钱包请始终选择 `local_secure`。 +::: + +**自定义密码：** +```bash +agent-wallet start -p Abc12345! +``` +密码要求：至少 8 位，包含大写、小写、数字和特殊字符。 + +:::caution Shell 历史记录风险 +使用 `-p` 内联传递密码会将密码记录在终端的历史文件中。生产钱包建议使用交互式模式（不带 `-p` 的 `agent-wallet start`）或通过环境变量设置 `AGENT_WALLET_PASSWORD`——详见[非交互式执行](#非交互式执行专为自动化与后台设计)。 +::: + +**导入已有私钥：** +```bash +agent-wallet start -p Abc12345! -k 你的私钥十六进制 +``` + +**导入助记词：** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." +``` + +### `agent-wallet sign`（核心签名操作） + +每条 `sign` 子命令都需要 `--network` / `-n` 来指定链。 + +**签名消息：** +```bash +agent-wallet sign msg "Hello" -n tron +``` + +**签名交易**（需要先通过 RPC 构建未签名交易）： +```bash +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron +``` + +**签名 EIP-712 结构化数据：** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 +``` + +--- + +## 钱包管理 + +管理多个钱包——添加、切换、查看、删除。 + +**添加新钱包：** +```bash +agent-wallet add +``` + +**列出所有钱包：** +```bash +agent-wallet list +``` + +**切换活跃钱包：** +```bash +agent-wallet use my-bsc-wallet +``` + +**查看钱包详情：** +```bash +agent-wallet inspect my-bsc-wallet +``` + +**用指定钱包签名**（不切换活跃钱包）： +```bash +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!' +``` + +**删除钱包：** +```bash +agent-wallet remove my-bsc-wallet +``` + +--- + +## 非交互式执行（专为自动化与后台设计） + +默认情况下，执行签名命令时，终端会停下来并出现一行提示，等待你手动敲击键盘输入密码。但如果是 AI 代理在后台运行，或者你在跑自动化脚本，这种"中途停下来等人输入"的机制会导致程序直接卡死报错。 + +为了让程序能一口气静默跑完（非交互模式），你需要提前把密码"喂"给命令。根据你的使用场景，有以下三种方式： + +### 方式 A：环境变量注入（推荐用于 AI 代理 / CI 流水线） + +将密码提前存在当前系统环境里，程序运行需要密码时会自动去环境里拿，全程静默： + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +``` + +设置后，当前窗口的所有签名命令直接秒出结果，不再停顿等待： + +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` + +:::tip 防止此命令被记录到 Shell 历史 +建议直接用文本编辑器编辑 `~/.zshrc` / `~/.bashrc`，从根本上避免历史记录泄露。如果选择在命令前加空格来阻止记录，请先确认你的 Shell 已启用相应设置：Bash 中运行 `echo $HISTCONTROL` 确认包含 `ignorespace`，Zsh 中运行 `setopt | grep HIST_IGNORE_SPACE` 确认已开启。这些设置在大多数系统上**并非**默认启用，需要手动配置。 +::: + +:::caution 密码有特殊字符？务必用单引号 +```bash +# 正确 — shell 按字面意思处理 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# 错误 — $ 被 shell 展开，导致密码在后台静默报错 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +
+GitHub Actions / CI 示例 + +在 CI/CD 环境中，切勿将密码硬编码在工作流文件里。请使用仓库密钥（Secrets）： + +```yaml +# .github/workflows/sign.yml +jobs: + sign: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: agent-wallet sign msg "Hello" -n tron + env: + AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }} +``` + +
+ +### 方式 B：密码本地缓存（便利性与安全性的取舍） + +执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： + +```bash +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets +``` + +:::danger 此操作会使双重锁保护失效 +将密码缓存在钱包文件旁边，意味着一次文件系统入侵就能获取全部资金——彻底击溃 Agent-wallet 的核心"物理文件 + 密码分离"安全模型。**请仅对一次性测试钱包使用此功能。** + +`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。务必确保该文件不会被提交到 git 或同步到云端。 + +工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。 + +要删除已缓存的密码并恢复完整的双重锁保护： + +```bash +rm ~/.agent-wallet/runtime_secrets.json +``` + +删除后，签名命令将再次以交互方式提示输入密码（或从 `AGENT_WALLET_PASSWORD` 环境变量读取）。 +::: + +### 方式 C：命令行内联 `-p`（适合临时跑单次指令） + +直接把密码写在命令的结尾。程序拿到密码就直接干活，不会再停下来问你： + +```bash +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' +``` + +:::danger 安全提示 +直接用 `-p` 传递密码时，明文密码会被留在你电脑的终端 `history`（历史记录）中。强烈建议仅在完全隔离的测试环境中使用此方法！ +::: + +### 自定义存储目录 + +所有命令都支持 `--dir` 参数来指定 Agent-wallet 的存储路径（默认在 `~/.agent-wallet`）。比如，你可以把 Agent-wallet 直接建在加密 U 盘里，即插即用，拔下即走： + +```bash +agent-wallet start --dir /Volumes/MyUSB/agent-wallet +agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet +``` + +--- + +## 危险操作 + +:::danger 以下操作不可逆，请谨慎使用！ +::: + +### `agent-wallet change-password`（修改主密码） + +修改后，**所有密钥文件会用新密码重新加密**。旧密码立即失效，请确保已在密码管理器中更新。 + +```bash +agent-wallet change-password +``` + + + +### `agent-wallet reset`（重置所有数据） + +删除 `~/.agent-wallet/` 下的所有内容。**这是核弹级操作——一旦执行，所有钱包、密钥、配置全部消失，无法恢复。** 系统会要求二次确认。 + +```bash +agent-wallet reset +``` + +--- + +## 实战：在 Shell 脚本中调用签名 + +CLI 不只是拿来手敲的——它可以完美嵌入你的自动化脚本。 + +下面这个极简示例展示了如何在 Bash 脚本中完成一次非交互式签名，并把签名结果干净地存入变量，供后续业务使用（不涉及复杂的网络请求代码）： + +```bash +#!/bin/bash +# 开启严格模式：遇到报错立刻停止 +set -e + +# 1. 密码应在运行此脚本之前已在环境中设置好。 +# 例如通过 ~/.zshrc / ~/.bashrc — 详见快速开始中的"保存并使密码生效"。 +# 切勿在脚本文件中硬编码真实密码（密码会随脚本进入 git 历史记录）。 +if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then + echo "错误：AGENT_WALLET_PASSWORD 未设置" >&2 + exit 1 +fi + +echo "正在调用本地 Agent-wallet 签名..." + +# 2. 核心操作：执行签名，并将终端打印出的哈希结果直接存入 SIGNATURE 变量 +SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) + +# 3. 拿到干净的签名结果，继续后续流程 +echo "✅ 签名成功！" +echo "提取到的签名内容是: $SIGNATURE" + +# 接下来，你可以拿这个 $SIGNATURE 去发请求、拼 JSON，或者传给其他流水线任务... +``` + +--- + +## 下一步 + +- 没写过代码？ → [快速上手](../QuickStart.md) +- 要开发应用？ → [SDK 接入指南](./SDK-Guide.md) +- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md new file mode 100644 index 00000000..1283f208 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -0,0 +1,568 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 完整代码示例 + +:::tip 为什么要看这个页面？ +在 [SDK 快速开始](./SDK-Guide.md) 中，你已经学会了如何让 Agent-wallet 完成"离线签名"。但在真实的业务中，AI 代理不能只会签名。它需要：**1. 去节点查数据构建交易 → 2. Agent-wallet 签名 → 3. 广播上链。** + +Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页为你提供了一套**"开箱即用"**的完整脚本，结合了 TronGrid 和 Ethers.js / Web3.py，带你跑通真正的全链路闭环。你可以直接复制这些代码用于你的生产环境！ +::: + +本页走完三个真实场景的完整流程：在 TRON 发送 TRX、在 BSC 发送 BNB、签名 x402 支付许可。每个示例都可以直接运行——复制代码、填入你的地址，就能跑。 + +文档提供 TypeScript 和 Python 两个版本，点击标签页切换。 + +--- + +## 前置条件 + +运行以下任何示例之前，确保已经完成： + +1. 安装 Agent-wallet SDK（详见 [SDK 接入指南](./SDK-Guide.md)） +2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量 +3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式——强烈推荐） + +:::danger 真金白银操作请勿使用静态模式（`AGENT_WALLET_PRIVATE_KEY`） +静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地 Agent-wallet。 +::: + +--- + +## TRON 转账 + +**使用场景**：AI 代理需要在 TRON 网络发起 TRX 转账——比如支付 API 调用费用、归集资金，或完成自动化任务后结算报酬。 + +**工作原理**： + +TRON 交易不能由客户端直接从零构建。流程必须从调用 TronGrid 的 `createtransaction` 接口开始——该接口返回一个包含 `txID` 和 `raw_data` 的未签名交易对象，由网络节点生成。然后把这个对象传给 Agent-wallet 进行本地签名——签名过程完全离线，私钥不会离开本机。最后，把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口，发布到链上。 + +``` +TronGrid（构建）→ Agent-wallet（签名）→ TronGrid（广播） +``` + +Agent-wallet 只参与中间的签名步骤，不需要 RPC 连接，也不感知交易的业务含义。 + +### 安装依赖 + + + + +```bash +npm install @bankofai/agent-wallet axios +``` + + + + +本示例使用 `aiohttp`（第三方 HTTP 库）和 `asyncio`（Python 标准库，无需安装）： + +```bash +pip install aiohttp +``` + +:::caution 如果出现标准库模块缺失的报错 +如果 `asyncio` 等标准库模块导入失败，通常是因为 pyenv 从源码编译 Python 时缺少系统依赖。先安装以下包，再重新运行 `pyenv install 3.11`： + +```bash +# CentOS / RHEL / Amazon Linux +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` +::: + + + + + + +### 完整代码 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import axios from "axios"; + +const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网；主网改为 https://api.trongrid.io + +async function transferTRX( + fromAddress: string, + toAddress: string, + amountSun: number // 1 TRX = 1_000_000 SUN +) { + // 第一步：初始化 Agent-wallet + const provider = resolveWalletProvider({ network: "tron:nile" }); + const wallet = await provider.getActiveWallet(); + + // 确保 fromAddress 与钱包地址一致——不匹配会导致 TronGrid 报错 + const walletAddress = await wallet.getAddress(); + if (fromAddress !== walletAddress) { + throw new Error(`fromAddress 不匹配：预期 ${walletAddress}，实际 ${fromAddress}`); + } + + // 第二步：通过 TronGrid 构建未签名交易 + const { data: unsignedTx } = await axios.post( + `${TRONGRID_API}/wallet/createtransaction`, + { + owner_address: fromAddress, + to_address: toAddress, + amount: amountSun, + visible: true, + } + ); + + if (!unsignedTx.txID) { + throw new Error("构建交易失败：" + JSON.stringify(unsignedTx)); + } + + console.log("未签名 txID：", unsignedTx.txID); + + // 第三步：用 Agent-wallet 本地签名 + let signedTx: Record; + try { + signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + } catch (e) { + throw new Error(`signTransaction 返回了无效的 JSON: ${e}`); + } + if (!signedTx.signature) { + throw new Error("签名后的交易缺少 signature 字段"); + } + if (!signedTx.txID) { + throw new Error("签名后的交易缺少 txID 字段"); + } + console.log("已签名，signature：", signedTx.signature); + + // 第四步：通过 TronGrid 广播 + const { data: broadcastResult } = await axios.post( + `${TRONGRID_API}/wallet/broadcasttransaction`, + signedTx + ); + + if (broadcastResult.result) { + console.log("广播成功！txID：", signedTx.txID); + } else { + console.error("广播失败：", broadcastResult); + } + + return signedTx.txID; +} + +// 示例调用 +transferTRX( + "你的 TRON 地址", // 替换成你的钱包地址 + "收款方 TRON 地址", // 替换成收款方地址 + 1_000_000 // 1 TRX +).catch(console.error); +``` + + + + +```python +import asyncio +import json +import aiohttp +from agent_wallet import resolve_wallet_provider + +TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网；主网改为 https://api.trongrid.io + +async def transfer_trx( + from_address: str, + to_address: str, + amount_sun: int, # 1 TRX = 1_000_000 SUN +): + # 第一步：初始化 Agent-wallet + provider = resolve_wallet_provider(network="tron:nile") + wallet = await provider.get_active_wallet() + + async with aiohttp.ClientSession() as session: + # 第二步：通过 TronGrid 构建未签名交易 + async with session.post( + f"{TRONGRID_API}/wallet/createtransaction", + json={ + "owner_address": from_address, + "to_address": to_address, + "amount": amount_sun, + "visible": True, + }, + ) as resp: + unsigned_tx = await resp.json() + + if "txID" not in unsigned_tx: + raise ValueError(f"构建交易失败：{unsigned_tx}") + + print("未签名 txID：", unsigned_tx["txID"]) + + # 第三步：用 Agent-wallet 本地签名 + raw_signed = await wallet.sign_transaction(unsigned_tx) + try: + signed_tx = json.loads(raw_signed) + except json.JSONDecodeError as e: + raise ValueError(f"signTransaction 返回了无效的 JSON: {e}") from e + if "signature" not in signed_tx: + raise ValueError("签名后的交易缺少 signature 字段") + print("已签名，signature：", signed_tx["signature"]) + + # 第四步：通过 TronGrid 广播 + async with session.post( + f"{TRONGRID_API}/wallet/broadcasttransaction", + json=signed_tx, + ) as resp: + broadcast_result = await resp.json() + + if broadcast_result.get("result"): + print("广播成功！txID：", signed_tx["txID"]) + else: + print("广播失败：", broadcast_result) + + return signed_tx["txID"] + +# 示例调用 +asyncio.run( + transfer_trx( + from_address="你的 TRON 地址", # 替换成你的钱包地址 + to_address="收款方 TRON 地址", # 替换成收款方地址 + amount_sun=1_000_000, # 1 TRX + ) +) +``` + + + + +:::caution 注意事项 +- 测试请使用 Nile 测试网，测试代币从 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取。 +- 切换主网：把 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet`。 +::: + +:::tip `visible: true` 与地址格式 +代码传了 `visible: true` 给 TronGrid，这个参数影响 API 期望的地址格式： + +- **`visible: true`**：API 接受 **Base58 格式**（标准的 TRON 可读地址，例如 `TNmo...`） +- **`visible: false`（或不传）**：API 接受 **十六进制格式**（例如 `41b9f...`） + +示例使用 Base58 地址，与 `visible: true` 保持一致。 +::: + +--- + +## EVM 转账（BSC / Ethereum） + +**使用场景**：AI 代理需要在 BSC、Ethereum 或其他 EVM 兼容链上发起原生代币转账——比如支付 Gas、向合约转账触发业务逻辑，或完成链上任务后结算。 + +**工作原理**： + +EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，没有集中式 API 帮你生成。未签名交易构建完成后，传给 Agent-wallet 进行本地签名，返回十六进制编码的已签名交易，最后通过 `sendRawTransaction` 广播。 + +``` +RPC 查询 nonce/gas（构建）→ Agent-wallet（签名）→ RPC sendRawTransaction（广播） +``` + +示例使用 BSC 测试网，切换到 Ethereum、Polygon、Base 或其他 EVM 链只需改 `RPC_URL` 和 `CHAIN_ID`——Agent-wallet 的调用代码一行不变。 + +### 安装依赖 + + + + +```bash +npm install @bankofai/agent-wallet ethers +``` + + + + +```bash +pip install web3 +``` + + + + +### 完整代码 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { ethers } from "ethers"; + +// BSC 测试网 +const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; +const CHAIN_ID = 97; // BSC 测试网；主网用 56 + +async function transferBNB( + toAddress: string, + amountEther: string // 例如 "0.001" +) { + // 第一步：初始化 Agent-wallet + const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); + const wallet = await provider.getActiveWallet(); + const fromAddress = await wallet.getAddress(); + + // 第二步：通过 RPC 查询 nonce 和 gas 信息 + const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); + const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); + const feeData = await rpcProvider.getFeeData(); + + if (!feeData.maxFeePerGas || !feeData.maxPriorityFeePerGas) { + throw new Error("该链不支持 EIP-1559 费用数据"); + } + + // 第三步：构建未签名交易 + const unsignedTx = { + to: toAddress, + value: ethers.parseEther(amountEther), + gas: 21000n, + maxFeePerGas: feeData.maxFeePerGas, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas, + nonce, + chainId: CHAIN_ID, + type: 2, // EIP-1559 + }; + + console.log("交易已构建，nonce：", nonce); + + // 第四步：用 Agent-wallet 本地签名 + const signedTxHex = await wallet.signTransaction(unsignedTx); + console.log("已签名"); + + // 第五步：广播 + // signTransaction 返回的十六进制不带 '0x' 前缀；ethers 需要加上 + const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); + console.log("广播成功！txHash：", txResponse.hash); + + // 等待确认（可选 — 添加超时以防止无限阻塞） + try { + const receipt = await txResponse.wait(1); // 等待 1 个确认，超时则抛出异常 + console.log("已在区块中确认：", receipt?.blockNumber); + } catch (e) { + console.warn("等待回执超时或失败：", e); + } + + return txResponse.hash; +} + +// 示例调用 +transferBNB( + "0x收款方地址", // 替换成收款方地址 + "0.001" // 发送 0.001 BNB +).catch(console.error); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider +from web3 import AsyncWeb3 + +# BSC 测试网 +RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" +CHAIN_ID = 97 # BSC 测试网；主网用 56 + +async def transfer_bnb(to_address: str, amount_ether: str): + # 第一步：初始化 Agent-wallet + provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") + wallet = await provider.get_active_wallet() + from_address = await wallet.get_address() + + # 第二步：通过 RPC 查询 nonce 和 gas 信息 + w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) + nonce = await w3.eth.get_transaction_count(from_address, "latest") + fee_data = await w3.eth.fee_history(1, "latest", [50]) + base_fee = fee_data["baseFeePerGas"][-1] + priority_fee = await w3.eth.max_priority_fee + + # 第三步：构建未签名交易 + unsigned_tx = { + "to": to_address, + "value": w3.to_wei(amount_ether, "ether"), + "gas": 21000, + "maxFeePerGas": base_fee + priority_fee, + "maxPriorityFeePerGas": priority_fee, + "nonce": nonce, + "chainId": CHAIN_ID, + "type": 2, # EIP-1559 + } + + print("交易已构建，nonce：", nonce) + + # 第四步：用 Agent-wallet 本地签名 + signed_tx_hex = await wallet.sign_transaction(unsigned_tx) + print("已签名") + + # 第五步：广播 + tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) + print("广播成功！txHash：", tx_hash.hex()) + + # 可选：等待确认 + # 注意：此调用会阻塞事件循环最多 `timeout` 秒。 + # 生产环境的 AI Agent 建议在后台任务中执行， + # 或使用 asyncio.wait_for() 配合更短的超时和重试逻辑。 + import asyncio + try: + receipt = await asyncio.wait_for( + w3.eth.wait_for_transaction_receipt(tx_hash), + timeout=120 + ) + print("已在区块中确认：", receipt["blockNumber"]) + except asyncio.TimeoutError: + print("等待确认超时——交易可能仍会被确认。txHash：", tx_hash.hex()) + + return tx_hash.hex() + +# 示例调用 +asyncio.run( + transfer_bnb( + to_address="0x收款方地址", # 替换成收款方地址 + amount_ether="0.001", + ) +) +``` + + + + +:::caution 注意事项 +- 测试请使用 BSC 测试网（chainId=97），测试代币从 [BSC Faucet](https://testnet.binance.org/faucet-smart) 领取。 +- 切换主网：把 `RPC_URL` 改为主网 RPC 地址，`CHAIN_ID` 改为 `56`，`network` 改为 `eip155:56`。 +::: + +--- + +## x402 支付许可签名 + +**使用场景**：AI 代理正在访问受 x402 协议保护的付费 API——比如获取实时数据、调用 AI 推理服务，或触发链上操作。服务器返回 HTTP 402，要求代理在获取内容之前提供支付授权。 + +**工作原理**： + +x402 支付不是直接发一笔转账，而是"先签名、验证后放行"的模型。代理对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，把得到的签名随请求一起发给服务器作为支付凭证。服务器验证签名有效后才返回内容。代理不需要等待链上确认——延迟极低。 + +``` +服务器返回 402 → 代理构建 PaymentPermit → Agent-wallet 签名 → 携带签名重发请求 → 服务器验证通过并响应 +``` + +PaymentPermit 数据由 x402 SDK 根据服务器返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面的示例展示了底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +async function signPaymentPermit(authorization: { + from: string; + to: string; + value: string; + validAfter: string; + validBefore: string; + nonce: string; +}) { + // 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配） + const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base 主网 + const wallet = await provider.getActiveWallet(); + + // 构建 EIP-712 结构化数据（与 x402 协议规范对齐） + const typedData = { + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "version", type: "string" }, + { name: "chainId", type: "uint256" }, + { name: "verifyingContract", type: "address" }, + ], + TransferWithAuthorization: [ + { name: "from", type: "address" }, + { name: "to", type: "address" }, + { name: "value", type: "uint256" }, + { name: "validAfter", type: "uint256" }, + { name: "validBefore", type: "uint256" }, + { name: "nonce", type: "bytes32" }, + ], + }, + primaryType: "TransferWithAuthorization", + domain: { + name: "USD Coin", + version: "2", + chainId: 8453, + verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC + }, + message: authorization, + }; + + // 用 Agent-wallet 本地签名 + const signature = await wallet.signTypedData(typedData); + console.log("PaymentPermit 签名：", signature); + + return signature; +} +``` + + + + +```python +from agent_wallet import resolve_wallet_provider + +async def sign_payment_permit(authorization: dict) -> str: + # 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配） + provider = resolve_wallet_provider(network="eip155:8453") # Base 主网 + wallet = await provider.get_active_wallet() + + # 构建 EIP-712 结构化数据（与 x402 协议规范对齐） + typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"}, + ], + "TransferWithAuthorization": [ + {"name": "from", "type": "address"}, + {"name": "to", "type": "address"}, + {"name": "value", "type": "uint256"}, + {"name": "validAfter", "type": "uint256"}, + {"name": "validBefore", "type": "uint256"}, + {"name": "nonce", "type": "bytes32"}, + ], + }, + "primaryType": "TransferWithAuthorization", + "domain": { + "name": "USD Coin", + "version": "2", + "chainId": 8453, + "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # Base USDC + }, + "message": authorization, + } + + # 用 Agent-wallet 本地签名 + signature = await wallet.sign_typed_data(typed_data) + print("PaymentPermit 签名：", signature) + + return signature +``` + + + + +:::tip +x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不需要手写这段代码。上面的示例展示了底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。 +::: + +--- + +## 下一步 + +- 喜欢敲命令？ → [CLI 命令行手册](./CLI-Reference.md) +- 要开发应用？ → [SDK 接入指南](./SDK-Guide.md) +- 了解 x402 与 Agent-wallet 如何配合 → [x402 简介](../../x402/index.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md new file mode 100644 index 00000000..1b1ac48c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md @@ -0,0 +1,531 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SDK 接入指南 + +CLI 已经跑通了，能从命令行签名。现在你想把签名能力放进代码里——MCP Server、自动化脚本、AI 代理工作流。 + +本页教你怎么做。完成后，你就能用几行 TypeScript 或 Python 初始化钱包 Provider、获取活跃钱包，并对消息、交易、EIP-712 结构化数据进行签名。 + +:::tip 刚刚入门？ +如果还没创建过钱包，先去 [快速上手](../QuickStart.md) 走一遍（不到一分钟）。SDK 读取的就是 CLI 创建的那个钱包——不需要重复配置任何东西。 +::: + +文档提供 TypeScript 和 Python 两个版本的安装说明和代码示例，点击标签页切换。 + +--- + +## 第一步：安装 + + + + +**检查 Node.js 版本** + +需要 Node.js ≥ 18，查看当前版本： + +```bash +node -v +``` + +输出 `v18.0.0` 或更高，可以直接安装；否则按下面的方法升级。 + +:::tip 安装 / 升级 Node.js + +推荐用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本： + +```bash +# 安装 nvm（已安装可跳过） +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# 重新加载 shell 配置 +source ~/.bashrc # 或 source ~/.zshrc + +# 安装并切换到 Node.js 18 LTS +nvm install 18 +nvm use 18 +``` + +也可以直接从 [nodejs.org](https://nodejs.org) 下载 **LTS** 安装包。 + +::: + +**安装 SDK** + +```bash +npm install @bankofai/agent-wallet +``` + + + + +**检查 Python 版本** + +需要 Python ≥ 3.11（SDK 使用了 3.11+ 的特性）： + +```bash +python3 --version +``` + +输出 `3.11.x` 或更高，可以直接安装；否则按下面的方法升级。 + +:::tip 安装 / 升级 Python + +推荐用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本： + +```bash +# 第一步：安装 pyenv +curl https://pyenv.run | bash +``` + +安装后需要手动添加到 shell 配置： + +```bash +# 将以下三行追加到 ~/.bashrc（zsh 用户改为 ~/.zshrc） +echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc +echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(pyenv init -)"' >> ~/.bashrc + +# 重新加载配置，使当前终端立即生效 +source ~/.bashrc +``` + +使用 pyenv 之前，先安装系统依赖，**跳过这步会导致 `_ctypes`、`ssl` 等模块缺失，进而影响 `asyncio` 等标准库的导入**： + +```bash +# CentOS / RHEL / Amazon Linux / Fedora +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` + +然后编译 Python： + +```bash +pyenv install 3.11 +pyenv global 3.11 +``` + +也可以从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.11 或更高版本**。 + +::: + +**安装 SDK** + +```bash +pip install 'bankofai-agent-wallet[evm,tron]' +``` + +如果只需要其中一条链，单独安装对应的 extra： + +```bash +pip install 'bankofai-agent-wallet[tron]' # 仅 TRON +pip install 'bankofai-agent-wallet[evm]' # 仅 EVM +``` + +验证安装： + +```bash +python3 -c "import agent_wallet; print('Installation successful')" +``` + + + + +--- + +## 第二步：配置模式 + +调用 SDK 之前，需要通过环境变量告诉 Agent-wallet 去哪里找密钥。 + +不要被复杂的概念吓到，`resolveWalletProvider()` 极其聪明，它会自动检测你配置了什么环境变量，并决定工作模式，代码里不需要写任何 `if/else` 判断逻辑。 + +它支持以下两种模式： + +### 🛡️ 核心用法：本地 Agent-wallet 模式（强烈推荐） + +如果你刚才已经跟着 [快速上手](../QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。 + +**在这个模式下，你根本不需要（也不应该）接触明文私钥。** 你只需要告诉 SDK 你的"开箱密码"即可。 + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +# 可选：如果你之前改过钱包存储目录，告诉 SDK 在哪找 +export AGENT_WALLET_DIR="$HOME/.agent-wallet" +``` + +:::caution 密码含特殊字符时，务必用单引号 +自动生成的强密码可能含有 `$`、`!` 等 shell 特殊字符，务必用单引号，避免 shell 展开导致密码被破坏： + +```bash +# ✅ 正确：单引号，密码原样传入 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ 错误：双引号，$ 被 shell 展开 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +### ⚠️ 备用方案：静态注入模式（仅限测试环境） + +如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地 Agent-wallet，直接把私钥喂给 SDK。 + +```bash +export AGENT_WALLET_PRIVATE_KEY='你的私钥十六进制' +# 或 +export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' +``` + +:::danger 极度危险：违背核心安全原则！ +静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地 Agent-wallet 模式。 +::: + +:::tip 环境变量冲突怎么办？ +如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地 Agent-wallet 模式，忽略明文私钥。 +::: + +### 环境变量速查 + +| 变量名 | 用途 | 模式 | 是否必填 | +| :--- | :--- | :--- | :--- | +| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地 Agent-wallet | 核心必填 | +| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地 Agent-wallet | 可选 | +| `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（十六进制） | ⚠️ 静态注入 | 二选一（与助记词） | +| `AGENT_WALLET_MNEMONIC` | 明文助记词短语 | ⚠️ 静态注入 | 二选一（与私钥） | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 派生索引（默认 `0`） | ⚠️ 静态注入 | 可选 | + +--- + +## 使用示例 + +### 初始化钱包 Provider + +所有操作的起点是 `resolveWalletProvider()`。它读取环境变量，选择对应模式，返回钱包 Provider。调用 `getActiveWallet()` 获取活跃钱包。 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); + +// 查看当前钱包地址 +const address = await wallet.getAddress(); +console.log("Address:", address); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + wallet = await provider.get_active_wallet() + + # 查看当前钱包地址 + address = await wallet.get_address() + print("Address:", address) + +asyncio.run(main()) +``` + + + + +拿到 `wallet` 之后，就可以调用下面三种签名方法。所有签名方法返回十六进制编码的签名字符串（不带 `0x` 前缀）。 + +### 签名消息 + + + + +```typescript +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_message(b"Hello") +print("Signature:", sig) +``` + + + + +### 签名交易 + +Agent-wallet 只负责签名，不构建也不广播。你需要先通过 RPC（比如 TronGrid、Infura）构建未签名的交易，再传给 SDK 签名。 + +#### TRON 交易 + + + + +```typescript +// 1. 调用方通过 TronGrid 构建未签名交易 +const unsignedTx = { + txID: "abc123...", + raw_data_hex: "0a02...", + raw_data: { /* TronGrid 返回的原始数据 */ }, +}; + +// 2. SDK 本地签名（无网络调用） +const signedTxJson = await wallet.signTransaction(unsignedTx); +console.log("Signed transaction:", signedTxJson); + +// 3. 调用方负责广播 +``` + + + + +```python +# 1. 调用方通过 TronGrid 构建未签名交易 +unsigned_tx = { + "txID": "abc123...", + "raw_data_hex": "0a02...", + "raw_data": {}, # TronGrid 返回的原始数据 +} + +# 2. SDK 本地签名（无网络调用） +signed_tx_json = await wallet.sign_transaction(unsigned_tx) +print("Signed transaction:", signed_tx_json) + +# 3. 调用方负责广播 +``` + + + + +#### EVM 交易（BSC、Ethereum 等） + + + + +```typescript +const sig = await wallet.signTransaction({ + to: "0xRecipient...", + value: 0n, + gas: 21000n, + maxFeePerGas: 20000000000n, + nonce: 0, + chainId: 56, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_transaction({ + "to": "0xRecipient...", + "value": 0, + "gas": 21000, + "maxFeePerGas": 20000000000, + "nonce": 0, + "chainId": 56, +}) +print("Signature:", sig) +``` + + + + +### 签名 EIP-712 结构化数据 + +用于 x402 协议 PaymentPermit 签名、Permit2 等场景： + + + + +```typescript +const sig = await wallet.signTypedData({ + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "chainId", type: "uint256" }, + ], + Transfer: [ + { name: "to", type: "address" }, + { name: "amount", type: "uint256" }, + ], + }, + primaryType: "Transfer", + domain: { name: "MyDApp", chainId: 1 }, + message: { to: "0x...", amount: 1000000 }, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_typed_data({ + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + ], + "Transfer": [ + {"name": "to", "type": "address"}, + {"name": "amount", "type": "uint256"}, + ], + }, + "primaryType": "Transfer", + "domain": {"name": "MyDApp", "chainId": 1}, + "message": {"to": "0x...", "amount": 1000000}, +}) +print("Signature:", sig) +``` + + + + +--- + +### 管理多个钱包 + +需要在代码中管理多个钱包时，使用本地模式的 `resolveWalletProvider()`，Provider 会读取钱包配置并支持切换活跃钱包： + + + + +```typescript +import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet"; + +// 本地模式：需要设置 AGENT_WALLET_PASSWORD +const provider = resolveWalletProvider({ network: "tron:nile" }); + +if (provider instanceof ConfigWalletProvider) { + // 列出所有钱包 — 返回 [walletId, config, isActive] 元组数组 + const wallets = provider.listWallets(); + for (const [id, config, isActive] of wallets) { + console.log(`${id} (${config.type})${isActive ? " ← 活跃" : ""}`); + } + + // 切换活跃钱包 + provider.setActive("my-evm-wallet"); +} + +// 获取并使用 +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider, ConfigWalletProvider + +# 需要设置 AGENT_WALLET_PASSWORD +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + if isinstance(provider, ConfigWalletProvider): + # 列出所有钱包 — 返回 [(wallet_id, config, is_active)] 元组列表 + wallets = provider.list_wallets() + for wallet_id, config, is_active in wallets: + print(f"{wallet_id} ({config.type}){' ← 活跃' if is_active else ''}") + + # 切换活跃钱包 + provider.set_active("my-evm-wallet") + + # 获取并使用 + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) + +asyncio.run(main()) +``` + + + + +--- + +### 错误处理 + +签名操作失败时，SDK 会抛出特定的错误类型，建议在代码中显式捕获，避免运行时崩溃。 + + + + +```typescript +import { + WalletNotFoundError, + SigningError, + DecryptionError, +} from "@bankofai/agent-wallet"; + +try { + const wallet = await provider.getActiveWallet(); + const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); + console.log("Signature:", sig); +} catch (e) { + if (e instanceof WalletNotFoundError) { + console.error("钱包不存在——检查是否设置了活跃钱包"); + } else if (e instanceof DecryptionError) { + console.error("解密失败——检查主密码是否正确"); + } else if (e instanceof SigningError) { + console.error("签名失败：", e.message); + } else { + throw e; + } +} +``` + + + + +```python +from agent_wallet import WalletNotFoundError, SigningError, DecryptionError + +try: + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) +except WalletNotFoundError: + print("钱包不存在——检查是否设置了活跃钱包") +except DecryptionError: + print("解密失败——检查主密码是否正确") +except SigningError as e: + print(f"签名失败：{e}") +``` + + + + +错误类型层级： + +``` +WalletError +├── WalletNotFoundError # 指定钱包不存在 +├── DecryptionError # 密码错误或密钥文件损坏 +├── SigningError # 签名操作失败 +├── NetworkError # 网络标识符不匹配 +├── InsufficientBalanceError # 余额不足（由调用方抛出） +└── UnsupportedOperationError # 该钱包类型不支持此操作 +``` + +--- + +## 下一步 + +- 喜欢敲命令？ → [CLI 命令行手册](./CLI-Reference.md) +- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md) +- 了解 Agent-wallet 的设计思路 → [简介](../Intro.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md new file mode 100644 index 00000000..59452cac --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -0,0 +1,218 @@ +# 常见问题 + +先回答你最关心的三件事，然后是日常使用中会碰到的细节。 + +--- + +## 💰 AI 代理会不会把我的钱全转走？ + +这是最常被问到的问题，答案是：**就算 AI 代理被入侵了，你的核心资产也是安全的。** + +我们强烈建议你给 AI 代理单独创建一个钱包，只充入它实际需要的小额资金（比如当 Gas 费的额度）。你的主钱包、大额资产永远不碰。这样就算最坏情况发生，损失也只是那个小额钱包里的余额。 + +```bash +# 给 AI 代理单独建一个小额钱包 +agent-wallet add +``` + +而且你的钱包文件是高强度加密的。就算黑客拿到了文件，没有主密码就是一堆乱码——暴力破解在经济上毫无意义。 + +--- + +## 🔌 断网了，AI 代理还能签名吗？ + +能。**Agent-wallet 所有签名操作 100% 在你本地机器上完成。** + +从设计上就没有任何网络依赖——不调 RPC、不连云服务、不请求任何远端 API。你的私钥从始至终不碰网络。 + +断网只会影响交易的构建和广播（那是 MCP Server 的事），签名本身完全离线。 + +--- + +## 🔑 密码忘了怎么办？ + +**找不回来。** + +主密码是解密所有私钥的唯一凭证。没有"忘记密码"功能，没有后门。 + +如果你忘了密码： +- 有私钥或助记词的其他备份？运行 `agent-wallet reset`，重新初始化，重新导入 +- 什么备份都没有？那个钱包的访问权限就丢失了 + +**所以请现在就做这件事**：打开密码管理器，把主密码存进去。认真的。 + +--- + +## 日常使用 + +### Agent-wallet 到底是什么？ + +一个纯本地的加密签名工具。它做两件事：1）把你的私钥加密存储；2）在本地完成签名。不联网、不用云，本身没有独立界面——而是作为隐形的安全中枢，完美接入 OpenClaw 等 AI 前端工具中。 + +### CLI 和 SDK 什么区别？用哪个？ + +- **CLI** — 命令行工具，用来建钱包、管密钥、手动测试签名 +- **SDK** — TypeScript / Python 库，用来在自己的代码里调用签名 + +大多数人不需要 SDK。如果你是用 OpenClaw 和 MCP Server 的普通用户，CLI 建完钱包、配好环境变量就够了。SDK 是给自己写代理的开发者用的。 + +### Agent-wallet 和 MetaMask 有什么区别？ + +MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要你手动点"确认"。Agent-wallet 是给 AI 代理用的命令行钱包，专门设计为非交互式——AI 代理可以在后台静默调用签名，不需要人盯着屏幕点按钮。两者的加密原理类似（都是 Keystore V3），但使用场景完全不同。 + +### 一台电脑上可以创建多少个钱包？ + +没有限制。你可以为不同的 AI 代理、不同的链、不同的用途分别创建独立钱包。用 `agent-wallet add` 添加，用 `agent-wallet use` 切换。 + +--- + +## 钱包类型 + +### `local_secure` 和 `raw_secret` 有什么区别？ + +| | `local_secure` | `raw_secret` | +| :--- | :---: | :---: | +| **密钥加密** | ✅ 高强度加密 | ❌ 明文 | +| **代理读了文件** | ✅ 拿不到密钥 | ❌ 直接被盗 | +| **适合场景** | ✅ 所有场景 | ⚠️ 完全隔离的开发环境 | + +:::danger `raw_secret` 会以明文存储你的私钥 +`raw_secret` 不加密私钥——这恰恰是 `local_secure` 模式旨在防范的风险。如果你的机器上有任何其他进程能读取文件，你的私钥就会被直接盗走。**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理，且处于完全隔离的离线测试环境中。 +::: + +### `network` 参数怎么填？ + +| 值 | 说明 | +| :--- | :--- | +| `tron:mainnet` | TRON 主网 | +| `tron:nile` | TRON Nile 测试网 | +| `tron:shasta` | TRON Shasta 测试网 | +| `eip155:1` | Ethereum 主网 | +| `eip155:56` | BSC 主网 | +| `eip155:137` | Polygon 主网 | +| `eip155:8453` | Base 主网 | +| `eip155:42161` | Arbitrum 主网 | + +--- + +## 安全性 + +### 既然密码也要配在环境变量里，那和直接放明文私钥有什么区别？ + +区别极大！这是"把现金摆在桌上"和"把钱锁进双重保险箱"的区别。 + +你平时用 Web3 钱包（比如 MetaMask）时，肯定不会每次都复制粘贴明文私钥，而是用一个短密码去解锁它。Agent-wallet 就是专为 AI 打造的命令行版 MetaMask。 + +* 传统方式（明文私钥）： 就像把现金直接放在桌子上。任何一个恶意的浏览器插件、一次不小心的代码提交、或者后台日志扫描，只要看一眼你的环境变量文件，钱瞬间就被转走了。这是典型的单点白给。 +* Agent-wallet 模式： 它把风险拆分成了两把锁。 + 1. 物理保险箱： 你的私钥被行业顶级的算法加密，锁死在你电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 + 2. 开箱密码： 你放在环境变量里的，仅仅是解锁这个保险箱的密码。 + +这就意味着，如果发生了泄露： + +* 黑客如果只偷到了你的密码（比如通过扫描环境变量），他没有你的加密钱包文件，密码就只是一串没用的字符。 +* 黑客如果只偷走了你的加密钱包文件，他没有你的主密码，文件就是一堆几万年都破解不开的乱码。 + +黑客必须同时黑进你的电脑、精准定位并偷走隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。这种攻击难度比仅仅扫描一下环境变量要高出无数倍！ + +### 密钥会通过网络发出去吗？ + +永远不会。Agent-wallet 不发起任何网络请求。零 RPC 调用、零云服务。你的私钥永远不离开你的机器。 + +### 主密码怎么保管才安全？ + +- ✅ 用密码管理器（1Password、Bitwarden） +- ✅ 通过环境变量 `AGENT_WALLET_PASSWORD` 传入 +- ❌ 不要写在代码里 +- ❌ 不要提交含密码的环境变量文件到 git + +### 加密算法安全吗？会不会被暴力破解？ + +Agent-wallet 使用 Keystore V3 标准加密（scrypt + AES-128-CTR），这和 Ethereum 官方钱包使用的加密方案完全一致。scrypt 算法的设计目标就是让暴力破解在计算和内存上都极其昂贵——即使使用专用硬件，破解一个强密码也需要数万年。 + +--- + +## 安装与环境 + +### 支持哪些操作系统？ + +macOS 和 Linux。只要能跑 Node.js >= 18 或 Python >= 3.11，就能用。目前不支持 Windows。 + +### `npm install -g` 报权限错误怎么办？ + +常见于 macOS / Linux。两种解法： + +**方法 1（推荐）：用 nvm 管理 Node.js**，它会把全局包装在用户目录下，不需要 `sudo`。 + +**方法 2：修复 npm 全局目录权限**： +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc +source ~/.zshrc +``` + +### 配了密码但 AI 代理说"找不到钱包"或"密码错误"？ + +最常见的三个原因： + +1. **密码没生效**：你在终端 A 配了 `export`，但 AI 代理在终端 B 运行。解决：重启 AI 代理后台服务（参考 [快速开始](./QuickStart.md) 第二步）。 +2. **密码被 shell 吃了**：双引号包裹的密码里有 `$` 或 `!`，被 shell 展开了。解决：改用单引号。 +3. **存储目录不对**：你之前用 `--dir` 指定了自定义路径，但 AI 代理在默认路径找。解决：`export AGENT_WALLET_DIR="/你的自定义路径"`。 + +### `agent-wallet` 命令找不到（command not found）？ + +说明全局安装没有生效。检查： +```bash +# 确认 npm 全局 bin 目录在 PATH 里 +npm prefix -g +# 全局 bin 目录为：$(npm prefix -g)/bin +``` +如果输出的路径不在你的 `$PATH` 中，手动添加： +```bash +echo "export PATH=$(npm prefix -g)/bin:$PATH" >> ~/.zshrc +source ~/.zshrc +``` + +--- + +## 跨语言 + +### Python 和 TypeScript 的密钥文件通用吗？ + +通用。两个实现使用完全相同的加密格式。CLI 建的钱包，Python SDK 直接能用，反过来也一样。 + +### 两种语言的签名结果一样吗？ + +完全一样。同一个私钥 + 同一份数据 = 同一个签名。 + +--- + +## 与 OpenClaw 集成 + +### OpenClaw 是必须的吗？ + +不是。Agent-wallet 是一个独立的签名工具，可以通过 CLI 或 SDK 独立使用。OpenClaw 只是最方便的前端——它让你用自然语言就能调用签名，不用写代码。 + +### OpenClaw 里说"签名失败"或"钱包未连接"？ + +按以下顺序排查： + +1. 确认 `AGENT_WALLET_PASSWORD` 环境变量已设置（在运行 OpenClaw 的那个终端里执行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 验证，不会泄露密码明文） +2. 确认 MCP Server 是在设置了环境变量**之后**启动的 +3. 确认钱包已初始化：`agent-wallet list` 应该能看到至少一个钱包 +4. 如果以上都正确，尝试用 CLI 手动签名测试：`agent-wallet sign msg "test" -n tron` + +### 在 OpenClaw 里签名需要花 Gas 费吗？ + +签名本身不花 Gas。签名只是用你的私钥对一段数据做密码学运算，完全在本地完成。只有当签名后的交易被广播到链上时，才需要 Gas 费。查地址、签名消息这类操作永远免费。 + +--- + +## 下一步 + +- 没写过代码？ → [快速开始](./QuickStart.md) +- 喜欢敲命令？ → [CLI 命令行手册](./Developer/CLI-Reference.md) +- 要开发应用？ → [SDK 接入指南](./Developer/SDK-Guide.md) +- 找现成代码？ → [完整代码示例](./Developer/SDK-Cookbook.md) +- 了解 OpenClaw Extension → [OpenClaw Extension 简介](../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md new file mode 100644 index 00000000..9dffa6e2 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -0,0 +1,176 @@ +# 简介 +## 享受 AI Agent 便利，告别私钥泄露焦虑 + +### 你的私钥，距离被盗可能只差一次文件读取 + +你想让 AI 代理帮你自动完成链上操作——刷空投、做兑换、付 Gas 费、定时转账。要做这些事，AI 代理需要一把"钥匙"（私钥）来替你签名。 + +于是你把私钥以明文的方式保存在了电脑的一个配置文件里——谁能读到这个文件，谁就拿到了你的私钥。 + +**这就好比把银行卡和密码贴在脑门上，走进了一间挤满陌生人的办公室。** + +那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读到这个文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个 APP 拿走。 + +--- + +### 这不是吓你，它正在发生 + +- **依赖链投毒。** 你装了一个好用的 MCP Server。三个月后，它 200 个 npm 依赖中的某一个被注入了恶意代码——悄悄扫描所有文件，找到长得像私钥的字符串就发走。你完全不知道发生了什么，等你发现的时候，钱包已经空了。 + +- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。你的配置文件也在里面。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 + +- **Git 的"完美记忆"。** 你在开发时把私钥写进了代码，后来删了。但三周前你 commit 过一次。`git log -p` 里还有。仓库只要上过一次 GitHub，哪怕就 30 秒，自动化爬虫已经找到了。 + +这些方式的共同点：**你的私钥总是在某个地方裸奔**——磁盘上、日志里、git 历史里。 + +--- + +## 破局之道：Agent-wallet —— 专为 AI 代理打造的 Web3 钱包 + +你平时用 Web3 钱包（比如 TronLink/MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。 + +**Agent-wallet 就是专为 AI 代理打造的本地 TronLink/MetaMask。** + +它通过**"物理与密码分离"**的双重机制，把你的风险降到了最低： + +1. **第一重锁（物理文件）：** 你的私钥会被行业顶级的算法加密，锁死在电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 +2. **第二重锁（授权密码）：** AI 代理只需要知道"开箱密码"（你可以配在环境变量里）就能干活。 + +**你可能会问："如果 AI 代理把我的开箱密码也泄露了怎么办？"** + +这就是 Agent-wallet 最精妙的地方：**密码泄露 ≠ 资产被盗。** + +如果黑客通过恶意插件只偷到了你的密码，他什么也干不了，因为他没有你的加密钱包文件。如果他只偷到了钱包文件，没有密码，那就是一堆无法破解的乱码。 + +**黑客必须同时黑进你的电脑系统，精准翻出隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。** 这种攻击难度和成本，比仅仅扫描一下环境变量文件里的明文私钥要高出无数倍！ + +一句话：**文件随便偷，没密码打不开；密码被泄露，没文件依然安全。** + +--- + +## 和"老办法"对比一下 + +| | :x: 传统方式（明文私钥放在配置文件里） | :white_check_mark: Agent-wallet | +| :--- | :--- | :--- | +| **工作原理** | :x: 把银行卡和密码直接交给 AI 代理 | :white_check_mark: **给 AI 代理密码，文件锁在本地** | +| **遭遇日志/环境变量泄露** | :rotating_light: **直接倾家荡产** | :shield: **只丢了密码，没有文件，黑客偷不走钱** | +| **遭遇加密文件被窃取** | :x: 明文私钥，直接被盗 | :shield: **没有密码，黑客打不开文件** | +| **断网能签名吗** | :warning: 看情况 | :white_check_mark: **100% 离线签名** | + +--- + +## 三条命令，一分钟上手 + +不需要先搞懂所有东西，先跑通再说： + +**第一步 — 安装 Agent-wallet：** +```bash +npm install -g @bankofai/agent-wallet +``` + +**第二步 — 创建你的 Agent-wallet 钱包：** +```bash +agent-wallet start +``` +运行后，系统会引导你初始化 Agent-wallet 钱包，并生成一个**主密码**。这个密码是你唯一的"开箱钥匙"：每次 AI 代理需要签名时，都要用它来解锁钱包。**请立刻用密码管理器（如 1Password、Bitwarden）保存这个密码**——它不会再次显示，丢了就无法找回，资产也将无法操作。 + +**第三步 — 第一次签名：** +```bash +agent-wallet sign msg "Hello from my AI agent" -n tron +``` + +当屏幕上吐出一串哈希字符时——恭喜，你的 Agent-wallet 配置成功了。 + +> 想看每一步的详细说明？去 **[快速开始](./QuickStart.md)**。 + +--- + +## 接下来，让 AI 代理真正跑起来 + +Agent-wallet 建好了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** + +根据你的角色，走不同的路： + +### 🎮 我是普通玩家——用现成的工具 + +你完全不需要懂代码！你可以直接使用我们配套好的"全家桶"：**[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。 + +#### 🤝 它们是怎么配合干活的？ + +为了让你用得绝对放心，我们把你的 AI 助理设计成了一家分工明确的"小公司"： + +- 🧠 **业务团队（OpenClaw + Skills + MCP）：** 负责在外头跑腿。它们脑子转得快、工具多，知道怎么查行情、算滑点、找最优报价。但最重要的是：它们没有任何动用你资金的权限。 +- 🏦 **财务总监（Agent Wallet）：** 负责死守钱袋子。你的私钥（银行卡密码）被死死锁在它的本地保险柜里，外面的业务团队根本看不见。 + +一条完美的安全流水线是这样的： + +1. 你坐在老板椅上发话："帮我买 100 U 的 TRX"。 +2. 业务团队马上跑去查价格、算手续费，并老老实实写好一张"交易申请单"。 +3. 它们把单子递给坐在保险柜旁的 **财务总监（Agent Wallet）**。 +4. 财务总监核对无误后，绝不把私钥拿出保险柜，而是直接在申请单上盖个"同意印章"（技术上叫签名），然后再把盖好章的单子递出去。 +5. 业务团队拿着盖好章的单子，去区块链上把事办妥。 + +✨ **核心亮点：** 在整个过程中，跑腿的 AI 工具自始至终只拿到了"盖好章的纸"，连私钥的影子都没见着！既保证了 AI 代理能帮你干极其复杂的活儿，又保证了你的资产绝对安全。 + +#### ⚙️ 听起来很棒，我该怎么把它们连起来？ + +极其简单！你不需要写复杂的程序，只需要做一件事：给业务团队一把唤醒财务总监的内部口令。 + +把你创建 Agent Wallet 时生成的"主密码"像下面这样告诉工具即可： + +```bash +export AGENT_WALLET_PASSWORD='你的主密码' +``` + +就这一行配置！设置好口令后，整个系统就能全自动无缝配合了。你的 AI 代理将彻底蜕变为一个既聪明能干，又绝对安全的 Web3 顶级私人管家！ + +> 迫不及待想试试？去 👉 **[快速开始](./QuickStart.md)** 跟着做一遍。 + +### ⌨️ 我是进阶用户——想用 CLI 管理钱包 + +需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。 + +### 👨‍💻 我是开发者——自己写代理 + +
+展开开发者路径 — TypeScript / Python SDK + +Agent-wallet 提供了完整的 SDK，TypeScript 和 Python 双语言支持，共享同一套接口： + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); +``` + +同一个密钥文件、同一份数据、同一个签名结果。 + +> **[SDK 接入指南](./Developer/SDK-Guide.md)** 手把手教你接入。 +> **[完整代码示例](./Developer/SDK-Cookbook.md)** 展示端到端的真实交易：TRON 转账、BSC 转账、x402 支付签名。 + +
+ +--- + +## 支持的链 + +| 链类型 | 网络 | +| :--- | :--- | +| **EVM** | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链（主网和测试网均支持） | +| **TRON** | TRON 主网、Nile 测试网、Shasta 测试网 | + +两类链共用同一套接口——学一次，到处用。 + +--- + +## 还有疑问？ + +| 我在想… | 去这里 | +| :--- | :--- | +| AI 代理会不会把我的钱全转走？ | [FAQ](./FAQ.md) — 我们有专门的风险隔离方案 | +| 没写过代码？ | [快速开始](./QuickStart.md) | +| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) | +| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) | +| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md new file mode 100644 index 00000000..5fb74d6e --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -0,0 +1,188 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 快速开始 + +三步，从零到在 OpenClaw 聊天框里唤醒你的 Agent-wallet。不用写代码，不花一分钱 Gas 费——复制粘贴就行。 + +:::tip 想看 CLI 命令细节？ +本页只带你跑通最短路径。免密配置、管理多个钱包、签名类型等进阶内容，请看 [CLI 命令行手册](./Developer/CLI-Reference.md)。 +::: + +--- + +## 第一步：安装并初始化钱包 + +### 1.1 准备环境：安装 Node.js + +Agent-wallet 需要你的电脑里有 Node.js（这是一个运行环境，版本需 >= 18）。 + +打开终端（Mac 用户按 `Command + 空格` 搜索"终端"），输入： + +```bash +node -v +``` + +- **如果输出 `v18.x.x` 或更高数字：** 太棒了，直接跳到 1.2！ +- **如果没有输出或报错：** 别慌，去 **[Node.js 官方网站](https://nodejs.org)** 下载最新的 **LTS** 安装包，像装普通软件一样双击安装，一路"下一步"即可。装完后关掉终端重新打开，再输入 `node -v` 确认。 + +
+开发者首选：使用 nvm 安装（小白请跳过） + +```bash +# 1. 安装 nvm（已有可跳过） +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# 2. 重新加载终端配置 +source ~/.bashrc # zsh 用户改成 source ~/.zshrc + +# 3. 安装并切换到 Node.js 18 +nvm install 18 && nvm use 18 +``` + +
+ +### 1.2 安装 Agent-wallet + +```bash +npm install -g @bankofai/agent-wallet +``` + +验证安装成功： +```bash +agent-wallet --help +``` + +看到帮助信息就说明安装好了。 + +### 1.3 创建你的 Agent-wallet 钱包 + +运行： +```bash +agent-wallet start +``` + +系统会引导你初始化 **Agent-wallet 钱包**。整个过程是交互式的——跟着提示走就行： + +``` +? Quick start type: local_secure — Encrypted key stored locally (recommended) +Wallet ID (e.g. my_wallet_1) (default): + +Wallet initialized! +? Import source: generate — Generate a new random private key + +Wallets: +┌───────────┬──────────────┐ +│ Wallet ID │ Type │ +├───────────┼──────────────┤ +│ default │ local_secure │ +└───────────┴──────────────┘ + +Your master password: <此处会显示你的专属密码> + Save this password! You'll need it for signing and other operations. + +Active wallet: default +``` + +:::caution 主密码 = 你所有资产的唯一钥匙 +这个密码是解开所有私钥的唯一凭证。**忘了就找不回来——我们也没有备份，没有后门，神仙难救。** + +请现在就做这件事： +1. 打开你的密码管理器（1Password、Bitwarden 等） +2. 新建一条记录，把主密码存进去 +3. 不要截图，不要记在桌面便签上，不要发给自己的微信 +::: + +--- + +## 第二步：把密码"喂"给 AI 代理（极其重要！） + +为了让 OpenClaw 能自动使用你的钱包，你必须把密码配置到它的运行环境中。请根据你的电脑系统，选择对应的标签页，**无脑复制执行**即可。 + +### 2.1 保存并使密码生效 + + + + +**第 1 步：** 用编辑器打开 `~/.zshrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： + +```bash +open -e ~/.zshrc +``` + +在文件末尾添加这一行，保存并关闭： + +```bash +export AGENT_WALLET_PASSWORD='你的主密码' +``` + +**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效： + +```bash +source ~/.zshrc +``` + +:::tip 为什么不用 echo 命令？ +`echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。 +::: + + + + +**第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： + +```bash +nano ~/.bashrc +``` + +在文件末尾添加这一行，保存并关闭（nano 中按 `Ctrl + O` 保存，`Ctrl + X` 退出）： + +```bash +export AGENT_WALLET_PASSWORD='你的主密码' +``` + +**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效： + +```bash +source ~/.bashrc +``` + + + + + + + + + +:::caution 密码有特殊字符？千万不要动单引号！ +自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉： + +```bash +# ✅ 正确 — 单引号，密码原样保存 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ 错误 — 双引号，$w0rd 被 shell 展开为空字符串，密码静默出错 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" +``` +::: + +### 2.2 重启你的 AI 代理后台服务 + +:::danger 这一步很多人忘了，结果 AI 代理死活读不到密码！ +因为你刚才新存了密码，而正在后台运行的 AI 助手还没刷新——它还是个"瞎子"！只有关掉它重新启动，它才能"看"到你的新密码。 +::: + +不管你现在是否正开着 OpenClaw 的后台服务，请务必将它**关闭**，然后在刚才执行过命令的终端窗口里，**重新启动**它。 + +--- + +## 你已经跑通了全流程 + +| 我想… | 去这里 | +| :--- | :--- | +| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) | +| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) | +| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) | +| 了解安全设计原理 | [简介](./Intro.md) | +| 查看常见问题 | [FAQ](./FAQ.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md index 6ce0f812..43aba1c6 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md @@ -1,11 +1,11 @@ # 简介 -BANK OF AI 通过 **MCP Server** 与 **Skills** 构建了一套完整的 AI Agent 能力体系：前者负责提供标准化的区块链交互能力，后者负责将这些能力组织为可执行的任务流程，从而支持 AI Agents 在链上环境中完成复杂操作。 +BANK OF AI 通过 **MCP Server** 与 **Skills** 构建了一套完整的 AI Agent 能力体系：前者是"锅碗瓢盆"——提供标准化的区块链交互工具；后者是"米其林菜谱"——将这些工具编排为可执行的任务流程，让 AI 在链上环境中像老手一样完成复杂操作。 -* **MCP Server** 旨在为大型语言模型 (LLM) 与外部工具和数据源之间的交互提供一个标准化的框架。其核心在于一个清晰定义的客户端-服务器架构和分层通信机制，确保了 AI 应用能够安全、高效地访问和利用外部信息。 -* **Skills** 是用于将多个工具按流程编排起来，帮助 AI 完成复杂任务的能力封装。 +* **MCP Server** 为大型语言模型 (LLM) 与外部工具和数据源之间的交互提供标准化框架。其核心是清晰定义的客户端-服务器架构和分层通信机制，确保 AI 应用能安全、高效地访问和利用外部信息。 +* **Skills** 是用于将多个工具按流程编排起来的"任务操作手册"，帮助 AI 完成复杂的多步骤任务——从 DEX 交易、永续合约到链上数据分析。 ## 快速导航 - **了解 MCP Server**：前往 [MCP Server 简介](./MCP/Intro.md)，了解协议架构与通信机制。 -- **了解 Skills**：前往 [Skills 简介](./SKILLS/Intro.md)，了解技能包的设计理念与使用方式。 +- **了解 Skills**：前往 [Skills 简介](./SKILLS/Intro.md)，了解技能包的设计理念、一键安装和使用方式。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md index a8f2f872..86978c0b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md @@ -6,7 +6,7 @@ MCP Server 旨在为大型语言模型 (LLM) 与外部工具和数据源之间 MCP 遵循**客户端-服务器**架构，主要包含以下三个核心参与者： -* **MCP 主机**：通常是 AI 应用程序本身（例如 Claude Code 或 Claude Desktop）。它负责协调和管理一个或多个 MCP 客户端。 +* **MCP 主机**：通常是 AI 应用程序本身。它负责协调和管理一个或多个 MCP 客户端。 * **MCP 客户端**：由 MCP 主机为每个 MCP 服务器实例化。每个客户端维护与对应 MCP 服务器的专用连接，并从服务器获取上下文信息供主机使用。 * **MCP 服务器**：一个程序，负责向 MCP 客户端提供上下文数据。服务器可以是本地运行的（例如文件系统服务器），也可以是远程运行的（例如 TRON MCP/SUN MCP 服务器）。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 9e29354e..dd2f8ff1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -9,9 +9,9 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi ## 连接问题 -### Claude Desktop "无法连接到 MCP 服务器" +### MCP 客户端 "无法连接到 MCP 服务器" -**症状：** Claude Desktop 显示服务器未响应或连接被拒绝。 +**症状：** MCP 客户端 显示服务器未响应或连接被拒绝。 **解决步骤：** @@ -31,12 +31,12 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi ``` 3. **检查 JSON 格式** - - 在 Claude Desktop 配置中验证 `stdio.json` 的 JSON 格式 + - 在 MCP 客户端 配置中验证 `stdio.json` 的 JSON 格式 - 常见错误：末尾多余逗号、未匹配的括号 -4. **重启 Claude Desktop** +4. **重启 MCP 客户端** - 完全关闭应用程序 - - 清除缓存：删除 `~/.claude` 目录中的临时文件 + - 清除缓存（方法取决于你使用的特定 MCP 客户端） - 重新启动应用程序 5. **检查服务器日志** @@ -85,10 +85,7 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi **解决方案：** -1. **配置 Agent Wallet** - ```bash - export AGENT_WALLET_PASSWORD="your_secure_password" - ``` +1. **配置 [Agent Wallet](../../../Agent-Wallet/Intro)**（推荐）— 设置 `AGENT_WALLET_PASSWORD` 2. **或配置私钥（仅测试网）** ```bash @@ -100,7 +97,7 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi export TRON_MNEMONIC="word1 word2 ... word12" ``` -4. **重新启动服务器**并重新连接 Claude Desktop +4. **重新启动服务器**并重新连接 MCP 客户端 验证配置成功的方式：查看 [完整能力清单](ToolList.md) 中的完整能力清单。 @@ -136,32 +133,9 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **解决步骤：** -1. **验证密码环境变量** - ```bash - echo $AGENT_WALLET_PASSWORD - # 应输出你的密码 - ``` - -2. **检查 Agent Wallet 目录** - ```bash - # 默认位置 - ls ~/.agent-wallet/ - # 应包含 wallet.json 等文件 - ``` - -3. **重新初始化 Wallet** - ```bash - # 删除现有 wallet（备份重要数据！） - rm -rf ~/.agent-wallet/ - - # 使用正确的密码重启服务器 - export AGENT_WALLET_PASSWORD="your_new_password" - sun-mcp-server - ``` - -4. **验证密码复杂性** - - 使用强密码（最少 8 字符） - - 避免特殊字符，使用字母数字组合 +1. **验证密码已设置**：运行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 确认变量已设置（不会泄露密码明文）。 +2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 +3. **密码丢失**：需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 ### "Conflicting wallet modes" @@ -174,17 +148,17 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' ```bash # 选项 1：Agent Wallet（推荐用于生产） -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' unset TRON_PRIVATE_KEY unset TRON_MNEMONIC # 选项 2：私钥（仅限测试网） -export TRON_PRIVATE_KEY="your_64_hex_chars" +export TRON_PRIVATE_KEY='your_64_hex_chars' unset AGENT_WALLET_PASSWORD unset TRON_MNEMONIC # 选项 3：助记词 -export TRON_MNEMONIC="word1 word2 ... word12" +export TRON_MNEMONIC='word1 word2 ... word12' unset AGENT_WALLET_PASSWORD unset TRON_PRIVATE_KEY ``` @@ -195,7 +169,7 @@ unset TRON_PRIVATE_KEY unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC # 只设置一个 -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' # 重启服务器 sun-mcp-server @@ -290,19 +264,14 @@ sun-mcp-server 1. **检查 Wallet 支持** ```bash # Agent Wallet 必须支持 signTypedData - echo $AGENT_WALLET_PASSWORD # 确认已设置 + [[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置" ``` 2. **验证签名数据** - 检查 Permit2 请求的结构化数据 - 确认链 ID、代币地址、截止时间正确 -3. **重新初始化 Wallet** - ```bash - rm -rf ~/.agent-wallet/ - export AGENT_WALLET_PASSWORD="your_password" - sun-mcp-server - ``` +3. **重新初始化 Wallet** — 运行 `agent-wallet reset` 清除并重新开始。详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)。 4. **使用备用授权方法** ``` @@ -427,7 +396,7 @@ sun-mcp-server **是的。** 例如，可以同时运行官方主网服务器和本地 Nile 实例。 -**配置示例（Claude Desktop）：** +**配置示例（MCP 客户端）：** ```json { diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 74b51e8a..9a3062d2 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 本地私有化部署 ## 什么是本地私有化部署？ @@ -61,29 +58,18 @@ import TabItem from '@theme/TabItem'; #### 方式一：通过 Agent Wallet（推荐）创建钱包 -这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 - -**安装并初始化 Agent Wallet：** +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。Agent Wallet 还支持**多钱包管理**和运行时通过 `select_wallet` 工具切换钱包。 -```bash -# 安装 -npm install -g @bankofai/agent-wallet +> Agent Wallet 的安装、初始化及详细用法请参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro)。 -# 创建加密钱包 -agent-wallet start -``` -Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 - -> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 - -**设置环境变量：** +**初始化 Agent Wallet 后设置环境变量：** ```bash # 添加到 ~/.zshrc 或 ~/.bashrc -export AGENT_WALLET_PASSWORD="<你的主密码>" +export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` @@ -173,123 +159,8 @@ npm install -g @bankofai/sun-mcp-server sun-mcp-server ``` ---- - -### 第三步：客户端配置 - -配置完成后，需要在 AI 客户端中添加 SUN MCP Server 的连接定义。 - -#### 找到配置文件 - -根据您使用的 AI 客户端，配置文件位置如下： - -| 客户端 | 配置文件路径 | -|--------|-------------| -| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | -| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | -| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` 或通过环境变量 | - -#### 添加服务器定义 - -选择与您的部署方式对应的选项卡： - - - - -**Claude Desktop 配置：** - -在 `~/.claude/resources/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_NETWORK": "nile" - } - } - } -} -``` - -**Claude Code** - -```bash -# 基础配置 -claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server - -# 携带环境变量 -claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server -``` - -**Cursor 配置：** - -在 `~/.cursor/extensions/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` - - - - -适用于从源码运行的情况。 - -**Claude Desktop 配置：** - -在 `~/.claude/resources/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_NETWORK": "nile" - } - } - } -} -``` - -**Cursor 配置：** - -在 `~/.cursor/extensions/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` - - - - +#### 方式 C：HTTP 模式 以 HTTP 服务器模式运行 SUN MCP Server，允许远程连接。 @@ -299,39 +170,12 @@ claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/s sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -**Claude Desktop 配置：** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - -**Cursor 配置：** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - :::warning HTTP 模式适用于本地开发和测试。对于远程部署，请使用 HTTPS 和适当的身份验证。 ::: - - - -:::tip 关于环境变量部分 -- **npx 运行**：环境变量在配置文件的 `"env"` 字段中设置，或直接在终端导出后运行。 +:::tip 关于环境变量 +- **npx 运行**：在运行命令前直接在终端导出环境变量。 - **HTTP 模式**：启动 HTTP 服务器时，环境变量应在启动命令前导出： ```bash @@ -339,11 +183,20 @@ export TRON_NETWORK=nile sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -- **重启生效**：修改配置后，需重启 AI 客户端使更改生效。 +- **客户端配置**：服务器运行后，配置你的 MCP 客户端以连接到它。 ::: --- +### 第三步：客户端配置 + +服务器运行后，需要配置你的 MCP 客户端与其连接。请参考你的 MCP 客户端文档获取配置说明。服务器可通过以下方式访问： + +- **npx/本地构建**：通常作为客户端管理的子进程运行 +- **HTTP 模式**：`http://127.0.0.1:8080/mcp`（或你指定的主机/端口） + +--- + ### 第四步：验证接入是否成功 启动 AI 客户端后，应该能看到 SUN MCP Server 的工具列表。进行以下测试以确认配置正确： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 17dd6efe..1aa5514b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,31 +1,24 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 官方云服务接入 ## 什么是官方云服务？ 官方云服务是由 **BANK OF AI** 托管的 SUN MCP Server 实例，用于为 AI 客户端提供 **SunSwap 链上数据的只读查询能力**。 -如果你想让 AI 助手查询 SunSwap 上的代币价格、池子 APY、协议交易量，或者分析某个地址的流动性持仓——这些都是只读操作，通过官方云服务即可完成，不需要在本地安装任何东西，也不需要提供任何钱包凭证。 +如果你想让 AI 助手查询 SunSwap 上的代币价格、池子 APY、协议交易量，或者分析某个地址的流动性持仓——这些都是只读操作，通过官方云服务即可完成，不需要提供任何钱包凭证。 **官方云服务的核心作用，就是将基础设施工作全部托管。** 你只需要在 AI 客户端的配置中添加一行服务地址，即可开始与 SunSwap 对话。 ### 使用官方云服务的主要优点 -**1. 无需任何本地安装** - -不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 - -**2. 无私钥暴露风险** +**1. 无私钥暴露风险** 由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露的风险。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 -**3. 官方维护与持续升级** +**2. 官方维护与持续升级** 云服务始终运行最新稳定版本，包括 SunSwap 协议更新的适配和 SUN.IO API 的同步。你无需关心版本号，也不需要手动重新构建。 -**4. 覆盖大量实用场景** +**3. 覆盖大量实用场景** 查询代币价格和兑换报价、分析池子数据和 APY、获取协议统计和历史指标、查看用户流动性持仓——这些日常最常用的 DeFi 数据查询，通过云服务全部可以完成。只有当你需要实际执行兑换或管理流动性时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 @@ -39,150 +32,96 @@ import TabItem from '@theme/TabItem'; ## 如何接入官方云服务？ -要接入官方云服务，只需在 AI 客户端配置中添加以下 MCP 服务地址： +### 一键自动安装 -**`https://sun-mcp-server.bankofai.io/mcp`** +只需告诉你的 AI Agent 执行以下命令： -> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 +```bash +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y +``` ---- +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 -## 客户端配置 - - - - -配置文件路径： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -**基础配置**： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` +安装完成后，重启 AI Agent，即可使用 SUN MCP Server 开始与 SunSwap 交互。 - - +### 交互式安装 -**命令行添加**： +如果你想手动选择安装到哪些 AI 工具，去掉 `-y` 参数即可： ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -**或在项目根目录添加 `.mcp.json`**： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "type": "http", - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。 +::: - - +#### 安装过程详解 -在项目根目录添加 `.cursor/mcp.json`： +安装器会引导你完成以下几步，照着做就行： -```json -{ - "mcpServers": { - "sun-mcp-server": { - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` +**1️⃣ 识别服务来源** - - +安装器会自动识别远程 MCP 服务地址，并为其生成服务名称： -如果你想将 SUN MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 +``` +◇ Source: https://sun-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: sun-mcp-server +``` -**第一步：初始化连接** +**2️⃣ 选择要安装到哪些 AI 工具** -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' -``` +安装器会自动检测你电脑上装了哪些 AI 工具（如 Claude Code、Cursor、Cline 等），用空格键勾选你要用的： -响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code +``` -**第二步：调用工具** +**3️⃣ 确认安装信息** -使用第一步获得的 `mcp-session-id`： +安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装： -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "getPrice", - "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} - }, - "id": 2 - }' +``` +◇ Installation Summary ───╮ +│ │ +│ Server: sun-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├──────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes ``` -**第三步：查看可用工具列表** +**4️⃣ 安装完成！** -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` +看到类似以下输出，说明 SUN MCP Server 已经成功安装到你选择的 AI 工具中： -:::info Session 管理 -- 每次 `initialize` 会创建一个新 Session -- Session 在 30 分钟无活动后自动过期 -- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session -::: +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` - - +安装完成后，重启 AI Agent，即可使用 SUN MCP Server 开始与 SunSwap 交互。 --- ## 验证接入是否成功 -配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： +接入完成后，你可以直接向 AI Agent 提出以下问题来测试： ``` 查一下 SunSwap 上 USDT 和 TRX 的当前价格 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 0d20a5e0..f79aed61 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 快速开始 这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次 DeFi 查询。** @@ -14,69 +11,25 @@ import TabItem from '@theme/TabItem'; 在开始之前，请确保你已经有： 1. **Node.js** >= 20.0.0（[下载链接](https://nodejs.org/)） -2. **MCP 客户端**：所有支持 MCP 的 AI 客户端。例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 +2. **MCP 客户端**：所有支持 MCP 的 AI 客户端。 --- -## 添加配置 - -根据你使用的工具选择对应的配置方式： - - - - -1. 打开 Claude Desktop 的配置文件： - - **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -2. 在 `mcpServers` 部分添加以下配置： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. 保存文件并重启 Claude Desktop。 +## 安装 - - - - -在终端中运行以下命令添加 SUN MCP Server： +只需告诉你的 AI Agent 执行以下命令： ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y ``` - - - - -1. 打开 Cursor 的配置文件：`.cursor/mcp.json` +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 -2. 在配置中添加： +命令完成后，重启你的 MCP 客户端。 -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. 保存文件并重启 Cursor。 - - - +:::tip 想手动选择安装到哪些 AI 工具？ +去掉 `-y` 参数即可进入交互式安装，详见[官方云服务接入](./OfficialServerAccess.md)。 +::: --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 1f7053e9..84f200bc 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -8,7 +8,7 @@ 连接问题通常发生在首次配置阶段。如果 AI 客户端无法识别 TRON 工具，多半是这里出了问题。 -### Claude Desktop 提示"无法连接到 MCP 服务器" +### 你的 MCP 客户端提示"无法连接到 MCP 服务器" 这是最常见的问题。按以下顺序逐一排查： @@ -20,15 +20,11 @@ 2. **检查 npx 是否可用**。在终端运行 `npx --version`。如果找不到命令，说明 Node.js 安装不完整，需要重新安装。 -3. **验证配置文件格式**。`claude_desktop_config.json` 必须是合法的 JSON。常见错误包括多余的逗号、缺少引号或括号不匹配。可以用这个命令快速验证： - ```bash - cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool - ``` - 如果输出了格式化的 JSON，说明格式没问题。如果报错，按照错误提示修复。 +3. **验证配置文件格式**。你的 MCP 客户端配置文件必须是合法的 JSON。常见错误包括多余的逗号、缺少引号或括号不匹配。使用 JSON 校验工具验证你的配置文件。 -4. **完全重启**。关闭窗口不等于退出——你需要从菜单栏/系统托盘彻底退出 Claude Desktop，然后重新打开。macOS 上可以在 Dock 图标上右键选择"退出"。 +4. **完全重启**。关闭窗口不等于退出——你需要彻底退出你的 MCP 客户端，然后重新打开。 -5. **查看日志**。如果以上都没解决问题，查看 Claude Desktop 的日志文件。macOS 上在 `~/Library/Logs/Claude/` 目录下，搜索包含 "mcp" 或 "tron" 的条目。 +5. **查看日志**。如果以上都没解决问题，查看你的 MCP 客户端的日志文件，搜索包含 "mcp" 或 "tron" 的条目。 ### HTTP 模式下"连接被拒绝" @@ -57,7 +53,7 @@ 要解锁写入工具，配置以下三种钱包模式之一： -- 设置 `AGENT_WALLET_PASSWORD`（Agent Wallet 模式，推荐） +- 设置 `AGENT_WALLET_PASSWORD`（[Agent Wallet](../../../Agent-Wallet/Intro) 模式，推荐） - 设置 `TRON_PRIVATE_KEY`（私钥模式） - 设置 `TRON_MNEMONIC`（助记词模式） @@ -91,18 +87,9 @@ ### "Agent Wallet 密码错误" -`AGENT_WALLET_PASSWORD` 必须与执行 `agent-wallet init` 时设置的主密码完全一致。如果你不确定： +`AGENT_WALLET_PASSWORD` 必须与运行 `agent-wallet start` 时生成的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -1. **检查钱包目录是否存在**： - ```bash - ls ~/.agent-wallet/ # 默认位置 - ``` - 如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 - -2. **密码丢失**时需要重新初始化。注意：这会创建一个新的钱包，旧钱包的资金需要通过其他方式恢复。 - ```bash - agent-wallet init - ``` +如果密码丢失，需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 @@ -200,25 +187,7 @@ AI 可能将 TRON MCP Server 的能力与其他区块链工具混淆。如果它 ### 能否同时使用多个 TRON MCP Server 实例？ -可以。在配置中定义多个 MCP Server 条目即可——比如一个连接主网云服务（只读），另一个连接本地测试网部署（带钱包）。只需使用不同的名称： - -```json -{ - "mcpServers": { - "tron-mainnet": { - "command": "npx", - "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] - }, - "tron-local": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "your-password" - } - } - } -} -``` +可以。在 MCP 客户端配置中定义多个 MCP Server 条目即可——比如一个连接主网云服务（只读），另一个连接本地测试网部署（带钱包）。在客户端的 MCP 配置中使用不同的名称配置这两个服务。 ### 如何更新到最新版本？ @@ -240,3 +209,4 @@ npm run build ### 支持哪个 MCP 协议版本？ TRON MCP Server 支持 MCP 协议版本 **2025-11-25**，使用 `@modelcontextprotocol/sdk` 1.22.0 或更高版本。 + diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md index 0e7421f1..08f964a1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -8,7 +8,7 @@ TRON MCP Server 是连接 AI 助手与 TRON 区块链的桥梁。它基于 [Mode 这对不同的人意味着不同的事情： -- 如果你是 **AI 应用用户**，它让你在 Claude Desktop、Cursor 等工具中直接操作区块链，和日常聊天一样简单。 +- 如果你是 **AI 应用用户**，它让你在支持 MCP 的 AI 工具中直接操作区块链，和日常聊天一样简单。 - 如果你是 **Web3 开发者**，它是你的链上快速原型工具——用自然语言调试合约、查询状态，省去大量样板代码。 - 如果你是 **AI Agent 构建者**，它提供了 95 个标准化的链上工具，可以直接编排进你的自动化流程。 - 如果你是 **数据分析师**，它让链上数据查询变成了对话，不再需要写脚本抓取和解析。 @@ -78,10 +78,10 @@ TRON MCP Server 覆盖了 TRON 区块链上几乎所有常见操作，从只读 --- ## 安全注意事项 -:::warning +:::warning 在开始使用之前，有几条安全原则值得牢记——尤其是在涉及真实资产的操作中： -- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件（如 `claude_desktop_config.json`），应通过系统环境变量或加密钱包管理。 +- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件，应通过系统环境变量或加密钱包管理。 - **先在测试网验证**：任何链上操作在主网执行前，先在 Nile 或 Shasta 测试网上跑通。 - **最小资金原则**：为 AI Agent 配置的钱包只存放执行任务所需的最低金额。 - **注意授权风险**：代币授权（`approve`）操作要格外谨慎，避免授予无限额度。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 62c96127..f07ad8dd 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 本地私有化部署 ## 什么是本地私有化部署？ @@ -46,7 +43,7 @@ node --version # 应输出 v20.x.x 或更高 在配置钱包之前，请务必理解以下安全原则： :::danger 安全警告 -**切勿**将私钥或助记词直接保存在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中。这些文件通常未加密，可能被意外分享或提交到 Git。请务必使用系统环境变量或加密钱包。 +**切勿**将私钥或助记词直接保存在 MCP 配置文件中。这些文件通常未加密，可能被意外分享或提交到 Git。请务必使用系统环境变量或加密钱包。 ::: --- @@ -67,29 +64,18 @@ node --version # 应输出 v20.x.x 或更高 #### 方式一：通过 Agent Wallet（推荐）创建钱包 -这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 - -**安装并初始化 Agent Wallet：** - -```bash -# 安装 -npm install -g @bankofai/agent-wallet - -# 创建加密钱包 -agent-wallet start -``` -Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。Agent Wallet 还支持**多钱包管理**和运行时通过 `select_wallet` 工具切换钱包。 -> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 +> Agent Wallet 的安装、初始化及详细用法请参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro)。 -**设置环境变量：** +**初始化 Agent Wallet 后设置环境变量：** ```bash # 添加到 ~/.zshrc 或 ~/.bashrc -export AGENT_WALLET_PASSWORD="<你的主密码>" +export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` @@ -178,149 +164,28 @@ npm install npm run build ``` ---- - -### 第四步：客户端配置 - -环境变量和安装都准备好了，现在把 AI 客户端指向本地服务器。 - -#### 找到配置文件 - -| 应用程序 | 操作系统 | 配置路径 | -| :--- | :--- | :--- | -| **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Cursor** | 所有 | 项目根目录：`.cursor/mcp.json` | -| **Google Antigravity** | 所有 | `~/.config/antigravity/mcp.json` | -| **Opencode** | 所有 | `~/.config/opencode/mcp.json` | - -#### 添加服务器定义 - - - - -直接从 npm 运行最新版本，无需克隆仓库。 - -**Claude Desktop**（`claude_desktop_config.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - -**Claude Code**： - -```bash -# 基础配置 -claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron - -# 携带环境变量 -claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron -``` - -**Cursor**（`.cursor/mcp.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - - - - -适用于从克隆仓库运行的开发者。 - -**Claude Desktop**（`claude_desktop_config.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - -将路径替换为你实际克隆的仓库路径。 - -**Cursor**（`.cursor/mcp.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - - - - -如果你以 HTTP 模式启动了服务器（`npm run start:http`），通过 HTTP URL 连接： +#### 方式 C：以 HTTP 模式运行 -**Claude Code**： +启动服务器的 HTTP 模式，然后通过 HTTP 端点连接你的 MCP 客户端： ```bash -claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp +npm run start:http ``` -**Cursor**（`.cursor/mcp.json`）： +这会启动一个本地 HTTP 服务器（默认：`http://localhost:3001/mcp`），你的 MCP 客户端可以连接到它。 -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "http://localhost:3001/mcp" - } - } -} -``` +#### 配置说明 - - +如果你要配置 MCP 客户端指向本地服务器： -:::tip 关于配置中的 `env` 部分 -如果你已经在系统中设置了环境变量（通过 `~/.zshrc` 或 `~/.bashrc`），可以完全省略配置中的 `env` 部分，服务器会自动读取系统环境变量。 +- **如果通过 npx 或源码运行**：在 MCP 客户端配置中使用相应的命令（例如 `command: npx` 加上 `args: ["-y", "@bankofai/mcp-server-tron"]`） +- **如果以 HTTP 模式运行**：通过 HTTP URL 配置选项将客户端指向 `http://localhost:3001/mcp` -如果你的 MCP 客户端不继承系统环境变量，则需要在 `env` 部分中设置。此时**请确保该配置文件不会被分享或提交到版本控制系统**。 -::: +如果你的 MCP 客户端不继承系统环境变量，则需要在客户端设置中显式配置它们。**请确保任何存储凭证的配置文件不会被分享或提交到版本控制系统**。 --- -### 第五步：验证接入是否成功 +### 第四步：验证接入是否成功 完成配置后，**完全退出并重启** AI 客户端，然后尝试： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index c964fdd5..a1647e14 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 官方云服务接入 ## 什么是官方云服务？ @@ -20,15 +17,11 @@ import TabItem from '@theme/TabItem'; ### 使用官方云服务的主要优点 -**1. 无需任何本地安装** - -不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 - -**2. 无私钥暴露风险** +**1. 无私钥暴露风险** 由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露、配置文件被误提交到 Git 等安全隐患。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 -**3. 官方维护与持续升级** +**2. 官方维护与持续升级** 云服务由官方统一维护，始终运行最新稳定版本的 TRON MCP Server。包括： @@ -38,7 +31,7 @@ import TabItem from '@theme/TabItem'; 你无需关心版本号，也不需要手动执行 `npm install` 或重新构建。 -**4. 覆盖绝大部分真实场景** +**3. 覆盖绝大部分真实场景** 日常中最常用的操作——查地址余额、分析交易详情、读取合约状态、查看超级代表列表、监控链上事件——全部属于只读查询，通过云服务就能完整覆盖。只有当你需要实际转移资产（转账、质押、合约写入等）时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 @@ -52,205 +45,96 @@ import TabItem from '@theme/TabItem'; ## 如何接入官方云服务？ -要接入官方云服务，只需要在 AI 客户端配置中添加官方提供的 **MCP 服务地址**：[https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) - - -> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 - -官方云服务支持 **两种使用模式**： - -| 模式 | 限速 | 说明 | -| :--- |--- |:--- | -| **无 TronGrid API Key（默认）** | 100,000 Requests / Day |即开即用，适合入门体验和低频查询 | -| **带 TronGrid API Key** | 500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | - -两种模式的接入方式完全相同，区别仅在于请求频率限制。 +### 一键自动安装 ---- +只需告诉你的 AI Agent 执行以下命令： -### 无 TronGrid API Key 模式（默认） +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y +``` -不配置任何 API Key 即可直接使用。适用于： +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 -- 首次体验 TRON MCP Server -- 偶尔查询链上数据 -- 教学演示和功能验证 +安装完成后，重启 AI Agent，即可使用 TRON MCP Server 开始与 TRON 区块链交互。 -在这种模式下，所有工具均可正常调用，但主网查询在高频场景下可能触发 TronGrid 公共 RPC 的速率限制。 +### 交互式安装 ---- +如果你想手动选择安装到哪些 AI 工具，去掉 `-y` 参数即可： -### 带 TronGrid API Key 模式（推荐） +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp +``` -如果你需要频繁查询主网数据，建议申请一个免费的 TronGrid API Key 以获得更高的请求频率上限。 +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。 +::: -**申请步骤：** +#### 安装过程详解 -1. 访问 [trongrid.io](https://www.trongrid.io/) -2. 注册账号并创建项目 -3. 复制生成的 API Key -4. 在配置中添加 API Key 请求头（见下方客户端配置示例） +安装器会引导你完成以下几步，照着做就行： -配置 API Key 后，你的请求会通过 TronGrid 的认证通道，享受更稳定的性能和更高的吞吐量。 +**1️⃣ 识别服务来源** ---- +安装器会自动识别远程 MCP 服务地址，并为其生成服务名称： -## 客户端配置 - - - - -配置文件路径： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -**基础配置（不含 API Key）**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} ``` - -**含 TronGrid API Key 的配置**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} +◇ Source: https://tron-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: tron-mcp-server ``` -将 `` 替换为你的实际 TronGrid API Key。 - - - +**2️⃣ 选择要安装到哪些 AI 工具** -**命令行添加**： +安装器会自动检测你电脑上装了哪些 AI 工具（如 Claude Code、Cursor、Cline 等），用空格键勾选你要用的： -```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp ``` - -**或在项目根目录添加 `.mcp.json`**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "type": "http", - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code ``` - - +**3️⃣ 确认安装信息** -在项目根目录添加 `.cursor/mcp.json`： +安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装： -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} ``` - - - - -如果你想将 TRON MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 - -**第一步：初始化连接** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' +◇ Installation Summary ────╮ +│ │ +│ Server: tron-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├───────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes ``` -响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 - -**第二步：调用工具** +**4️⃣ 安装完成！** -使用第一步获得的 `mcp-session-id`： +看到类似以下输出，说明 TRON MCP Server 已经成功安装到你选择的 AI 工具中： -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' ``` - -**第三步：查看可用工具列表** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! ``` -:::info Session 管理 -- 每次 `initialize` 会创建一个新 Session -- Session 在 30 分钟无活动后自动过期 -- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session -::: - - - +安装完成后，重启 AI Agent，即可使用 TRON MCP Server 开始与 TRON 区块链交互。 --- ## 验证接入是否成功 -配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： +接入完成后，你可以直接向 AI Agent 提出以下问题来测试： ``` 查询 TRON 主网当前的区块高度 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index d3cde4b3..4f7fe27f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 快速开始 这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次区块链查询。** @@ -13,7 +10,7 @@ import TabItem from '@theme/TabItem'; 在开始之前，确保你已经安装了以下工具： -- 所有支持 MCP 的 AI 客户端：例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 +- 所有支持 MCP 的 AI 客户端 - **Node.js v20.0.0 或更高版本**（用于执行 `npx` 命令）（[Node.js 下载](https://nodejs.org/)） 验证 Node.js 版本： @@ -24,59 +21,21 @@ node --version # 应输出 v20.x.x 或更高 --- -## 添加配置 - -选择你使用的 AI 客户端，把对应的配置复制进去： - - - +## 安装 -打开配置文件： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -添加以下内容： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - -在终端执行： +只需告诉你的 AI Agent 执行以下命令： ```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y ``` - - +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 -在项目根目录添加 `.cursor/mcp.json`： +命令完成后，重启你的 MCP 客户端。 -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - +:::tip 想手动选择安装到哪些 AI 工具？ +去掉 `-y` 参数即可进入交互式安装，详见[官方云服务接入](./OfficialServerAccess.md)。 +::: --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index dd5dd885..f3c8ac77 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -30,8 +30,8 @@ TRON MCP Server 提供 **95 个工具**、**6 个提示词模板**和 **1 个资 | 工具名称 | 描述 | 关键参数 | 模式 | | :--- | :--- | :--- | :--- | | `get_wallet_address` | 获取当前已配置钱包的地址（Base58 和 Hex 格式） | - | 读取 | -| `list_wallets` | 列出所有可用钱包的 ID 和地址（Agent Wallet 模式） | - | 读取 | -| `select_wallet` | 在运行时切换活跃钱包（Agent Wallet 模式） | `walletId` | 写入 | +| `list_wallets` | 列出所有可用钱包的 ID 和地址（[Agent Wallet](../../../Agent-Wallet/Intro) 模式） | - | 读取 | +| `select_wallet` | 在运行时切换活跃钱包（[Agent Wallet](../../../Agent-Wallet/Intro) 模式） | `walletId` | 写入 | | `sign_message` | 使用已配置的钱包对任意消息进行签名 | `message` | 写入 | | `convert_address` | 在 Hex（`41...`/`0x...`）和 Base58（`T...`）格式之间转换地址 | `address` | 读取 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 96dd9d33..aec15986 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,228 +1,191 @@ -# BANK OF AI Skills +# 技能大全 -BANK OF AI Skills 是一组为 AI 智能体设计的现成技能包，覆盖 TRON 生态的各种场景——DEX 交易、永续合约、链上数据查询、支付协议。每个技能封装了完整的业务工作流：从如何调用 API、按什么顺序执行步骤，到如何处理授权、怎样保护用户资产，全部内置在 `SKILL.md` 和配套脚本中。 +你不需要写代码，不需要懂技术。只要把下面的"参考话术"复制到 AI 对话框里，回车，AI 就会自动帮你干活。 -你无需编写代码，只需用自然语言告诉 AI 你想做什么，AI 会自动找到对应的技能并执行。 +:::warning 三条铁律 +BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤回"按钮，没有客服回滚。 -:::warning 使用任何 Skill 之前，请先阅读 -BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤销"按钮，没有客服回滚，转错地址的资金无法追回。使用前请牢记三条规则： - -1. **私钥永远不要出现在聊天窗口或配置文件中。** 只通过环境变量传递（如 `TRON_PRIVATE_KEY`）。私钥一旦泄露，请立即将资产转移到新钱包。 -2. **先测试网，后主网。** 每一个新操作都必须先在 Nile 或 Shasta 测试网上验证，再切换到主网执行。 -3. **写操作必须人工确认。** AI 在执行任何链上交易前，应向你展示完整的操作详情并等待你的明确确认。 +1. **永远不要把私钥粘贴到聊天窗口里。** 请使用 [Agent Wallet](../../Agent-Wallet/Intro.md)（相当于给 AI 开了一个专用"支付宝"，你不需要把银行卡密码直接给它）。 +2. **先用假钱练手。** 每个新操作都先在 Nile 测试网上试——测试网用的是免费"游戏币"，怎么折腾都不亏。 +3. **仔细看确认弹窗。** 任何花钱操作执行前，AI 都会把账单摊开给你看，你不点头它绝不动手。 ::: --- -## 可用技能一览 +## 技能一览表 -| Skill | 版本 | 功能概述 | 可选凭证 | -| :--- | :--- | :--- | :--- | -| **sunswap** | v2.0.0 | SunSwap DEX 交易——余额、报价、兑换、V2/V3 流动性 | `TRON_PRIVATE_KEY` | -| **sunperp-skill** | v1.0.0 | SunPerp 永续合约——行情、下单、仓位、提现 | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | -| **tronscan-skill** | v1.0.0 | TronScan 链上数据查询——账户、交易、代币、区块 | `TRONSCAN_API_KEY` | -| **x402-payment** | v1.4.0 | x402 协议支付——调用付费 API 和付费智能体 | `TRON_PRIVATE_KEY` 或 `EVM_PRIVATE_KEY` | -| **recharge-skill** | v1.1.1 | BANK OF AI 余额查询、订单记录、通过 MCP 充值 | `BANKOFAI_API_KEY` | +| 技能 | 能干什么 | 需要什么钥匙/密码？ | +| :--- | :--- | :--- | +| **sunswap** | 查价、报价、换币、管理流动性池 | 查询不需要；交易需要钱包凭证 | +| **sunperp-skill** | 看行情、开仓、平仓、提现 | 看行情不需要；交易需要 SunPerp 密钥 | +| **tronscan-skill** | 查账户、交易、代币、区块、全网数据 | 建议配置 TronScan API 密钥（不配可能卡顿） | +| **x402-payment** | 链上"先付后用"自动结算 | 需要钱包凭证 | +| **recharge-skill** | 查余额、看订单、充值 | 需要 BANK OF AI 密钥 | ---- +### 🔑 这些"钥匙"去哪领？怎么配？ + +如果你只想让 AI 帮你查查公开数据（比如币价、区块高度），你可以什么都不配，直接去玩。 -## 安装 +但如果你想解锁高级功能或交易，请根据需要去领取对应的"钥匙"： -最简单的安装方式是使用 **OpenClaw Extension**——一键安装所有组件，自动配置技能目录，AI 开箱即用： +**1. 钱包凭证（用来花钱、交易的密码）** -```bash -# 方式一：直接运行（适合信任来源） -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +- **去哪领：** 你不需要去别的地方申请，这就是你的波场钱包私钥。 +- **怎么配：** 我们在[《快速开始》](./QuickStart.md#-想让-ai-帮你交易)里准备了两种方案任你挑： + - **方案一（推荐）：** 用 [Agent Wallet](../../Agent-Wallet/QuickStart.md)，可视化界面，两分钟搞定，私钥加密存储不外露。 + - **方案二：** 直接把私钥贴进系统配置文件（记事本大法），适合老手或快速测试。 -# 方式二：先检查脚本再运行（推荐） -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +**2. TronScan API 密钥（查数据的 VIP 通行证）** -安装完成后，技能会被放置到 `~/.openclaw/skills/` 目录，OpenClaw 自动发现并加载。 +不填这个也能查数据，但查快了容易被系统拉黑限速。填了就能走 VIP 高速通道。 -安装后验证技能是否就绪： +- **去哪领（完全免费）：** 去 [TronScan 官网](https://tronscan.org/) 注册个账号，点击生成即可。 +- **怎么配：** 请参考[《快速开始》里的"想让 AI 帮你交易？"](./QuickStart.md#-想让-ai-帮你交易)，用同样的记事本大法把 `TRONSCAN_API_KEY` 贴进去就行。 -```bash -ls ~/.openclaw/skills -``` +**3. SunPerp 密钥（专门用来玩永续合约）** -你应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 +- **去哪领：** 前往 [SunPerp 官网](https://sunperp.com/)，连接你的钱包后，在账户设置里生成 API Key 和 Secret。 +- **怎么配：** 同样使用记事本大法，把 `SUNPERP_ACCESS_KEY` 和 `SUNPERP_SECRET_KEY` 贴到系统配置文件里。 -### 其他平台安装 +**4. BANK OF AI 密钥（用来给账户充值或查余额）** -如果你使用 Claude Code、Cursor 或其他支持 Skills 的 AI 工具，也可以手动安装： +- **去哪领：** 前往 [chat.bankofai.io/key](https://chat.bankofai.io/key)，登录后即可获取。 +- **怎么配：** 使用记事本大法，贴入 `BANKOFAI_API_KEY`。 -**Claude Code：** +--- -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ -``` +## 还没安装？ -Claude Code 启动时会自动加载这些技能。 +去 **[快速开始](./QuickStart.md)** 花 1 分钟装一下，装完再回来挑你想用的技能。 -**Cursor：** +--- -```bash -# 克隆到项目根目录 -git clone https://github.com/BofAI/skills.git .cursor/skills -``` +## sunswap — 换币、查价、管理池子 {#sunswap} -在 Cursor Chat 中，使用 `@` 符号引用特定 `SKILL.md` 文件提供上下文，或将技能路径添加到 `.cursorrules`。 +想在 SunSwap 上换币、查行情、管理流动性？对 AI 说下面的话就行。 -**通用方式（任何 AI 工具）：** +**绝对安全，只看不花钱：** -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` +> TRX 现在值多少钱？ -然后在对话中显式告诉 AI 读取某个技能文件： +> 100 USDT 在 SunSwap 上能换多少 TRX？ -``` -请阅读 ~/bofai-skills/sunswap/SKILL.md，帮我查询 TRX 当前价格。 -``` +> 帮我查看 SunSwap 上收益最高的 10 个池子。 ---- +> 帮我查看我当前所有的 SunSwap V3 流动性仓位。 -## 验证安装结果 +**需要你确认才会执行（AI 会先把账单给你看）：** -安装完成后，从只读操作开始是最好的起点——不需要私钥，零风险，适合熟悉技能的工作方式。 +> 在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 -在客户端输入： +> 在 SunSwap V2 的 TRX/USDT 池中添加 100 TRX 和 15 USDT 的流动性。 -``` -100 USDT 在 SunSwap 上能换多少 TRX？ -``` +> 帮我收取 V3 仓位 #12345 的手续费奖励。 -``` -帮我查一下 BTC-USDT 永续合约的当前行情。 -``` +**实战场景：** + +> 想搬砖？ "帮我算算 100 U 在 SunSwap 换成 TRX 划不划算？" + +> 想挖矿？ "SunSwap 上哪个 V3 池子年化收益最高？帮我分析一下。" + +> 想抄底？ "TRX 的价格现在处于什么位置？帮我查一下最近 7 天的走势。" --- -## 各技能使用示例 +## sunperp-skill — 永续合约交易 {#sunperp-skill} -每个示例标注了操作类型： -- 🟢 **只读** — 不产生链上交易，不需要私钥 -- ⚠️ **写操作** — 会发起链上交易，执行前需要用户确认 +想做合约？这个技能帮你看行情、开仓、平仓、设止损。内置安全锁：最高 20 倍杠杆，开仓必须设止损——默认帮你守住底线，亏损超过 5% AI 会自动帮你跑路，防止爆仓。 -### sunswap +**绝对安全，只看不花钱：** -``` -# 🟢 查询余额 -帮我查看我的 TRX 和 USDT 余额。 +> BTC-USDT 永续合约现在什么价格？24h 涨跌和资金费率呢？ -# 🟢 查询价格 -TRX 现在的价格是多少？ +> 我的 SunPerp 账户余额和可用保证金是多少？ -# 🟢 兑换报价 -100 USDT 在 SunSwap 上能兑换多少 TRX？ +> 我当前有哪些未平仓位？显示开仓均价、未实现盈亏和强平价。 -# ⚠️ 执行兑换 -在 SunSwap Nile 测试网上把 100 TRX 兑换成 USDT。 +**需要你确认才会执行：** -# ⚠️ 添加流动性 -在 SunSwap V2 的 TRX/USDT 池中添加 100 TRX 和 15 USDT 的流动性。 +> 以市价在 SunPerp 开 1 张 BTC-USDT 多单，10 倍杠杆，设置 5% 止损。 -# 🟢 查看 V3 仓位 -帮我查看我当前所有的 SunSwap V3 流动性仓位。 +> 平掉我所有的 BTC-USDT 仓位。 -# ⚠️ 收取手续费 -帮我收取 V3 仓位 #12345 的手续费奖励。 -``` +> 从 SunPerp 提现 10 USDT 到我的链上地址。 -### sunperp-skill +**实战场景：** -``` -# 🟢 查看行情 -BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ +> 被套牢了？ "帮我看看 BTC 现在的资金费率，建议做多还是做空？" -# 🟢 查看账户 -我的 SunPerp 账户余额和可用保证金是多少？ +> 想控制风险？ "帮我把 BTC-USDT 的杠杆降到 5 倍，止损调到 3%。" -# 🟢 查看持仓 -我当前有哪些未平仓位？显示开仓均价、未实现盈亏和强平价。 +> 想了解全局？ "帮我列出所有可交易的永续合约，按 24h 成交量排序。" -# ⚠️ 开仓 -以市价在 SunPerp 开 1 张 BTC-USDT 多单，10 倍杠杆，设置 5% 止损。 +--- -# ⚠️ 平仓 -平掉我所有的 BTC-USDT 仓位。 +## tronscan-skill — 链上数据侦探 {#tronscan-skill} -# ⚠️ 提现 -从 SunPerp 提现 10 USDT 到我的链上地址。 -``` +想查链上发生了什么？这个技能帮你查账户、交易、代币、区块和全网统计。**纯查询，绝对安全，不花一分钱，不需要任何密码。** 非常适合作为你的第一个技能来上手。 -### tronscan-skill +> 帮我查询地址 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf 的完整账户信息和持仓。 -``` -# 🟢 账户查询 -帮我查询地址 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf 的完整账户信息和持仓。 +> 查询这笔交易的详情：abc123... -# 🟢 交易查询 -查询这笔交易哈希的详情：abc123... +> 显示市值排名前 10 的 TRC20 代币。 -# 🟢 代币信息 -显示市值排名前 10 的 TRC20 代币。 +> 给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 -# 🟢 全网概览 -给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 +> 查询地址 TXX... 最近 20 笔 USDT 转账记录。 -# 🟢 转账记录 -查询地址 TXX... 最近 20 笔 USDT 转账记录。 -``` +**实战场景：** -### x402-payment +> 发现了一个新币，想看靠不靠谱？ "帮我查一下代币 TXX... 的持仓分布和合约验证状态。" -``` -# ⚠️ 调用付费端点 -使用 x402 协议调用这个付费智能体端点：https://api.example.com -``` +> 追踪鲸鱼动向？ "查一下地址 TXX... 最近 24 小时内超过 10 万 USDT 的所有交易。" -### recharge-skill +> 核实一笔转账？ "帮我查一下这笔交易到底成功了没有：abc123..." -``` -# 🟢 查询余额 -我的 BANK OF AI 账户还有多少余额？ +--- -# 🟢 查询订单 -显示我最近的 BANK OF AI 订单记录。 +## x402-payment — 链上"先付后用"自动结算 {#x402-payment} -# ⚠️ 充值 -给 BANK OF AI 充值 1 USDT。 +有些高级 API 和 AI 智能体是收费的——需要你先完成链上付费才能使用。这个技能通过 x402 协议帮你自动完成"先付费、再获取"的链上结算流程：AI 发现对方要收费，自动帮你完成链上支付，拿到结果后汇报给你。每次付款前同样会先问你确认。 -# ⚠️ 充值（英文） -Recharge 1 USDT to my BANK OF AI account. -``` +**需要你确认才会执行：** + +> 使用 x402 协议调用这个付费智能体端点：https://api.example.com （请替换为你实际要调用的付费端点地址） --- -## 推荐学习路径 +## recharge-skill — BANK OF AI 账户管理 {#recharge-skill} + +查余额、看订单、给 BANK OF AI 账户充值。 + +**绝对安全，只看不花钱：** + +> 我的 BANK OF AI 账户还有多少余额？ -如果你刚开始使用 BANK OF AI Skills，按这个顺序来会更顺畅： +> 显示我最近的 BANK OF AI 订单记录。 -第一步：只读查询 - → 先用 tronscan-skill 查账户、看交易，熟悉技能的交互方式 - → 用 sunswap 查价格和报价，不执行真实交易 +**需要你确认才会执行：** + +> 给 BANK OF AI 充值 1 USDT。 + +--- + +## 推荐学习路径 -第二步：测试网写操作 - → 在 Nile 测试网执行 swap、添加流动性、开合约 - → 确认 AI 的行为符合预期，确认参数传递正确 +**从这里开始——零风险，零配置：** 用 tronscan-skill 查账户、看交易，用 sunswap 查价格和报价。纯查询，不花钱，不需要密码。 -第三步：主网小额操作 - → 用少量资金验证完整流程 +**接下来——用假钱练手：** 配置好钱包（见 [Agent Wallet 快速开始](../../Agent-Wallet/QuickStart.md)），然后在 Nile 测试网上试试换币和流动性操作。确认 AI 的表现完全符合预期。 -第四步：主网正式使用 - → 日常操作，根据需要调整参数和技能组合 +**然后——主网小额试水：** 用少量真实资金跑一遍完整流程，确保没有意外。 +**最后——放心使用：** 日常操作，根据需要调整参数和技能组合。 --- ## 下一步 -- 想深入了解 Skill 的工作原理？ → [Skills 是什么？](./Intro.md) -- 遇到问题？ → [常见问题](./Faq.md) -- 使用 OpenClaw Extension 安装？ → [OpenClaw Extension 文档](../../Openclaw-extension/Intro.md) +- 想了解技能背后的工作原理？ → [什么是 Skills？](./Intro.md) +- 遇到问题了？ → [常见问题](./Faq.md) +- 在用 OpenClaw Extension？ → [OpenClaw Extension 文档](../../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index 3f094c6e..2874304a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -1,204 +1,188 @@ -# 常见问题与排查 +# 常见问题 -以下问题按你最可能遇到的顺序排列。 +问题按你最可能遇到的顺序排列——出了问题的排最前面，概念解释放最后。 --- -## 基础概念 +## 出了问题怎么办 -### Skill 和 MCP Server 有什么区别？ +### AI 说"找不到技能"，或者回答牛头不对马嘴 -这是最常见的问题。一句话解释：**MCP Server 是工具箱，Skill 是操作手册。** +直接告诉 AI 去哪里读取技能文件： -MCP Server 提供原子级工具——比如"查余额"、"发起转账"、"调用合约"。Skill 则告诉 AI 如何把这些工具组合起来完成一个完整任务——比如"在 DEX 上兑换代币"需要依次执行查余额、获取报价、检查授权、执行兑换四个步骤，Skill 负责定义这个流程。 +``` +请阅读 ~/.openclaw/skills/sunswap/SKILL.md，帮我查一下 TRX 当前的价格。 +``` -### Skill 需要单独安装吗？ +如果这样能正常工作，说明之前只是 AI 自动匹配没命中。下次在指令里加个提示词就行，比如"使用 sunswap 技能"。 -不需要额外安装应用程序。Skill 就是一个文件夹——你只需把它放在 AI 工具能读取的目录里，AI 就能自动发现和使用它。 +如果这样也不管用，按顺序排查： -但如果技能包含 `scripts/` 目录（sunswap、sunperp-skill、tronscan-skill 都有），需要在该目录下运行一次 `npm install` 安装脚本依赖。使用 OpenClaw Extension 安装时这步是自动的。 +1. 技能目录存在吗？在终端（黑框框）运行 `ls ~/.openclaw/skills`，看看有没有对应的文件夹。 +2. 依赖装了吗？进到技能目录运行 `npm install`（比如 `cd ~/.openclaw/skills/tronscan-skill && npm install`）。 +3. 密码配了吗？参考下方 [怎么配置密码和密钥？](#怎么配置密码和密钥)。 -### Skills 支持哪些 AI 工具？ +### 安装失败了 -目前支持：**OpenClaw**（最完整的集成体验）、**Claude Code**、**Cursor**，以及任何支持读取本地文件的 AI 助手（通过显式调用方式）。 +安装技能需要你的电脑上装有一个叫"Node.js"的基础运行环境（类似 Java 运行环境）。如果安装报错，大概率是缺了它或版本太低。 ---- +**最简单的解决办法：** 去 [Node.js 官网](https://nodejs.org/) 下载最新的 LTS 版本（就像安装普通软件一样，一路点"下一步"），装完后重新试一次。 -## 安装与配置 +:::tip 已经装了 Node.js 但还是报错？ +在终端运行 `node --version` 查看版本号。技能需要 **v20 或更高版本**。如果版本太低，去官网重新下载最新版覆盖安装即可。 +::: -### 怎么知道技能安装成功了？ +### 怎么确认技能安装成功了？ + +在终端运行： ```bash ls ~/.openclaw/skills ``` -应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 +能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录名就说明装好了。 -然后在 OpenClaw 中验证： +然后在 AI 对话中验证： ``` -阅读 sunswap 技能，告诉我这个技能能做什么。 +读一下 sunswap 技能，告诉我它能做什么。 ``` -如果 AI 能准确描述技能内容，说明安装成功。 - -### npm install 报错怎么办？ +AI 能准确描述功能 = 安装成功。 -先确认 Node.js 版本： +--- -```bash -node --version # 需要 >= 18 -``` +## 我的钱安全吗 -如果版本过低，用 nvm 升级： +### AI 会偷偷把我的钱转走吗？ -```bash -nvm install 18 -nvm use 18 -``` +**不会。** 所有涉及花钱的操作，AI 都会先暂停，把完整的"账单"摊开给你看——要花多少、转到哪里、走哪条链、预估手续费是多少。**你不亲口说"好"，它绝不动手。** -然后重新在技能目录执行 `npm install`。 +另外建议：用一个专门的钱包，只放你打算交易的资金。别把全部身家放进去——就像你不会带着所有积蓄去菜市场一样。 -### 凭证（私钥/API Key）怎么配置？ +### 私钥泄露了怎么办？ -通过环境变量配置。根据你使用的技能，在 `~/.zshrc` 或 `~/.bashrc` 中添加对应变量： +**先别慌，看看你用的是什么网络：** -```bash -# TRON 钱包（sunswap、sun-mcp-server、x402-payment 需要） -export TRON_PRIVATE_KEY="你的私钥" -export TRONGRID_API_KEY="你的 TronGrid API Key" +如果你一直在用 **Nile 测试网**（我们强烈推荐新手这样做），那恭喜你——测试网里的"钱"是免费的游戏币，丢了就丢了，重新申请一个钱包就行，零损失。 -# SunPerp 合约交易（sunperp-skill 需要） -export SUNPERP_ACCESS_KEY="你的 SunPerp Access Key" -export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" +如果是**主网**私钥泄露了，需要立即行动： -# TronScan 数据查询（tronscan-skill 需要） -export TRONSCAN_API_KEY="你的 TronScan API Key" +1. 停止使用当前 AI 工具。 +2. 创建一个新钱包。 +3. 把旧钱包里的所有资产转到新钱包。 +4. 更新你的配置，指向新的密钥。 +5. 去各个协议（SunSwap、SunPerp 等）撤销旧钱包的授权。 -# BANK OF AI（recharge-skill 需要） -export BANKOFAI_API_KEY="你的 BANK OF AI API Key" -``` +:::tip 预防胜于补救 +从一开始就使用 [Agent Wallet](../../Agent-Wallet/Intro.md) 替代明文私钥。Agent Wallet 把你的密钥锁在本地加密保险箱里——就算有人偷看到你的环境变量，没有加密密码也打不开保险箱。两把锁同时被破的概率极低。 +::: -添加后执行 `source ~/.zshrc` 生效，然后重启 AI 工具。 +### 为什么每笔交易 AI 都要问我确认？ ---- +这是故意设计的安全机制。AI 每次要花你的钱之前，都会把所有细节列出来让你检查：要做什么操作、涉及哪些代币和金额、走哪条链、预估要花多少手续费。 -## 使用问题 +**这是你在真金白银动之前的最后一道安全门。别跳过它。** -### AI 说"找不到技能"或行为不符合预期怎么办？ +### 怎么切换测试网和主网？ -首先换成**显式调用**——直接告诉 AI 技能文件在哪里： +直接告诉 AI： ``` -请阅读 ~/.openclaw/skills/sunswap/SKILL.md，帮我查 TRX 当前价格。 +在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 ``` -如果显式调用正常，说明是隐式触发的匹配问题。可以在任务描述中加入更明确的关键词，比如"使用 sunswap 技能"、"通过 tronscan-skill"。 +AI 会自动切换到测试网操作。**强烈建议每次新操作都先在测试网跑一遍**——测试网用的是免费游戏币，怎么折腾都不亏。 -如果显式调用也不工作，检查技能目录是否存在、npm install 是否完成、环境变量是否正确设置。 +### 报价和实际成交价为什么有差异？ -### 如何在测试网和主网之间切换？ +因为区块链不会在你看报价的时候暂停。从看到报价到点确认执行，可能过了几秒到几十秒，这段时间内价格可能发生变化。 -通过 `--network` 参数指定。**强烈建议每次新操作都先在测试网验证**： +AI 的应对策略是：先给你看报价，你确认后在实际提交前会重新获取最新价格，并用"滑点保护"确保你不会拿到一个差得离谱的价格。 -```bash -# 测试网（默认，推荐先用这个） -node scripts/swap.js TRX USDT 100 --network nile +如果市场剧烈波动导致交易失败，可以适当放宽容忍度："帮我兑换 100 TRX 为 USDT，滑点设 1%。" -# 主网（确认一切正常后再用） -node scripts/swap.js TRX USDT 100 --network mainnet --execute -``` +--- -也可以在对话中直接告诉 AI： +## 配置相关 -``` -在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 -``` +### 怎么配置密码和密钥？ -### 为什么 AI 在执行前要让我确认？ +**最简单、最安全的方法（强烈推荐）：使用 [Agent Wallet](../../Agent-Wallet/QuickStart.md)。** 它就像一个带密码的保险箱，有简单的可视化界面，按提示填入密钥即可。设置一次，以后再也不用跟复杂的代码打交道。 -这是设计如此的安全机制——所有写操作（涉及链上交易的操作）都必须经过用户明确确认才能执行。 +
+极客/老手备用方法：通过环境变量配置 -AI 会在确认提示中展示：操作类型、涉及的代币和金额、目标网络、预估 Gas 和滑点。这是为了让你在资金真正动用之前，有机会核查操作是否符合预期。**不要跳过这个步骤，更不要开启自动执行写操作。** +如果你熟悉命令行，可以将密码贴在系统的"隐形便签"（shell 配置文件）里。 -### dry-run（模拟执行）是什么意思？ +**苹果电脑：** -sunswap 等 Skill 的脚本支持不带 `--execute` 标志运行——这就是 dry-run 模式。它会模拟执行流程、检查余额和授权状态、获取报价，但不会广播任何链上交易。 +1. 打开终端（按 `Command + 空格`，搜索 `Terminal`） +2. 输入 `nano ~/.zshrc`，按回车——你会看到一个简陋的文本编辑器 +3. 用方向键移到最下面，把下面需要的内容粘贴进去（注意：每行两边的英文双引号 `"` 千万别删掉，也别替换成中文引号） +4. 按 `Ctrl + X`，再按 `Y`，再按回车——保存完毕 +5. 关掉终端，重新打开，然后重启你的 AI 工具 + +根据你需要的技能，把对应的内容粘贴进去： ```bash -# Dry-run：模拟检查，不执行 -node scripts/swap.js TRX USDT 100 +# SunSwap 换币（交易时需要） +export TRON_PRIVATE_KEY="你的私钥" +export TRONGRID_API_KEY="你的 TronGrid API Key" -# 真实执行 -node scripts/swap.js TRX USDT 100 --execute -``` +# SunPerp 永续合约 +export SUNPERP_ACCESS_KEY="你的 SunPerp Access Key" +export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" -遇到不确定的情况时，先跑 dry-run 是个好习惯。 +# TronScan 数据查询 +export TRONSCAN_API_KEY="你的 TronScan API Key" -### 为什么报价和实际成交有差异？ +# BANK OF AI 账户 +export BANKOFAI_API_KEY="你的 BANK OF AI API Key" +``` -因为从获取报价到实际执行之间有时间差，这段时间内价格可能发生变化。sunswap 的 `swap.js` 采用两步报价策略来处理这个问题：第一次报价展示给用户确认，用户确认后在实际提交交易前会重新获取最新报价，然后以最新报价计算的 `amountOutMin` 作为滑点保护。 +
-如果市场波动剧烈导致交易失败，适当增大滑点容忍度（`--slippage 1.0`）通常能解决。 +### 哪些 AI 工具能用这些技能？ ---- +目前支持：**OpenClaw**（最省心），以及任何能读取本地技能文件的 AI 助手。 -## 安全与进阶 +--- -### 我可以修改技能吗？ +## 自定义和管理 -可以。直接编辑 `SKILL.md` 或 `scripts/` 中的脚本，AI 下次调用时会读取最新版本。你可以修改操作步骤、添加自定义规则、调整安全参数，或者添加新的示例。 +### 我能修改技能的规则吗？ -修改 `sunperp-skill/resources/sunperp_config.json` 可以调整杠杆上限和止损默认值： +当然可以。技能就是你电脑上的普通文件夹，随便改。 -```json -{ - "safety": { - "max_leverage": 20, - "stop_loss": { - "required": true, - "default_percent": 5, - "max_percent": 25 - } - } -} -``` +比如你觉得 AI 做合约时 20 倍杠杆还是太高了，打开 `~/.openclaw/skills/sunperp-skill/resources/sunperp_config.json`，把数字改小就行——你的 AI，规矩由你定。 -### 技能的版本怎么管理？ +### 怎么卸载或更新？ -技能版本由 `SKILL.md` 的 YAML frontmatter 中的 `version` 字段标记。使用 OpenClaw Extension 时，可以通过 `GITHUB_BRANCH` 环境变量指定安装特定版本： +**卸载：** 删掉文件夹就行。 ```bash -GITHUB_BRANCH=v1.4.10 ./install.sh # 安装指定版本 -GITHUB_BRANCH=main ./install.sh # 使用最新主分支 +rm -rf ~/.openclaw/skills/sunswap ``` -默认使用 `v1.4.12` 标签版本。 +**更新：** 重新运行安装命令，会自动更新所有技能到最新版本。 -### 私钥泄露了怎么办？ +```bash +npx skills add https://github.com/BofAI/skills +``` -**立即行动，不要犹豫：** +--- -1. 停止使用当前 AI 工具 -2. 创建一个新的 TRON/EVM 钱包地址 -3. 将所有资产转移到新地址（注意检查当前账户是否有待处理交易） -4. 更新所有环境变量，指向新的私钥 -5. 撤销旧钱包在所有协议上的代币授权 -6. 查看旧钱包的交易记录，确认是否已有未授权的操作 +## 概念解释（给好奇的你） -Agent Wallet（加密存储）比明文私钥更安全——即使环境变量泄露，攻击者还需要额外的加密密钥才能访问资金。如果你管理较多资金，建议切换到 Agent Wallet 模式。 +### "技能"和"工具箱"到底什么关系？ -### 如何卸载或更新技能？ +一句话：**工具箱给 AI 干活的能力，技能教 AI 怎么干活。** -**卸载：** +工具箱（MCP Server）提供单个能力——比如"查余额"、"发转账"。技能（Skill）教 AI 怎么把这些能力串起来完成一个完整任务——比如"换币"需要先查余额、再看报价、确认价格、最后执行交易。技能定义了这个流程。 -```bash -rm -rf ~/.openclaw/skills/sunswap # 删除指定技能 -``` +打个比方：工具箱 = 菜刀、锅、灶台。技能 = 菜谱。 -**更新（重新安装最新版本）：** +### 装了一堆技能会不会变卡？ -```bash -cd openclaw-extension -./install.sh # 如果同名技能已存在，安装程序会询问是否覆盖 -``` +不会。AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个技能，照样飞快。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index 0b60ac1d..4c46a964 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -1,143 +1,120 @@ -# Skills 是什么？ +# 简介 -你可能已经在用 MCP Server 让 AI 助手查余额、发转账、调用合约了。但你会发现，有些任务并不是"调一次工具就完事"——比如在 DEX 上兑换代币，需要先查余额、再获取报价、然后授权、最后执行兑换，每一步都有判断和参数要处理。 +欢迎来到 BANK OF AI SKILLS！ -**Skills 就是为这类多步骤任务而生的。** +在过去，探索 Web3 是一件充满门槛的苦差事：盯盘、算滑点、切钱包、查合约……稍有不慎还会踩坑报错。现在，我们决定终结这种繁琐。 -一个 Skill 是一个"任务手册"——它不是工具，而是告诉 AI 怎样把一系列工具按正确的顺序、用正确的参数组合起来，完成一个完整的业务流程。 +简单来说，BANK OF AI SKILLS 是一套专为 TRON（波场）生态深度定制的**"AI 专属技能包"**。普通的 AI 面对复杂的 Web3 交易往往只会生搬硬套、漏洞百出，而我们的 Skills 给 AI 提供一套"标准化流程"——就像是给你配了一个自带 DEX 交易、合约查询、永续合约实战经验的私人交易员。你只需要像聊天一样发号施令，从前置排雷、参数计算到交易打包，这些极其容易出错的脏活累活，Skills 都会在底层自动为你完美编排。 --- -## Skill 和 MCP Server 的区别 +## 🌟 为什么你需要一套专业的 Skill（技能包）？ -很多人第一次接触 Skills 时会问：这和 MCP Server 有什么不一样？ +现在的普通 AI 都很聪明，如果你硬让它去写一段转账代码，或者给它接上接口去链上碰碰运气，它也能做到。但如果你真让它毫无防备地去操作你的真金白银，往往会变成一场灾难。 -| | MCP Server | Skill | -| :--- | :--- | :--- | -| **本质** | 工具服务 | 任务手册 + 脚本集合 | -| **作用** | 提供 AI **做事的原子能力** | 教 AI **如何把能力组合起来完成一件事** | -| **例子** | `mcp-server-tron` 提供 `send_trx` 工具 | `sunswap` 告诉 AI 如何用多个工具完成一次 DEX 兑换 | -| **类比** | 厨房里的刀、锅、炉子 | 菜谱 | - -简单说：**MCP Server 是工具箱，Skill 是操作手册。** Skill 告诉 AI 打开哪个抽屉、拿哪把工具、按什么步骤完成任务。 +在 Web3 真实的高风险交易中，AI 需要的不仅仅是"聪明能干"，而是必须"懂行"且"绝对靠谱"。BANK OF AI SKILLS 的核心竞争力，就在于把一个只会生搬硬套的普通 AI，升级成了一个自带防错机制、精通业务流程、且严格守住风控底线的"Web3 专属私人助理"。 ---- +有了 Skills，你的 AI 将拥有以下断层优势： -## 一个 Skill 长什么样？ +| 真实交易痛点 | ❌ 普通的 AI 聊天机器人 | 🦸‍♂️ 搭载 BANK OF AI SKILLS（专属助理） | +| :--- | :--- | :--- | +| **执行复杂交易**（防错与 SOP） | 靠猜行事，容易卡壳。它能执行单步指令，但遇到复杂的换币，它往往不知道前提是要先授权（Approve），导致盲目操作、报错卡死。 | 自带"老司机导航"。强制执行完美步骤：查余额 → 检查授权 → 报价 → 确认 → 交易，一步都不乱。 | +| **资金安全与风控**（防爆仓） | 盲目听话，没有底线。它不懂金融常识，你如果随口说"开 100 倍杠杆"，它真敢毫无顾忌地帮你生成危险指令。 | 内置"业务级安全锁"。底层锁死风控红线（如：最高 20 倍杠杆、强制带止损），直接拦截危险操作。 | -Skill 是一个文件夹，结构非常简单： +**一句话总结：** 普通的 AI 只是一个理论满分的"高材生"，一上实操就容易漏洞百出；而搭载了 BANK OF AI SKILLS 的 AI，就像是给你配了一个自带 DEX 交易、合约查询、永续合约技能的实战老手——绝不犯低级错误、还会主动帮你避坑。你只管用大白话点菜，剩下的它全包。 -| 文件/目录 | 作用 | 是否必须 | -| :--- | :--- | :--- | -| `SKILL.md` | 核心指令文档——AI 从这里学会如何执行任务 | **必须** | -| `scripts/` | 可执行脚本——AI 调用这些脚本完成具体操作 | 可选 | -| `resources/` | 参考数据——合约地址、代币列表、配置文件等 | 可选 | -| `package.json` | npm 依赖声明（有 scripts 的 Skill 需要先安装） | 可选 | +### 🎬 真实场景还原：当你想"花 50 U 买点 TRX" -`SKILL.md` 的顶部是一段 YAML Frontmatter，声明技能的基本信息： +假设你现在对 AI 下达了一句最简单的指令："帮我用 50 USDT 买点 TRX。" -```yaml ---- -name: SunSwap DEX Trading -description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. -version: 2.0.0 -dependencies: - - node >= 18.0.0 - - tronweb -tags: - - defi - - dex - - swap - - tron ---- +**❌ 如果是普通的 AI：** -# SunSwap DEX Trading Skill +它听到指令，可能直接给你生成一段漏洞百出的代码，或者盲目去链上碰运气。结果往往是**"砰"的一声，交易失败**。然后给你弹出一长串看不懂的英文报错（比如 `transfer amount exceeds allowance`）。 -## 🚀 Quick Start -...（具体操作指令） -``` +为什么？因为在 Web3 的世界里，花 USDT 之前必须先进行**"授权（Approve）"**。普通的 AI 空有智商却没有"行业常识"，漏掉前置步骤直接宕机，留下你一脸懵。 -`name` 和 `description` 是 AI 识别和匹配技能的关键字段——写得越准确，AI 越容易在合适的时机自动找到它。正文则是具体的操作指令，没有格式限制，可以是文字说明、代码示例、参数表格，或者任何有助于 AI 理解的内容。 +**✅ 如果是搭载了 BANK OF AI SKILLS 的专属 AI：** ---- +它接到指令后，不仅会执行，还会自动在后台跑一遍"标准作业流程"。你的体验会是这样的： -## 为什么不把所有指令直接给 AI？ +1. **自动查账：** "老板，看过了，您的钱包里有 100 USDT，余额充足。" +2. **前置排雷：** "发现您还没对 SunSwap 授权过 USDT，我已经帮您把授权（Approve）申请准备好了，请先确认。" +3. **精准报价：** "授权成功！按最新价格，50 USDT 约可兑换 350 TRX，我已经自动帮您设置好 1% 的防夹滑点。是否现在买入？" -理解 Skills 设计的关键问题：如果只是告诉 AI 怎么操作，直接在对话里说不就行了？ +在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"查余额 → 发现缺授权 → 补授权 → 算滑点 → 拉报价"这整整 5 个高门槛步骤。这就是**"普通聊天 AI"和"专业 Web3 管家"**之间最直观的降维打击。 -这样做有两个根本问题： +--- -**上下文窗口有限且昂贵。** 如果把所有 Skill 的完整内容都塞进每次对话，光是这些指令就会占据大量 token，让 AI 反应变慢，也让每次对话的成本大幅增加。 +## 🛡️ 使用 Skills 交易，你的资产绝对安全 -**注意力分散。** 当 AI 面对几十个 Skill 的详细说明时，它很难专注于当前任务，容易混淆不同技能的规则和参数，产生错误。 +**"Skills 会越权动用我的资金吗？"** +不会。所有涉及花钱的操作都内置了**拦截确认机制**——AI 会先暂停，把完整的"账单"摊开给你看（要花多少、转到哪里、走哪条链、预估手续费），**你不亲口说"好"，它绝不动手**。就像一个尽职的助理，每笔报销单都要你签字才能走流程。 -Skills 的解法是**三层渐进式加载**——只在需要的时候才加载需要的内容。 +**"装了一堆 Skills，系统响应会不会变慢？"** +不会。Skills 采用**按需唤醒的轻量级架构**——AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个 Skills，照样飞快。 --- -## 三层渐进式加载 - -把 Skills 想象成图书馆的检索系统： +## 目前 Skills 能帮你干什么？ -**第一层：书架索引（极轻量）** +五大核心技能，覆盖 TRON 生态最常用的场景。每个技能都配了一句"参考话术"——复制到 AI 对话框里回车就能体验。 -AI 启动时，系统只向它暴露所有 Skill 的 `name` 和 `description`——就像书架上的标签。这些"索引卡片"非常小，即使同时加载几百个 Skill 也不会造成负担。AI 通过这一层决定"这次任务需要用到哪个技能"。 +### 💱 执行 DEX 交易 -**第二层：操作手册（按需加载）** +查价格、比报价、甚至一键换币。 -当 AI 确认需要某个 Skill，才去读取对应的 `SKILL.md` 完整内容。这一步只在匹配到技能时触发，为 AI 提供具体的执行步骤、参数要求、边界条件和常见错误处理。 +> 🗣️ "帮我算算现在 100 USDT 在 SunSwap 上能换多少 TRX？" -**第三层：工具执行（实时调用）** +💡 如需了解更多进阶玩法，请查看：[**sunswap**（DEX 交易向导）](./BANKOFAISkill.md#sunswap) -当任务执行到需要具体操作的环节（比如查询链上余额、执行兑换交易），AI 才调用对应的脚本或 MCP 工具，完成实质性工作，然后把结果返回给对话。 +### 📈 进行永续合约交易 -这种设计让系统在管理大量 Skill 的同时，保持低延迟和高准确性。 +在 SunPerp 看行情、开平仓。内置安全锁，最高只允许 20 倍杠杆，且开仓强制设止损——帮你管住手，防爆仓。 ---- +> 🗣️ "现在 BTC 资金费率是多少？帮我开一张 5 倍杠杆的多单，亏损 5% 自动止损。" -## AI 如何找到并使用一个 Skill？ +💡 如需了解更多参数设置，请查看：[**sunperp-skill**（永续合约安全员）](./BANKOFAISkill.md#sunperp-skill) -AI 选择并执行一个 Skill 经历四个步骤： +### 🕵️ 查询链上数据 -**步骤 1：意图识别** +查账户、查交易、查新币靠不靠谱。纯查询，绝对安全，不花一分钱。 -你发出一条请求（比如"帮我在 SunSwap 上把 100 USDT 兑换成 TRX"），AI 解析意图，扫描所有已挂载 Skill 的描述，找到最匹配的那个。 +> 🗣️ "帮我查一下昨天那个土狗币现在的持仓分布，有没有被庄家控盘？" -**步骤 2：规则内化** +💡 如需了解更多查询维度，请查看：[**tronscan-skill**（链上数据侦探）](./BANKOFAISkill.md#tronscan-skill) -AI 读取该 Skill 的 `SKILL.md`，理解执行步骤、参数格式、网络选择、安全限制等具体规则。 +### ☕ 自动结算链上付费服务 -**步骤 3：工具执行** +当 AI 需要调用付费的链上服务或数据接口时，会通过 x402 协议自动完成"先付费、再获取"的链上结算，无需你手动扫码或切换钱包。 -按照手册的指引，AI 逐步执行——调用脚本查余额、获取报价、检查授权、执行兑换——在关键节点等待你的确认。 +> 🗣️ "使用 x402 协议调用这个付费智能体端点：https://api.example.com"（请替换为你实际要调用的付费端点地址） -**步骤 4：结果反馈** +💡 如需了解支付与授权细节，请查看：[**x402-payment**（链上自动结算）](./BANKOFAISkill.md#x402-payment) -任务完成后，AI 将结果整理成易读的格式汇报给你。遇到缺少信息或执行异常时，主动询问。 +### 🏦 管理 BANK OF AI 账户 ---- +查看你的 BANK OF AI 余额，一句话完成充值。 -## 两种调用方式 +> 🗣️ "帮我看看我的账户还有多少余额，顺便再充 5 个 U 进去。" -你可以通过两种方式触发 Skill： +💡 如需了解充值与提现规则，请查看：[**recharge-skill**（账户大管家）](./BANKOFAISkill.md#recharge-skill) -**显式调用** — 直接告诉 AI 要读哪个 Skill，适合需要确定性行为的场景： +--- -``` -阅读 sunswap 技能，帮我查 100 USDT 在 SunSwap 上能兑换多少 TRX。 -``` +## 🎯 这套 Skills 适合我吗？ -**隐式触发** — 描述任务，让 AI 自动匹配，适合日常对话： +- **👶 我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么算滑点和 Gas 费了。直接用大白话提要求，AI 把处理好的结果直接喂给你。 +- **🕴️ 我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下大把精力。你只需专注策略，把枯燥的执行全扔给 AI。 +- **🍉 我只是想吃瓜玩玩：** 完全没问题！"链上数据侦探"等纯读取技能 100% 免费，不用连钱包也能畅通无阻，零风险体验 Web3 魔法。 -``` -帮我查一下现在 100 USDT 在 SunSwap 能换多少 TRX。 -``` +--- -两种方式的区别在于控制权：显式调用确保 AI 使用你指定的 Skill；隐式触发更自然，但如果描述不够清晰，AI 可能匹配到错误的 Skill。遇到执行不符合预期时，换成显式调用通常能解决问题。 +
---- +**准备好了吗？只需 2 步，不到 1 分钟。** -## 下一步 + +前往快速开始 + -- 想了解 BANK OF AI 提供了哪些现成的 Skill？ → [BANK OF AI Skills](./BANKOFAISkill.md) -- 有疑问？ → [常见问题](./Faq.md) +
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md new file mode 100644 index 00000000..1f4f769b --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -0,0 +1,213 @@ +# 快速开始 + +只需 **2 步**，不到 **1 分钟**，你的 AI 就能开始帮你查链上数据、看行情报价。不需要密码，不需要配置任何东西——装完就能用。 + +--- + +## 第 1 步：安装技能库 + +### 一键自动安装 + +只需告诉你的 AI Agent 执行以下命令： + +```bash +npx skills add https://github.com/BofAI/skills -y -g +``` + +`-y` 参数会跳过所有交互选择，默认安装所有 Skills；`-g` 参数表示全局安装（所有项目都可使用）。安装完成后会显示 ✅ 全局安装完成！以及安装的所有 Skills 列表。 + +### 交互式安装 + +如果你想手动选择安装哪些 Skills 以及安装范围，去掉 `-y -g` 参数即可： + +```bash +npx skills add https://github.com/BofAI/skills +``` + +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。 +::: + +#### 安装过程详解 + +安装器会引导你完成以下几步，照着做就行： + +**1️⃣ 确认安装工具** + +终端会提示你需要安装 `skills` 工具包，输入 `y` 并回车即可： + +``` +Need to install the following packages: + skills@1.4.6 +Ok to proceed? (y) y +``` + +**2️⃣ 选择要安装的 Skills** + +安装器会自动从仓库拉取所有可用的 Skills，然后列出清单让你勾选。按**空格键**切换选中/取消，默认全选即可： + +``` +◇ Found 6 skills +│ +◇ Select skills to install (space to toggle) +│ Multi-Sig & Account Permissions, recharge-skill, +│ SunPerp Perpetual Futures Trading, SunSwap DEX Trading, +│ TronScan Data Lookup, x402-payment +``` + +:::tip 建议全选 +除非你很明确只需要某几个技能，否则建议全部安装。Skills 采用按需唤醒架构，不用的技能不会占用任何资源。 +::: + +**3️⃣ 选择要安装到哪些 AI 工具** + +安装器会自动检测你电脑上装了哪些 AI 工具（如 Cursor、Claude Code、Cline 等），用空格键勾选你要用的： + +``` +◇ 43 agents +◇ Which agents do you want to install to? +│ Amp, Antigravity, Cline, Codex, Cursor, Deep Agents, +│ Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp +``` + +**4️⃣ 选择安装范围** + +选择 `Project`（当前项目）或 `User`（所有项目全局可用），按需选择即可： + +``` +◇ Installation scope +│ Project +``` + +**5️⃣ 查看安全评估 & 确认安装** + +安装器会对每个 Skill 进行安全风险扫描，并展示评估结果。确认无误后选择 `Yes` 开始安装： + +``` +◇ Security Risk Assessments ──────────────────────────────╮ +│ │ +│ Gen Socket Snyk │ +│ Multi-Sig & Account Permissions -- -- -- │ +│ recharge-skill -- -- -- │ +│ SunPerp Perpetual Futures Trading -- -- -- │ +│ SunSwap DEX Trading -- -- -- │ +│ TronScan Data Lookup -- -- -- │ +│ x402-payment Med 1 alert Med │ +│ │ +├──────────────────────────────────────────────────────────╯ + +◇ Proceed with installation? +│ Yes +``` + +**6️⃣ 安装完成！** + +看到类似以下输出，说明所有 Skills 已经成功安装到你选择的 AI 工具中： + +``` +◇ Installed 6 skills ────────────────────────╮ +│ │ +│ ✓ Multi-Sig & Account Permissions (copied) │ +│ ✓ recharge-skill (copied) │ +│ ✓ SunPerp Perpetual Futures Trading (copied)│ +│ ✓ SunSwap DEX Trading (copied) │ +│ ✓ TronScan Data Lookup (copied) │ +│ ✓ x402-payment (copied) │ +│ │ +├─────────────────────────────────────────────╯ + +└ Done! +``` + +:::tip 可选：安装 find-skills +安装完成后，工具可能会提示你是否安装 `find-skills`——这是一个帮 AI 自动发现和推荐新技能的辅助工具，建议选 `Yes`。 +::: + +### 验证安装 + +打开你的 AI 对话框，输入： + +``` +读一下 sunswap 技能，告诉我它能做什么。 +``` + +AI 能准确描述功能——恭喜，安装成功！ + +--- + +## 第 2 步：对 AI 说出你的第一句话 + +打开你的 AI 对话框，把下面这句话复制进去，回车： + +> 给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 + +几秒后，AI 会自动调用 tronscan-skill，为你呈现一份完整的链上数据报告。 + +**这个操作绝对安全——它只是帮你"看"数据，不碰你的钱包，不花一分钱。** + +再试几句： + +> 100 USDT 在 SunSwap 上能换多少 TRX？ + +> 显示市值排名前 10 的 TRC20 代币。 + +> BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ + +如果 AI 返回了真实数据——恭喜，你的 AI 已经"开窍"了！ + +--- + +## 💰 想让 AI 帮你交易？ + +上面所有的操作都是"只看不动"的——AI 能帮你查数据、比价格，但它现在还没有权限动你的一分钱。这是故意的：控制权始终在你手里。 + +当你准备好让 AI 帮你换币、开仓、管理流动性时，你需要给它配一把"钱包钥匙"。 + +我们为你准备了两种给钥匙的方法，任选其一即可： + +### 方案一：给 AI 开个专用"支付宝"（强烈推荐，最安全） + +我们推荐使用 **Agent Wallet**。你可以把它理解成给 AI 开了一个专属的支付账户。你不需要把银行卡密码（明文私钥）直接暴露在电脑文件里，而是给它设置一个支付密码。每次花钱前，它都会把账单摊开给你看，你说"好"它才会操作。 + +👉 前往 [Agent Wallet 快速开始](../../Agent-Wallet/QuickStart.md) 设置（有可视化界面，大约 2 分钟搞定）。 + +### 方案二：直接把私钥贴给 AI（适合老手或快速测试） + +如果你嫌麻烦，不想装新工具，只想马上体验交易，你也可以像改普通记事本一样，直接把你的私钥贴在电脑的"隐形便签"里： + +1. 在终端（黑框框）输入 `open -e ~/.zshrc` 并按回车。 +2. 电脑会弹出一个记事本窗口。滑到最底下，新起一行，把你的波场私钥粘贴进去： + ```bash + export TRON_PRIVATE_KEY='你的真实或测试网私钥' + ``` + ⚠️ 注意：两边的英文双引号千万别漏掉！ +3. 按 `Command + S` 保存，关掉记事本。 + +:::danger 极其重要的一步 +无论你用哪种方案配好了钥匙，都必须**彻底关闭并重新打开你的 AI 软件**，它才能拿到这把新钥匙！ +::: + +--- + +## 🎮 钥匙配好了，怎么让它去交易？ + +配好钥匙并重启 AI 后，你就可以直接对它下达交易指令了！ + +:::caution 新手铁律：先用假钱练手 +在执行任何真实交易之前，**务必先在 Nile 测试网上跑一遍**。测试网用的是没有真实价值的"游戏币"，怎么折腾都不会亏钱。 +::: + +打开对话框，对 AI 喊出你的第一句交易指令： + +> 在 Nile 测试网上，帮我把 100 TRX 兑换成 USDT。 + +此时，AI 会迅速帮你计算价格、预估手续费，然后停下来问你："确定要执行吗？" 你只需要回复"确定"，这笔链上交易就自动完成了！ + +等你在测试网上玩熟了，确认 AI 的表现完全符合预期，以后只要把指令里的"测试网"三个字去掉，它就会帮你操作主网的真金白银了。 + +--- + +## 下一步 + +- 看看每个技能都能帮你干什么 → [技能大全](./BANKOFAISkill.md) +- 遇到问题了？ → [常见问题](./Faq.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md index 0eb63d56..d0646bcc 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md @@ -1,221 +1,93 @@ -# 常见问题与排查 +# 常见问题 -遇到问题时，先来这里找找答案。按照你最可能遇到的顺序组织：安装问题、连接问题、凭证问题、运行时问题，最后是一些通用问题。 +遇到报错别慌，通常都是一些小设置没配好。我们按最容易碰到的问题排了个序： --- -## 安装问题 +## 安装时报错了 -### 安装程序报错"command not found: node" +### 报错里写着 "command not found: node" 或 "npm install 失败" -安装程序需要 Node.js v18.0.0 或更高版本。检查是否已安装： +**人话翻译**：你的电脑上没装 Node.js，或者版本太老了。 -```bash -node --version -``` +**怎么解决**：去 [Node.js 官网](https://nodejs.org/) 下载最新的稳定版（LTS，建议 v20 或更高版本），像装普通软件一样一路点"下一步"装好。然后关掉终端里的黑框框，重新运行一次安装口令。 -如果未安装或版本太低，请到 [nodejs.org](https://nodejs.org/) 下载安装最新 LTS 版本。安装 Node.js 后，`npx` 命令会同时可用。 +### 报错里写着 "command not found: python3" -### 安装程序报错"command not found: python3" +**人话翻译**：你的电脑缺少一个叫 Python 的基础运行环境。 -安装程序使用 Python 处理 JSON 配置文件。macOS 通常自带 Python 3，Linux 可以通过包管理器安装： +**怎么解决**：去 [Python 官网](https://www.python.org/downloads/) 下载安装。 -```bash -# Ubuntu/Debian -sudo apt install python3 +### AgentWallet（AI 保险柜）安装失败了 -# macOS (通过 Homebrew) -brew install python3 -``` +**怎么解决**： -### 安装程序警告"OpenClaw not found" - -安装程序检测到 `~/.openclaw` 目录不存在。这意味着 OpenClaw 可能未安装，或者安装在了非标准路径。 - -安装程序会询问你是否继续——你可以选择继续安装（MCP Server 和 Skills 仍然会被配置），但 OpenClaw 启动后可能无法自动加载它们。建议先到 [OpenClaw 官方仓库](https://github.com/openclaw) 完成安装。 - -### Skills 克隆失败 - -如果 `git clone` 失败，常见原因包括： - -- **网络问题**：检查是否能访问 GitHub。可以尝试 `git clone https://github.com/BofAI/skills.git` 手动测试。 -- **Git 未安装**：运行 `git --version` 确认。 -- **指定的分支/标签不存在**：如果你设置了 `GITHUB_BRANCH` 环境变量，确认对应的分支或标签确实存在。 - -Skills 克隆失败不会中断整个安装——MCP Server 的配置仍然完好。你可以之后手动安装 Skills。 - -### npm install 失败 - -安装 Skills 时，部分 Skill（如 sunswap、x402-payment）需要运行 `npm install` 安装依赖。如果失败： - -- 检查网络连接（npm 需要访问 registry.npmjs.org） -- 确认 Node.js 版本 >= 18 -- 尝试手动运行： - ```bash - cd ~/.openclaw/skills/sunswap # 或其他 Skill 目录 - npm install - ``` - -npm install 失败不会中断安装程序——它会发出警告但继续。该 Skill 的部分功能可能受限，直到依赖安装成功。 +1. 再次确认你的 Node.js 版本是否足够新。 +2. 有时候纯粹是网络太卡下载超时了，喝口水等两分钟重新运行一次安装代码即可。 +3. 如果一直卡住，可以试着手动把旧的 `~/.agent-wallet` 文件夹删掉，从头再来。 --- -## 连接问题 - -### OpenClaw 启动后看不到区块链工具 +## 安装完了，但 AI 像个傻子 -**最常见的原因**：没有重启 OpenClaw。修改 mcporter.json 后，必须完全退出并重新启动 OpenClaw。 +### AI 委屈地说："我没有查区块链的工具" 或 "我不知道什么是 SunSwap" -如果重启后仍然看不到： +**最可能的原因**：你装完之后太心急，**没有重启 OpenClaw 软件**。 -1. **检查 mcporter.json 格式**： - ```bash - python3 -m json.tool ~/.mcporter/mcporter.json - ``` - 如果报 JSON 语法错误，修复格式问题后重启。 +**怎么解决**：把 OpenClaw 彻底退出（苹果电脑按 `Command+Q`），重新打开，让 AI 重新读取一下它的新脑子。 -2. **检查 mcporter.json 内容**：确认 `mcpServers` 下有你安装的 Server 条目。 +### AI 能查到数据，但回答乱七八糟、经常出错？ -3. **手动测试 MCP Server**： - ```bash - npx -y @bankofai/mcp-server-tron - ``` - 如果这条命令能正常启动（显示日志输出），说明 MCP Server 本身没问题，问题在 OpenClaw 的配置读取。 +**最可能的原因**：你用的 AI 底层模型版本太低了。就好比你让一个小学生去做高中数学题，它不是不努力，是真的能力不够。 -### 只有查询工具可用，没有转账等写入工具 +**怎么解决**：打开 OpenClaw 的设置，把模型升级到更强的版本。模型越强，AI 理解你的指令就越准确，调用工具也越不容易出错。 -这是设计如此。写入工具只在配置了钱包凭证后才会出现。检查以下之一是否已配置： +### 凭什么别人能转账，我的 AI 只能查数据？ -- 环境变量 `TRON_PRIVATE_KEY`（mcp-server-tron） -- 环境变量 `PRIVATE_KEY`（bnbchain-mcp） -- mcporter.json 中对应 Server 的 `env.TRON_PRIVATE_KEY` 或 `env.PRIVATE_KEY` +**原因**：你现在的 AI 是极度安全的"只读模式"。因为你在安装时跳过了 AgentWallet 配置，没有给它留钱包钥匙。 -配置凭证后重启 OpenClaw。详细说明请参阅 [配置参考](./Configuration.md)。 - -### MCP Server 启动超时 - -如果 OpenClaw 在启动 MCP Server 时超时，可能是 npx 下载包太慢。首次运行时需要从 npm 下载包，可能需要几十秒。 - -可以提前手动下载来加速： - -```bash -npx -y @bankofai/mcp-server-tron --help -npx -y @bnb-chain/mcp@latest --help -``` - -下载完成后，后续启动会使用缓存，速度会快很多。 +**怎么解决**：重新跑一次安装脚本，在 AgentWallet 设置那一关跟着提示认真把钱包配好。配好并重启后，转账和交易功能就会被激活。 --- -## 凭证问题 - -### "私钥无效"错误 - -**TRON 私钥**应为 64 个字符的十六进制字符串，可以带或不带 `0x` 前缀。 - -**EVM 私钥**应带 `0x` 前缀。安装程序会自动为不带前缀的私钥添加 `0x`，但如果你手动编辑配置文件，请确保格式正确。 - -常见错误： -- 多余的空格、换行或引号嵌套 -- 从其他地方复制时带入了不可见字符 - -验证方法：将私钥导入对应的钱包（TronLink 或 MetaMask）确认有效。 +## 密码和安全焦虑 -### TronGrid API Key 不生效 +### 私钥填错了或者报错说 "私钥无效" -1. **变量名是否正确**：必须是 `TRONGRID_API_KEY`（不是 `TRON_API_KEY`） -2. **Key 是否仍然有效**：登录 [trongrid.io](https://www.trongrid.io/) 确认状态 -3. **是否正确加载**：如果在环境变量中设置，确认已运行 `source ~/.zshrc` +**原因**：现在的安装包用 AgentWallet 管理钱包，一般不需要你手动填私钥了。但如果你使用了币安链工具箱 (bnbchain-mcp)，手动配私钥时可能不小心多复制了一个空格或回车。 +**怎么解决**：重新仔细复制一遍。EVM（币安/以太坊）私钥要带 `0x` 开头，如果你是手动改文件，千万注意别漏了。 -### BANK OF AI API Key 无效 +### AI 报错 "请求限速" 或 "429 错误" -检查 `~/.bankofai/config.json` 或 `~/.mcporter/bankofai-config.json` 的内容： +**人话翻译**：你让 AI 查数据的速度太快了，免费的网络通道觉得你像个机器人，把你拉黑了一小会儿。 -```bash -cat ~/.bankofai/config.json -``` +**怎么解决**： -确认 `api_key` 字段包含有效的 Key。注意 recharge-skill 的凭证读取有优先级顺序（CLI 参数 > 环境变量 > 工作目录 `bankofai-config.json` > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`），如果你在多个地方设置了不同的值，可能会读到意外的那个。 +1. **治标**：歇几分钟再问。 +2. **治本**：去 [TronGrid](https://www.trongrid.io/) 免费申请一个专属的 API Key。安装时把这个 Key 填进去，AI 就能跑 VIP 高速通道了。 --- -## 运行时问题 - -### 请求限速（429 错误） - -主网的公共 RPC 有严格的频率限制。解决方法： - -- **配置 TronGrid API Key**：免费申请后设置 `TRONGRID_API_KEY`，显著提升限额 -- **使用测试网**：Nile 和 Shasta 测试网受限更少 -- **减少并发查询**：在提示词中避免让 AI 同时执行大量查询 - -### Skill 执行失败 - -如果某个 Skill 报错，按以下顺序排查： - -1. **检查依赖是否安装**： - ```bash - cd ~/.openclaw/skills/ - npm install # 如果有 package.json - ``` - - -2. **检查 Node.js 版本**：部分 Skill 需要 >= 18.0.0。 - -### 交易失败 - -链上交易失败的常见原因： - -- **余额不足**：TRX 余额不够支付 Gas 费（带宽/能量） -- **能量不足**：智能合约调用（包括 TRC20 转账）需要消耗能量 -- **账户未激活**：新的 TRON 地址需要先收到一笔 TRX 才能激活 -- **授权额度不足**：TRC20 代币转账前可能需要先 approve - -使用 mcp-server-tron 的 `get_transaction_info` 工具查看交易失败的具体原因。 - ---- - -## 通用问题 - -### 能否只安装部分组件？ - -可以。安装程序在每个阶段都允许你选择性安装。比如你可以只安装 mcp-server-tron 而不装其他 MCP Server，或者只安装 sunswap Skill 而跳过其他 Skill。 - -### 能否多次运行安装程序？ - -可以。安装程序对 mcporter.json 采用深度合并策略，不会覆盖已有配置。对于 Skills，如果目标位置已存在同名 Skill，会提示你是否覆盖。 - -### 如何完全卸载？ +## 随心所欲地折腾（卸载与重装） -OpenClaw Extension 没有自动卸载程序。手动卸载步骤： +### 我能不能只装某一个技能，不装别的？ -1. **删除 MCP Server 配置**：编辑 `~/.mcporter/mcporter.json`，移除对应的 Server 条目 -2. **删除 Skills**：删除安装目录下的 Skill 文件夹（默认 `~/.openclaw/skills/`） -3. **删除凭证文件**： - ```bash - rm -f ~/.x402-config.json - rm -f ~/.bankofai/config.json - rm -f ~/.mcporter/bankofai-config.json - rm -f ~/.clawdbot/wallets/.deployer_pk - ``` -4. **清理环境变量**：从 `~/.zshrc` 或 `~/.bashrc` 中移除相关 export 语句 +完全可以！安装向导走到第 4 关时，会列出所有技能。你用空格键只勾选你想要的，别的空着，按回车确认就行。 -### 支持哪些操作系统？ +### 玩腻了，怎么卸载它们？ -安装程序是 Bash 脚本，支持： -- **macOS**（Intel 和 Apple Silicon） -- **Linux**（Ubuntu、Debian、CentOS 等） -- **Windows**：需要通过 WSL（Windows Subsystem for Linux）运行 +最简单粗暴的方法：打开电脑的文件夹，找到 `~/.openclaw/skills/` 目录，把你不想用的技能文件夹直接删掉，然后重启 AI 软件，它就彻底消失了。 -### 和 TRON MCP Server 的官方云服务有什么区别？ +### 我瞎填了一通装坏了，能重新装吗？ -[官方云服务](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md)是远程托管的只读 MCP Server，不需要本地安装。OpenClaw Extension 则在你本地运行 MCP Server，配合私钥可以解锁完整的读写能力。 +随便装！不用怕搞坏电脑。 -如果你只需要查询链上数据，云服务更简单。如果你需要转账、合约写入等操作，或者需要使用 Skills（如 SunSwap 交易），就需要 OpenClaw Extension。 +- **选 1（普通安装）**：重新跑一次脚本，它会自动修补你缺的东西。 +- **选 2（全新安装 - Clean install）**：如果你想彻底从头来过，选这个。它会把你旧的工具箱、技能、配置全部格式化清空，给你一个干干净净的新环境。为了防止你误触，它还会要求你手动输入 `CLEAN` 这几个字母来确认。 --- -## 下一步 +## 还是搞不定？ -- 从头开始 → [快速开始](./QuickStart.md) +👉 回到 **[快速开始](./QuickStart.md)** 从第一步跟着再走一遍，通常 99% 的问题都能迎刃而解。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index cec7b4e9..3ae6f759 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -1,62 +1,60 @@ # 简介 -## OpenClaw Extension 是什么？ +一键让你的 AI 懂区块链。 -OpenClaw Extension 是由 **BANK OF AI** 开发的一套扩展工具包，为 [OpenClaw](https://github.com/openclaw)（开源 AI 助手）赋予**区块链交互能力**。安装后，你的 AI 助手就能直接操作链上资产——查余额、发起转账、调用智能合约、在 DEX 上兑换代币——而这一切只需要用自然语言对话完成。 +你有没有想过，有一天查链上数据、换币、看余额，再也不用打开十几个网页，也不用盯着复杂的各种 App？ -传统方式下，让 AI 操作区块链需要自己搭建 MCP Server、手动管理配置文件、逐个安装各种工具。OpenClaw Extension 把这些工作打包成了一个交互式安装程序——运行一条命令，按提示选择你需要的组件，几分钟内就能让 AI 助手具备多链操作能力。 +你只需要像跟朋友微信聊天一样，发一句大白话，剩下的脏活累活，全由你的 AI 助理搞定。 + +**OpenClaw Extension，就是帮你实现这个魔法的"一键安装包"。** --- -## 核心愿景 +## 它是怎么施展魔法的？ -OpenClaw Extension 的目标是为 AI 代理经济构建一套金融基础设施——让每个 AI 代理都具备独立的金融能力： +以前的 AI 只是个懂理论的"嘴强王者"。为了让它能帮你干实事，我们的安装包会给它装上两样核心武器： -- **赚取收益**：通过 x402 协议等标准接口接受任务和服务的付款 -- **自主消费**：独立支付计算、数据、存储等资源费用 -- **代理互联**：促进代理之间（A2A）的直接金融活动和结算 -- **DeFi 交互**：无缝地与去中心化金融协议和智能合约交互 +### 🛠️ 1. 工具箱 (MCP Server) —— 给 AI 装上"手" ---- +这就是 AI 接入区块链的网线。装上它，AI 就拥有了直接读写区块链的能力。 -## 它包含什么？ +目前我们支持： -OpenClaw Extension 由两大类组件构成：**MCP Server** 和 **Skills**。你可以在安装时按需选择要启用哪些组件。 +- **波场 (TRON) 工具箱**：能查余额、发转账、玩转波场生态。 +- **币安 (BNB Chain) 工具箱**：支持 BSC、以太坊等多链操作。 +- **充值小助手**：帮你远程给 BANK OF AI 账户充值。 -### MCP Server — 链上操作能力 +### 🧠 2. 技能包 (Skills) —— 给 AI 装上"脑子" -MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) 标准接口提供链上操作能力。目前支持两条链的 MCP Server 和一个远程充值服务： +光有手还不行，AI 得知道遇到事情该怎么按步骤处理。技能包就是我们提前写好的"菜谱"。 -| MCP Server | 目标 | 核心能力 | -| :--- | :--- | :--- | -| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | -| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | -| **bankofai-recharge** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | +比如 **"sunswap" 技能**，就是教 AI："当主人说想换币时，你要先去查价格，再算好手续费，最后把账单发给主人确认，绝对不能乱花钱。" -### Skills — 预构建工作流 +--- -Skills 是封装好的业务流程模板。与 MCP Server 提供的单个工具不同，一个 Skill 可以串联多个操作完成完整的任务——比如"在 SunSwap 上兑换代币"涉及查价格、检查余额、执行兑换、确认结果等步骤，一个 Skill 就能搞定。 +## 🌟 装上之后，体验有多爽？ -| Skill | 功能 | -| :--- | :--- | -| **sunswap** | SunSwap DEX 交易——余额查询、报价、兑换、V2/V3 流动性管理 | -| **sunperp-skill** | SunPerp 永续合约交易——行情、下单、仓位管理、杠杆设置、提现 | -| **tronscan-skill** | 通过 TronScan API 查询链上数据（账户、交易、代币、区块、全网统计） | -| **x402-payment** | x402 支付技能，调用付费智能体和付费 API | -| **recharge-skill** | BANK OF AI 余额和订单查询，以及通过 MCP 充值 | +安装完成后，你的 AI 会立刻化身为极其专业的私人 Web3 助理。试试像这样使唤它： +> **"帮我查一下现在 TRON 链上能量费贵不贵？"** +> +> **"100 USDT 在 SunSwap 上能换多少 TRX？算上手续费划算吗？"** +> +> **"我的钱包里还有多少余额？顺便帮我查一下昨天那个土狗币的持仓情况。"** + +它会把枯燥的代码和数据嚼碎了，变成大白话喂给你。 --- -## 适合谁使用？ +## 这适合我吗？ -- **OpenClaw 用户**：想让 AI 助手直接操作区块链，而不想自己手动搭建 MCP Server -- **Web3 开发者**：需要一个快速搭建的链上开发环境，用自然语言调试合约和查询数据 -- **AI Agent 构建者**：需要为自动化代理配备多链操作能力 -- **DeFi 用户**：想通过 AI 助手在 SunSwap 上交易或管理流动性 +- **我是小白玩家**：太棒了！不想折腾代码，只想用大白话让 AI 帮忙查数据、做交易，这就是为你量身定制的。 +- **我是 Web3 老手**：懒得天天开网页连钱包，想拥有一个随叫随到的私人交易助理，它能帮你省下大把盯盘时间。 --- -## 下一步 +## 迫不及待了？ + +别犹豫了，整个安装过程就像用微波炉热个便当一样简单，只需要几分钟。 -- 想立刻体验？ → [快速开始](./QuickStart.md) +👉 **[去快速开始，给你的 AI 升级吧！](./QuickStart.md)** diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md index 8a63a4fa..73590b1d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -1,145 +1,133 @@ # 快速开始 -这个页面的目标是：**让你在几分钟内完成安装，并发起第一次区块链查询。** - -安装程序是交互式的，会引导你选择要安装哪些 MCP Server 和 Skills，然后自动完成所有配置。你只需要按提示操作即可。 +我们的目标是：**花几分钟跟着向导点几下，让你的 AI 成功查到第一笔链上数据。** --- -## 准备工作 - -在运行安装程序之前，确保以下工具已就绪： +## 🕹️ 准备工作 -| 要求 | 说明 | 验证命令 | 下载安装 | -| :--- | :--- | :--- | :--- | -| **OpenClaw** | 你的开源 AI 助手 | 检查 `~/.openclaw` 目录是否存在 |[OpenClaw 官方仓库](https://github.com/openclaw) | -| **Node.js v18+** | 运行 MCP Server 所需 | `node --version` | [Node.js 官方网站](https://nodejs.org/) | -| **Python 3** | 安装程序用于处理 JSON 配置 | `python3 --version` | [Python 官方网站](https://www.python.org/downloads/)| -| **Git** | 克隆 Skills 仓库 | `git --version` | [Git 官方网站](https://git-scm.com/) | +在开始之前，请确保你的电脑上已经装好了这几样基础软件（如果没有，请像装普通软件一样去官网下载安装）： +1. **OpenClaw**：你的 AI 助手软件。 +2. **Node.js**（请务必安装 v20 或以上版本）：这是技能包运行的基础环境。*（极其重要，版本太低一定会报错！）* +3. **Git**：用来下载技能包的小工具。 +4. **Python 3**：安装向导用来处理配置文件的小帮手。 --- -## 运行安装程序 +## 🚀 第一步：一键通关安装 + +打开你电脑上的"终端"（也就是那个黑框框）。 + +- **苹果电脑：** 按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车。 -### 方式一：一键安装（推荐） +把下面这行神奇的代码**完整复制**，粘贴进去，按回车： ```bash curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash ``` -### 方式二：从源码安装 +🚑 **急救包：敲完回车就报错了？** 如果屏幕提示 `command not found: node` 或 `python3`，说明你的电脑缺少上面说的基础环境。👉 [点这里看怎么解决](./FAQ.md#报错里写着-command-not-found-node-或-npm-install-失败) -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +如果没有报错，屏幕上会跳出英文向导。请把它当成一个文字小游戏，整个流程分 4 关： -安装程序启动后，会自动检查环境依赖（Node.js、npx、Git、Python），如果发现缺失会立即提示。 +### 🟢 第 1 关：选安装模式 -如无依赖缺失，进入安装过程，安装过程分为两个主要阶段，每一步都会让你交互式选择。 +屏幕会问你选哪种方式。键盘输入 `1`（普通安装），然后按回车。 这种方式最省心，能保留你以前的设置。 ---- +### 🟢 第 2 关：配置"AI 的专属保险柜"（AgentWallet） -## 安装过程详解 +向导会自动给你装一个叫 AgentWallet 的工具，用来安全存放 AI 的钱包钥匙。 -### 第一阶段：选择并配置 MCP Server +如果你是新手，面对屏幕上的问题，闭着眼睛一路按回车，用默认值就足够了。 -安装程序会列出所有可用的 MCP Server，让你选择要安装哪些： +（🚑 报错卡住了？👉 [点这里看 AgentWallet 安装失败怎么救](./FAQ.md#agentwallet-ai-保险柜安装失败了)） -``` -📦 Available MCP Servers: - 1) mcp-server-tron - TRON blockchain interaction - 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) bankofai-recharge - Remote BANK OF AI recharge MCP +### 🟢 第 3 关：挑选工具箱（给 AI 装"手"） -Select servers to install (e.g., 1,2,3 or 'all'): -``` +屏幕会列出波场 (mcp-server-tron) 等选项。按键盘 `↑` `↓` 方向键移动，按**空格键**打勾，选完后按**回车**确认。 + +⚠️ **前方高能**：向导可能会突然问你要 API Key！ -> **关于 bankofai-recharge**：这是一个远程 MCP，直接连接到 `https://recharge.bankofai.io/mcp`，无需配置本地凭证——安装程序会自动配置好远程端点。 +- **这是啥？** 它是 VIP 通行证，有了它查数据就不卡。 +- **我现在没有怎么办？** 直接按回车跳过！留空完全没关系！ 绝不影响你现在的安装。 -对于每个选中的服务器，安装程序会继续询问凭证存储方式： +### 🟢 第 4 关：挑选技能包（给 AI 装"脑子"） -- **选项 1：保存到配置文件** — 密钥以明文存储在 `~/.mcporter/mcporter.json` 中。方便但安全性较低。 -- **选项 2：使用环境变量（推荐）** — 密钥从系统环境变量读取，不写入任何文件。 +屏幕会列出 sunswap（换币）、tronscan（查数据）等技能。同样按**空格键**打勾，按**回车**确认。 -如果你选择保存到配置文件，安装程序会接着询问具体的密钥值（私钥、API Key 等）。如果选择环境变量，安装程序会告诉你需要设置哪些变量。 +遇到看不懂的密钥索要提示，统统直接按回车跳过。 -> **建议**：如果你只是想快速体验，可以先跳过密钥配置（直接回车留空）。没有私钥时 MCP Server 会以只读模式运行，你仍然可以查询链上数据。 +当屏幕底部亮起 `Installation Complete!` 时——恭喜，通关成功！ + +--- -### 第二阶段：选择并安装 Skills +## 🎉 第二步：重启并见证奇迹 -安装程序会从 GitHub 克隆 [Skills 仓库](https://github.com/BofAI/skills)，自动发现所有可用的 Skill，并让你选择： +安装完成后，有一步绝对不能漏：**彻底关掉你的 OpenClaw 软件，然后重新打开它。** + +🚑 **急救包：AI 像个傻子？** 如果它回答"我不知道什么是 SunSwap"，99% 是因为你刚才没重启。👉 [点这里看怎么彻底重启](./FAQ.md#ai-委屈地说我没有查区块链的工具-或-我不知道什么是-sunswap) + +打开对话框，对你的 AI 发出第一个指令： ``` -🔧 Available Skills: - 1) recharge-skill - BANK OF AI account query and recharge - 2) sunperp-skill - SunPerp perpetual futures trading (TRON) - 3) sunswap - SunSwap DEX trading skill - 4) tronscan-skill - TRON blockchain data lookup - 5) x402-payment - Agent payment protocol (x402) - -Select skills to install (e.g., 1,2,3 or 'all'): +查一下 TRON 主网当前的区块高度。 ``` -然后选择安装位置： - -| 选项 | 路径 | 适用场景 | -| :--- | :--- | :--- | -| **用户级别**（推荐） | `~/.openclaw/skills/` | 所有项目共享 | -| **工作区级别** | `.openclaw/skills/` | 仅当前项目使用 | -| **自定义路径** | 你指定的目录 | 特殊需求 | +如果它思考了几秒钟，然后乖乖给你报出了一串数字——太棒了！你的 AI 已经成功连上了区块链！ -部分 Skill 有额外的凭证需求，安装程序会在安装时逐一提示： +再试一句： -- **recharge-skill** — 需要 BANK OF AI API Key（`BANKOFAI_API_KEY`） -- **sunperp-skill** — 需要 SunPerp API 密钥（`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`） -- **tronscan-skill** — 提示你在 shell 中设置 `TRONSCAN_API_KEY` 环境变量 -- **sunswap** — 提示配置 TRON 私钥（如果前面没有配置） +``` +100 USDT 在 SunSwap 上现在能换多少 TRX？ +``` --- -## 验证安装是否成功 +*（以上是新手必修课。如果你已经玩转了，可以继续往下看👇）* -安装完成后，**重启 OpenClaw**，然后在对话中输入： +--- -``` -查一下 TRON 主网当前的区块高度 -``` +## 🛠️ 事后怎么补填 API Key（VIP 通行证）？ -如果收到正常响应（显示当前区块高度），说明 mcp-server-tron 已成功接入。 +太懂你了！一开始安装只想随便看看，全都按回车跳过了。现在玩熟练了，想填入 API Key 享受"VIP 不限速通道"该怎么做？ -你还可以试试： +### 第一步：弄清楚你需要哪把"钥匙" -``` -查一下 TRON 地址 TXyz... 的 TRX 余额 -``` +| Key 名称 | 它是干嘛的？ | 去哪免费领？ | +| :--- | :--- | :--- | +| `TRONGRID_API_KEY` | 波场工具箱的高速通道，不填会被限速 | [trongrid.io](https://www.trongrid.io/) 免费注册获取 | +| `TRONSCAN_API_KEY` | TronScan 查数据技能必须用到 | [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) 免费申请 | +| `BANKOFAI_API_KEY` | 给 BANK OF AI 充值或查余额用 | [chat.bankofai.io/key](https://chat.bankofai.io/key) 登录后获取 | -``` -TRON 主网当前的能量和带宽价格是多少？ -``` +### 第二步：把钥匙填进系统里 -如果这些查询都能正常返回结果，说明一切就绪。 +拿到对应的 Key 后，根据它的类型，选择下面简单的方法填进去。**填完后千万记得重启 OpenClaw！** -:::info 关于只读模式 -如果你在安装时没有配置私钥，MCP Server 会以只读模式运行——所有查询类操作（查余额、查交易、查合约状态等）都可以正常使用，但转账、合约写入等操作不可用。要解锁写入能力，请参阅 [配置参考](./Configuration.md)。 -::: +#### 🔧 A 类钥匙：填入"隐形便签"（适用于 TRONGRID 和 TRONSCAN） ---- +1. 在终端输入 `open -e ~/.zshrc` 并回车。 +2. 在弹出的记事本最下方，粘贴这行代码（注意保留双引号 `""`）： + ``` + export TRONGRID_API_KEY="你的TronGrid_Key填在这里" + export TRONSCAN_API_KEY="你的TronScan_Key填在这里" + ``` +3. 按 `Command + S` 保存关闭，然后重新打开终端或重启 OpenClaw 即可生效。 -## 遇到问题？ +#### 🔧 B 类钥匙：一键生成配置文件（适用于 BANK OF AI） -如果安装后 AI 助手无法识别区块链工具，常见原因包括： +如果你拿到了这把钥匙，直接在终端（黑框框）里复制并运行下面的整段代码即可（记得把中文部分替换成你的真实 Key）： -- **没有重启 OpenClaw** — 修改配置后必须完全重启 -- **Node.js 版本太低** — 确保 v18.0.0 或更高 -- **mcporter.json 格式错误** — 可以用 `python3 -m json.tool ~/.mcporter/mcporter.json` 检查 +**配置 BANK OF AI：** -更多排查方法请参阅 [常见问题](./FAQ.md)。 +```bash +mkdir -p ~/.mcporter && echo '{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://api.bankofai.io/v1/"}' > ~/.mcporter/bankofai-config.json +``` --- -## 下一步 +## 还有其他卡壳的地方？ + +这很正常！每个人的电脑环境都不一样。 -- 遇到问题？ → [常见问题](./FAQ.md) +去看看 👉 **[常见问题（救火指南）](./FAQ.md)**，99% 的奇葩坑我们都已经帮你踩过，并写好解法了。 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 c154bf8f..1edc900e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -148,6 +148,26 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Agent Wallet', + collapsed: false, + items: [ + 'Agent-Wallet/Intro', + 'Agent-Wallet/QuickStart', + { + type: 'category', + label: '进一步探索', + collapsed: true, + items: [ + 'Agent-Wallet/Developer/CLI-Reference', + 'Agent-Wallet/Developer/SDK-Guide', + 'Agent-Wallet/Developer/SDK-Cookbook', + ], + }, + 'Agent-Wallet/FAQ', + ], + }, { type: 'category', label: 'Openclaw 扩展插件', diff --git a/package.json b/package.json index 300615c9..5f00a0d0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.2.3", + "version": "1.2.4", "description": "x402-tron documentation", "license": "MIT", "scripts": { diff --git a/sidebars.js b/sidebars.js index 8c6b3e56..96a41ef4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -138,12 +138,33 @@ const sidebars = { collapsed: false, items: [ 'McpServer-Skills/SKILLS/Intro', + 'McpServer-Skills/SKILLS/QuickStart', 'McpServer-Skills/SKILLS/BANKOFAISkill', 'McpServer-Skills/SKILLS/Faq', ], }, ], }, + { + type: 'category', + label: 'Agent Wallet', + collapsed: false, + items: [ + 'Agent-Wallet/Intro', + 'Agent-Wallet/QuickStart', + { + type: 'category', + label: 'Explore Further', + collapsed: true, + items: [ + 'Agent-Wallet/Developer/CLI-Reference', + 'Agent-Wallet/Developer/SDK-Guide', + 'Agent-Wallet/Developer/SDK-Cookbook', + ], + }, + 'Agent-Wallet/FAQ', + ], + }, { type: 'category', label: 'Openclaw Extension',